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 2007-05-18 "" "Linux Programmer's Manual"
   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 envz_add(char **" envz ", size_t *" envz_len ,
  16 .ti 20n
  17 .BI "const char *" name ", const char *" value );
  18 .sp
  19 .BI "char *envz_entry(const char *" envz ", size_t *" envz_len \
  20 ", const char *" name );
  21 .sp
  22 .BI "char *envz_get(const char *" envz ", size_t *" envz_len \
  23 ", const char *" name );
  24 .sp
  25 .BI "error_t envz_merge(char **" envz ", size_t *" envz_len ,
  26 .ti 20n
  27 .BI "const char *" envz2 ", size_t " envz2_len ", int " override );
  28 .sp
  29 .BI "void envz_remove(char **" envz ", size_t *" envz_len \
  30 ", const char *" name );
  31 .sp
  32 .BI "void envz_strip(char **" envz ", size_t *" envz_len );
  33 .fi
  34 .SH DESCRIPTION
  35 These functions are glibc-specific.
  36 .LP
  37 An argz vector is a pointer to a character buffer together with a length,
  38 see
  39 .BR argz_add (3).
  40 An envz vector is a special argz vector, namely one where the strings
  41 have the form "name=value".
  42 Everything after the first '=' is considered
  43 to be the value.
  44 If there is no '=', the value is taken to be NULL.
  45 (While the value in case of a trailing '=' is the empty string "".)
  46 .LP
  47 These functions are for handling envz vectors.
  48 .LP
  49 .BR envz_add ()
  50 adds the string
  51 .RI \&" name = value \&"
  52 (in case
  53 .I value
  54 is non-NULL) or
  55 .RI \&" name \&"
  56 (in case
  57 .I value
  58 is NULL) to the envz vector
  59 .RI ( *envz ,\  *envz_len )
  60 and updates
  61 .I *envz
  62 and
  63 .IR *envz_len .
  64 If an entry with the same
  65 .I name
  66 existed, it is removed.
  67 .LP
  68 .BR envz_entry ()
  69 looks for
  70 .I name
  71 in the envz vector
  72 .RI ( envz ,\  envz_len )
  73 and returns the entry if found, or NULL if not.
  74 .LP
  75 .BR envz_get ()
  76 looks for
  77 .I name
  78 in the envz vector
  79 .RI ( envz ,\  envz_len )
  80 and returns the value if found, or NULL if not.
  81 (Note that the value can also be NULL, namely when there is
  82 an entry for
  83 .I name
  84 without '=' sign.)
  85 .LP
  86 .BR envz_merge ()
  87 adds each entry in
  88 .I envz2
  89 to
  90 .IR *envz ,
  91 as if with
  92 .BR envz_add ().
  93 If
  94 .I override
  95 is true, then values in
  96 .I envz2
  97 will supersede those with the same name in
  98 .IR *envz ,
  99 otherwise not.
 100 .LP
 101 .BR envz_remove ()
 102 removes the entry for
 103 .I name
 104 from
 105 .RI ( *envz ,\  *envz_len )
 106 if there was one.
 107 .LP
 108 .BR envz_strip ()
 109 removes all entries with value NULL.
 110 .SH "RETURN VALUE"
 111 All envz functions that do memory allocation have a return type of
 112 \fIerror_t\fP, and return 0 for success, and \fBENOMEM\fP
 113 if an allocation error occurs.
 114 .SH "CONFORMING TO"
 115 These functions are a GNU extension.
 116 Handle with care.
 117 .SH EXAMPLE
 118 .sp
 119 .nf
 120 #include <stdio.h>
 121 #include <stdlib.h>
 122 #include <envz.h>
 123
 124 int
 125 main(int argc, char *argv[], char *envp[])
 126 {
 127     int i, e_len = 0;
 128     char *str;
 129
 130     for (i=0; envp[i] != NULL; i++)
 131         e_len += strlen(envp[i]) + 1;
 132
 133     str = envz_entry(*envp, e_len, "HOME");
 134     printf("%s\en", str);
 135     str = envz_get(*envp, e_len, "HOME");
 136     printf("%s\en", str);
 137     exit(EXIT_SUCCESS);
 138 }
 139 .fi
 140 .SH "SEE ALSO"
 141 .BR argz_add (3)