man3/envz_add.3

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