Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 168 insertions, 0 deletions

diff --git a/man/man3/envz_add.3 b/man/man3/envz_add.3
new file mode 100644
index 0000000..888fc07
--- /dev/null
+++ b/man/man3/envz_add.3
@@ -0,0 +1,168 @@
+'\" t
+.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de)
+.\"
+.\" SPDX-License-Identifier: GPL-1.0-or-later
+.\"
+.\" based on the description in glibc source and infopages
+.\"
+.\" Corrections and additions, aeb
+.TH envz_add 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+envz_add, envz_entry, envz_get, envz_merge,
+envz_remove, envz_strip \- environment string support
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <envz.h>
+.P
+.BI "error_t envz_add(char **restrict " envz ", size_t *restrict " envz_len ,
+.BI "               const char *restrict " name \
+", const char *restrict " value );
+.P
+.BI "char *envz_entry(const char *restrict " envz ", size_t " envz_len ,
+.BI "               const char *restrict " name );
+.P
+.BI "char *envz_get(const char *restrict " envz ", size_t " envz_len ,
+.BI "               const char *restrict " name );
+.P
+.BI "error_t envz_merge(char **restrict " envz ", size_t *restrict " envz_len ,
+.BI "               const char *restrict " envz2 ", size_t " envz2_len ,
+.BI "               int " override );
+.P
+.BI "void envz_remove(char **restrict " envz ", size_t *restrict " envz_len ,
+.BI "               const char *restrict " name );
+.P
+.BI "void envz_strip(char **restrict " envz ", size_t *restrict " envz_len );
+.fi
+.SH DESCRIPTION
+These functions are glibc-specific.
+.P
+An argz vector is a pointer to a character buffer together with a length,
+see
+.BR argz_add (3).
+An envz vector is a special argz vector, namely one where the strings
+have the form "name=value".
+Everything after the first \[aq]=\[aq] is considered
+to be the value.
+If there is no \[aq]=\[aq], the value is taken to be NULL.
+(While the value in case of a trailing \[aq]=\[aq] is the empty string "".)
+.P
+These functions are for handling envz vectors.
+.P
+.BR envz_add ()
+adds the string
+.RI \&" name = value \&"
+(in case
+.I value
+is non-NULL) or
+.RI \&" name \&"
+(in case
+.I value
+is NULL) to the envz vector
+.RI ( *envz ,\  *envz_len )
+and updates
+.I *envz
+and
+.IR *envz_len .
+If an entry with the same
+.I name
+existed, it is removed.
+.P
+.BR envz_entry ()
+looks for
+.I name
+in the envz vector
+.RI ( envz ,\  envz_len )
+and returns the entry if found, or NULL if not.
+.P
+.BR envz_get ()
+looks for
+.I name
+in the envz vector
+.RI ( envz ,\  envz_len )
+and returns the value if found, or NULL if not.
+(Note that the value can also be NULL, namely when there is
+an entry for
+.I name
+without \[aq]=\[aq] sign.)
+.P
+.BR envz_merge ()
+adds each entry in
+.I envz2
+to
+.IR *envz ,
+as if with
+.BR envz_add ().
+If
+.I override
+is true, then values in
+.I envz2
+will supersede those with the same name in
+.IR *envz ,
+otherwise not.
+.P
+.BR envz_remove ()
+removes the entry for
+.I name
+from
+.RI ( *envz ,\  *envz_len )
+if there was one.
+.P
+.BR envz_strip ()
+removes all entries with value NULL.
+.SH RETURN VALUE
+All envz functions that do memory allocation have a return type of
+.I error_t
+(an integer type),
+and return 0 for success, and
+.B ENOMEM
+if an allocation error occurs.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR envz_add (),
+.BR envz_entry (),
+.BR envz_get (),
+.BR envz_merge (),
+.BR envz_remove (),
+.BR envz_strip ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+GNU.
+.SH EXAMPLES
+.\" SRC BEGIN (envz_add.c)
+.EX
+#include <envz.h>
+#include <stdio.h>
+#include <stdlib.h>
+\&
+int
+main(int argc, char *argv[], char *envp[])
+{
+    char    *str;
+    size_t  e_len = 0;
+\&
+    for (size_t i = 0; envp[i] != NULL; i++)
+        e_len += strlen(envp[i]) + 1;
+\&
+    str = envz_entry(*envp, e_len, "HOME");
+    printf("%s\en", str);
+    str = envz_get(*envp, e_len, "HOME");
+    printf("%s\en", str);
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR argz_add (3)