man3/envz_add.3

   1 .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de)
   2 .\" Distributed under GPL
   3 .\" based on the description in glibc source and infopages
   4 .\"
   5 .\" Corrections and additions, aeb
   6 .TH ENVZ_ADD 3
   7 .SH NAME
   8 envz_add, envz_entry, envz_get, envz_merge,
   9 envz_remove, envz_strip \- environment string support
  10 .SH SYNOPSIS
  11 .nf
  12 .sp
  13 .B "#include <envz.h>"
  14 .sp
  15 .BI "error_t"
  16 .BI "envz_add(char **" envz ", size_t *" envz_len ,
  17 .ti 16n
  18 .BI "const char *" name ", const char *" value );
  19 .sp
  20 .BI "char *"
  21 .BI "envz_entry(const char *" envz ", size_t *" envz_len ", const char *" name );
  22 .sp
  23 .BI "char *"
  24 .BI "envz_get(const char *" envz ", size_t *" envz_len ", const char *" name );
  25 .sp
  26 .BI "error_t"
  27 .BI "envz_merge(char **" envz ", size_t *" envz_len ,
  28 .ti 16n
  29 .BI "const char *" envz2 ", size_t " envz2_len ", int " override );
  30 .sp
  31 .BI "void"
  32 .BI "envz_remove(char **" envz ", size_t *" envz_len ", const char *" name );
  33 .sp
  34 .BI "void"
  35 .BI "envz_strip(char **" envz ", size_t *" envz_len );
  36 .SH DESCRIPTION
  37 These functions are glibc-specific.
  38 .LP
  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 '=' is considered
  45 to be the value.
  46 If there is no '=', the value is taken to be NULL.
  47 (While the value in case of a trailing '=' is the empty string "".)
  48 .LP
  49 These functions are for handling envz vectors.
  50 .LP
  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 .RI * envz
  64 and
  65 .RI * envz_len .
  66 If an entry with the same
  67 .I name
  68 existed, it is removed.
  69 .LP
  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 .LP
  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 '=' sign.)
  87 .LP
  88 .BR envz_merge ()
  89 adds each entry in
  90 .I envz2
  91 to
  92 .RI * 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 .RI * envz ,
 101 otherwise not.
 102 .LP
 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 .LP
 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 \fIerror_t\fP, and return 0 for success, and \fBENOMEM\fP
 115 if an allocation error occurs.
 116 .SH EXAMPLE
 117 .sp
 118 .nf
 119 #include <stdio.h>
 120 #include <envz.h>
 121
 122 int
 123 main(int argc, char *argv[], char *envp[])
 124 {
 125     int i, e_len = 0;
 126     char *str;
 127
 128     for (i=0; envp[i] != NULL; i++)
 129         e_len += strlen(envp[i]) + 1;
 130
 131     str = envz_entry(*envp, e_len, "HOME");
 132     printf("%s\en", str);
 133     str = envz_get(*envp, e_len, "HOME");
 134     printf("%s\en", str);
 135     return 0;
 136 }
 137 .fi
 138 .SH "CONFORMING TO"
 139 These functions are a GNU extension.
 140 Handle with care.
 141 .SH "SEE ALSO"
 142 .BR argz (3)