original/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 2014-05-28 "" "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
  18 .BI "error_t envz_add(char **" envz ", size_t *" envz_len ,
  19 .BI "                 const char *" name ", const char *" value );
  20
  21 .BI "char *envz_entry(const char *" envz ", size_t " envz_len \
  22 ", const char *" name );
  23
  24 .BI "char *envz_get(const char *" envz ", size_t " envz_len \
  25 ", const char *" name );
  26
  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
  31 .BI "void envz_remove(char **" envz ", size_t *" envz_len \
  32 ", const char *" name );
  33
  34 .BI "void envz_strip(char **" envz ", size_t *" envz_len );
  35 .fi
  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 \(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 .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 .I *envz
  64 and
  65 .IR *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 \(aq=\(aq sign.)
  87 .LP
  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 .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 .IR error_t ,
 115 and return 0 for success, and
 116 .B ENOMEM
 117 if an allocation error occurs.
 118 .SH CONFORMING TO
 119 These functions are a GNU extension.
 120 Handle with care.
 121 .SH EXAMPLE
 122 .nf
 123 #include <stdio.h>
 124 #include <stdlib.h>
 125 #include <envz.h>
 126
 127 int
 128 main(int argc, char *argv[], char *envp[])
 129 {
 130     int i, e_len = 0;
 131     char *str;
 132
 133     for (i = 0; envp[i] != NULL; i++)
 134         e_len += strlen(envp[i]) + 1;
 135
 136     str = envz_entry(*envp, e_len, "HOME");
 137     printf("%s\en", str);
 138     str = envz_get(*envp, e_len, "HOME");
 139     printf("%s\en", str);
 140     exit(EXIT_SUCCESS);
 141 }
 142 .fi
 143 .SH SEE ALSO
 144 .BR argz_add (3)
 145 .SH COLOPHON
 146 This page is part of release 3.68 of the Linux
 147 .I man-pages
 148 project.
 149 A description of the project,
 150 information about reporting bugs,
 151 and the latest version of this page,
 152 can be found at
 153 \%http://www.kernel.org/doc/man\-pages/.