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