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