diff options
| author | Alejandro Colomar <alx.manpages@gmail.com> | 2022-09-05 23:03:38 +0200 |
|---|---|---|
| committer | Alejandro Colomar <alx.manpages@gmail.com> | 2022-09-05 23:03:47 +0200 |
| commit | 70ac1c4785fc1e158ab2349a962dba2526bf4fbc (patch) | |
| tree | bff270e2496dd284bccfc1271b43946f5d225224 /man/man3/envz_add.3 | |
| parent | 5423a6f86b2b920a5f3e8cf8d759b513050f2d33 (diff) | |
| download | man-pages-70ac1c4785fc1e158ab2349a962dba2526bf4fbc.tar.gz | |
src.mk, All pages: Move man* to man/
The root of the repository is becoming a bit overpopulated and
unorganized, due to the recent addition of more mandirs, and more
informative and configuration files too. Let's create a specific
mandir <man/> that contains the mandirs <man[1-8]*>.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Diffstat (limited to 'man/man3/envz_add.3')
| -rw-r--r-- | man/man3/envz_add.3 | 168 |
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 0000000000..6c31424f62 --- /dev/null +++ b/man/man3/envz_add.3 @@ -0,0 +1,168 @@ +.\" 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 2021-03-22 "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> +.PP +.BI "error_t envz_add(char **restrict " envz ", size_t *restrict " envz_len , +.BI " const char *restrict " name \ +", const char *restrict " value ); +.PP +.BI "char *envz_entry(const char *restrict " envz ", size_t " envz_len , +.BI " const char *restrict " name ); +.PP +.BI "char *envz_get(const char *restrict " envz ", size_t " envz_len , +.BI " const char *restrict " name ); +.PP +.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 ); +.PP +.BI "void envz_remove(char **restrict " envz ", size_t *restrict " envz_len , +.BI " const char *restrict " name ); +.PP +.BI "void envz_strip(char **restrict " envz ", size_t *restrict " envz_len ); +.fi +.SH DESCRIPTION +These functions are glibc-specific. +.PP +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 "".) +.PP +These functions are for handling envz vectors. +.PP +.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. +.PP +.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. +.PP +.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.) +.PP +.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. +.PP +.BR envz_remove () +removes the entry for +.I name +from +.RI ( *envz ,\ *envz_len ) +if there was one. +.PP +.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). +.ad l +.nh +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.BR envz_add (), +.BR envz_entry (), +.BR envz_get (), +.BR envz_merge (), +.BR envz_remove (), +.BR envz_strip () +T} Thread safety MT-Safe +.TE +.hy +.ad +.sp 1 +.SH STANDARDS +These functions are a GNU extension. +.SH EXAMPLES +.EX +#include <stdio.h> +#include <stdlib.h> +#include <envz.h> + +int +main(int argc, char *argv[], char *envp[]) +{ + int e_len = 0; + char *str; + + for (int 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 +.SH SEE ALSO +.BR argz_add (3) |