man3/envz_add.3

   1 .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de)
   2 .\"
   3 .\" SPDX-License-Identifier: GPL-1.0-or-later
   4 .\"
   5 .\" based on the description in glibc source and infopages
   6 .\"
   7 .\" Corrections and additions, aeb
   8 .TH ENVZ_ADD 3 2021-03-22 GNU "Linux Programmer's Manual"
   9 .SH NAME
  10 envz_add, envz_entry, envz_get, envz_merge,
  11 envz_remove, envz_strip \- environment string support
  12 .SH LIBRARY
  13 Standard C library
  14 .RI ( libc ", " \-lc )
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <envz.h>
  18 .PP
  19 .BI "error_t envz_add(char **restrict " envz ", size_t *restrict " envz_len ,
  20 .BI "               const char *restrict " name \
  21 ", const char *restrict " value );
  22 .PP
  23 .BI "char *envz_entry(const char *restrict " envz ", size_t " envz_len ,
  24 .BI "               const char *restrict " name );
  25 .PP
  26 .BI "char *envz_get(const char *restrict " envz ", size_t " envz_len ,
  27 .BI "               const char *restrict " name );
  28 .PP
  29 .BI "error_t envz_merge(char **restrict " envz ", size_t *restrict " envz_len ,
  30 .BI "               const char *restrict " envz2 ", size_t " envz2_len ,
  31 .BI "               int " override );
  32 .PP
  33 .BI "void envz_remove(char **restrict " envz ", size_t *restrict " envz_len ,
  34 .BI "               const char *restrict " name );
  35 .PP
  36 .BI "void envz_strip(char **restrict " envz ", size_t *restrict " envz_len );
  37 .fi
  38 .SH DESCRIPTION
  39 These functions are glibc-specific.
  40 .PP
  41 An argz vector is a pointer to a character buffer together with a length,
  42 see
  43 .BR argz_add (3).
  44 An envz vector is a special argz vector, namely one where the strings
  45 have the form "name=value".
  46 Everything after the first \(aq=\(aq is considered
  47 to be the value.
  48 If there is no \(aq=\(aq, the value is taken to be NULL.
  49 (While the value in case of a trailing \(aq=\(aq is the empty string "".)
  50 .PP
  51 These functions are for handling envz vectors.
  52 .PP
  53 .BR envz_add ()
  54 adds the string
  55 .RI \&" name = value \&"
  56 (in case
  57 .I value
  58 is non-NULL) or
  59 .RI \&" name \&"
  60 (in case
  61 .I value
  62 is NULL) to the envz vector
  63 .RI ( *envz ,\  *envz_len )
  64 and updates
  65 .I *envz
  66 and
  67 .IR *envz_len .
  68 If an entry with the same
  69 .I name
  70 existed, it is removed.
  71 .PP
  72 .BR envz_entry ()
  73 looks for
  74 .I name
  75 in the envz vector
  76 .RI ( envz ,\  envz_len )
  77 and returns the entry if found, or NULL if not.
  78 .PP
  79 .BR envz_get ()
  80 looks for
  81 .I name
  82 in the envz vector
  83 .RI ( envz ,\  envz_len )
  84 and returns the value if found, or NULL if not.
  85 (Note that the value can also be NULL, namely when there is
  86 an entry for
  87 .I name
  88 without \(aq=\(aq sign.)
  89 .PP
  90 .BR envz_merge ()
  91 adds each entry in
  92 .I envz2
  93 to
  94 .IR *envz ,
  95 as if with
  96 .BR envz_add ().
  97 If
  98 .I override
  99 is true, then values in
 100 .I envz2
 101 will supersede those with the same name in
 102 .IR *envz ,
 103 otherwise not.
 104 .PP
 105 .BR envz_remove ()
 106 removes the entry for
 107 .I name
 108 from
 109 .RI ( *envz ,\  *envz_len )
 110 if there was one.
 111 .PP
 112 .BR envz_strip ()
 113 removes all entries with value NULL.
 114 .SH RETURN VALUE
 115 All envz functions that do memory allocation have a return type of
 116 .I error_t
 117 (an integer type),
 118 and return 0 for success, and
 119 .B ENOMEM
 120 if an allocation error occurs.
 121 .SH ATTRIBUTES
 122 For an explanation of the terms used in this section, see
 123 .BR attributes (7).
 124 .ad l
 125 .nh
 126 .TS
 127 allbox;
 128 lbx lb lb
 129 l l l.
 130 Interface       Attribute       Value
 131 T{
 132 .BR envz_add (),
 133 .BR envz_entry (),
 134 .BR envz_get (),
 135 .BR envz_merge (),
 136 .BR envz_remove (),
 137 .BR envz_strip ()
 138 T}      Thread safety   MT-Safe
 139 .TE
 140 .hy
 141 .ad
 142 .sp 1
 143 .SH CONFORMING TO
 144 These functions are a GNU extension.
 145 .SH EXAMPLES
 146 .EX
 147 #include <stdio.h>
 148 #include <stdlib.h>
 149 #include <envz.h>
 150
 151 int
 152 main(int argc, char *argv[], char *envp[])
 153 {
 154     int e_len = 0;
 155     char *str;
 156
 157     for (int i = 0; envp[i] != NULL; i++)
 158         e_len += strlen(envp[i]) + 1;
 159
 160     str = envz_entry(*envp, e_len, "HOME");
 161     printf("%s\en", str);
 162     str = envz_get(*envp, e_len, "HOME");
 163     printf("%s\en", str);
 164     exit(EXIT_SUCCESS);
 165 }
 166 .EE
 167 .SH SEE ALSO
 168 .BR argz_add (3)