| .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) |
| .\" |
| .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) |
| .\" Distributed under GPL |
| .\" %%%LICENSE_END |
| .\" |
| .\" based on the description in glibc source and infopages |
| .\" |
| .\" Corrections and additions, aeb |
| .TH ENVZ_ADD 3 2021-03-22 "" "Linux Programmer's Manual" |
| .SH NAME |
| envz_add, envz_entry, envz_get, envz_merge, |
| envz_remove, envz_strip \- environment string support |
| .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 |
| .IR 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 CONFORMING TO |
| 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) |