man3/envz_add.3

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