diff options
Diffstat (limited to 'upstream/fedora-rawhide/man3/envz_add.3')
| -rw-r--r-- | upstream/fedora-rawhide/man3/envz_add.3 | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/upstream/fedora-rawhide/man3/envz_add.3 b/upstream/fedora-rawhide/man3/envz_add.3 new file mode 100644 index 00000000..4d892578 --- /dev/null +++ b/upstream/fedora-rawhide/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 2023-10-31 "Linux man-pages 6.06" +.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) |