diff options
| -rw-r--r-- | libsimple/env.h | 100 | ||||
| l--------- | man/enputenvf.3libsimple | 1 | ||||
| l--------- | man/envputenvf.3libsimple | 1 | ||||
| l--------- | man/eputenvf.3libsimple | 1 | ||||
| l--------- | man/evputenvf.3libsimple | 1 | ||||
| l--------- | man/getenv_e.3libsimple | 1 | ||||
| l--------- | man/getenv_ne.3libsimple | 1 | ||||
| l--------- | man/libsimple_enputenvf.3 | 1 | ||||
| l--------- | man/libsimple_envputenvf.3 | 1 | ||||
| l--------- | man/libsimple_eputenvf.3 | 1 | ||||
| l--------- | man/libsimple_evputenvf.3 | 1 | ||||
| -rw-r--r-- | man/libsimple_getenv_e.3 | 74 | ||||
| -rw-r--r-- | man/libsimple_getenv_ne.3 | 82 | ||||
| l--------- | man/libsimple_putenvf.3 | 1 | ||||
| -rw-r--r-- | man/libsimple_vputenvf.3 | 197 | ||||
| l--------- | man/putenvf.3libsimple | 1 | ||||
| l--------- | man/vputenvf.3libsimple | 1 |
17 files changed, 466 insertions, 0 deletions
diff --git a/libsimple/env.h b/libsimple/env.h index 1c10a75..e97c65f 100644 --- a/libsimple/env.h +++ b/libsimple/env.h @@ -1,5 +1,6 @@ /* See LICENSE file for copyright and license details. */ + /** * Read an environment variable, but handle it as undefined if empty * @@ -17,6 +18,7 @@ libsimple_getenv_ne(const char *__name) # define getenv_ne libsimple_getenv_ne #endif + /** * Read an environment variable, but handle it as empty if undefined * @@ -34,12 +36,40 @@ libsimple_getenv_e(const char *__name) # define getenv_e libsimple_getenv_e #endif + +/** + * Formats a string and adds its as an environment variable, + * overriding its old value if it already exists + * + * The constructed string should have the format name=value, + * however, it is possible to add environment variables with + * only the name, but this can couse problems in some programs + * and should not done; the name however must not be empty + * + * @param fmt Format string, see vsprintf(3) + * @param ap Format arguments, see vsprintf(3) + * @return 0 on success, -1 on failure + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__))) int libsimple_vputenvf(const char *, va_list); #ifndef vputenvf # define vputenvf libsimple_vputenvf #endif + +/** + * Formats a string and adds its as an environment variable, + * overriding its old value if it already exists + * + * The constructed string should have the format name=value, + * however, it is possible to add environment variables with + * only the name, but this can couse problems in some programs + * and should not done; the name however must not be empty + * + * @param fmt Format string, see vsprintf(3) + * @param ... Format arguments, see vsprintf(3) + * @return 0 on success, -1 on failure + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__, __format__(__printf__, 1, 2)))) static inline int libsimple_putenvf(const char *__fmt, ...) @@ -53,12 +83,48 @@ libsimple_putenvf(const char *__fmt, ...) # define putenvf libsimple_putenvf #endif + +/** + * Formats a string and adds its as an environment variable, + * overriding its old value if it already exists + * + * The constructed string should have the format name=value, + * however, it is possible to add environment variables with + * only the name, but this can couse problems in some programs + * and should not done; the name however must not be empty + * + * On failure, the libsimple_enprintf function is called, + * cause the program to print an error message and exit, + * see libsimple_enprintf for more information + * + * @param status The exit value for the process in case of failure + * @param fmt Format string, see vsprintf(3) + * @param ap Format arguments, see vsprintf(3) + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__))) void libsimple_envputenvf(int, const char *, va_list); #ifndef envputenvf # define envputenvf libsimple_envputenvf #endif + +/** + * Formats a string and adds its as an environment variable, + * overriding its old value if it already exists + * + * The constructed string should have the format name=value, + * however, it is possible to add environment variables with + * only the name, but this can couse problems in some programs + * and should not done; the name however must not be empty + * + * On failure, the libsimple_enprintf function is called, + * cause the program to print an error message and exit, + * see libsimple_enprintf for more information + * + * @param status The exit value for the process in case of failure + * @param fmt Format string, see vsprintf(3) + * @param ap Format arguments, see vsprintf(3) + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__, __format__(__printf__, 2, 3)))) static inline void libsimple_enputenvf(int __status, const char *__fmt, ...) @@ -72,6 +138,23 @@ libsimple_enputenvf(int __status, const char *__fmt, ...) # define enputenvf libsimple_enputenvf #endif + +/** + * Formats a string and adds its as an environment variable, + * overriding its old value if it already exists + * + * The constructed string should have the format name=value, + * however, it is possible to add environment variables with + * only the name, but this can couse problems in some programs + * and should not done; the name however must not be empty + * + * On failure, the libsimple_eprintf function is called, + * cause the program to print an error message and exit, + * see libsimple_eprintf for more information + * + * @param fmt Format string, see vsprintf(3) + * @param ap Format arguments, see vsprintf(3) + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__))) static inline void libsimple_evputenvf(const char *__fmt, va_list __ap) { libsimple_envputenvf(libsimple_default_failure_exit, __fmt, __ap); } @@ -79,6 +162,23 @@ static inline void libsimple_evputenvf(const char *__fmt, va_list __ap) # define evputenvf libsimple_evputenvf #endif + +/** + * Formats a string and adds its as an environment variable, + * overriding its old value if it already exists + * + * The constructed string should have the format name=value, + * however, it is possible to add environment variables with + * only the name, but this can couse problems in some programs + * and should not done; the name however must not be empty + * + * On failure, the libsimple_eprintf function is called, + * cause the program to print an error message and exit, + * see libsimple_eprintf for more information + * + * @param fmt Format string, see vsprintf(3) + * @param ap Format arguments, see vsprintf(3) + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__, __format__(__printf__, 1, 2)))) static inline void libsimple_eputenvf(const char *__fmt, ...) diff --git a/man/enputenvf.3libsimple b/man/enputenvf.3libsimple new file mode 120000 index 0000000..640377b --- /dev/null +++ b/man/enputenvf.3libsimple @@ -0,0 +1 @@ +libsimple_enputenvf.3
\ No newline at end of file diff --git a/man/envputenvf.3libsimple b/man/envputenvf.3libsimple new file mode 120000 index 0000000..1b96365 --- /dev/null +++ b/man/envputenvf.3libsimple @@ -0,0 +1 @@ +libsimple_envputenvf.3
\ No newline at end of file diff --git a/man/eputenvf.3libsimple b/man/eputenvf.3libsimple new file mode 120000 index 0000000..f1831a3 --- /dev/null +++ b/man/eputenvf.3libsimple @@ -0,0 +1 @@ +libsimple_eputenvf.3
\ No newline at end of file diff --git a/man/evputenvf.3libsimple b/man/evputenvf.3libsimple new file mode 120000 index 0000000..9982fa0 --- /dev/null +++ b/man/evputenvf.3libsimple @@ -0,0 +1 @@ +libsimple_evputenvf.3
\ No newline at end of file diff --git a/man/getenv_e.3libsimple b/man/getenv_e.3libsimple new file mode 120000 index 0000000..8e09a17 --- /dev/null +++ b/man/getenv_e.3libsimple @@ -0,0 +1 @@ +libsimple_getenv_e.3
\ No newline at end of file diff --git a/man/getenv_ne.3libsimple b/man/getenv_ne.3libsimple new file mode 120000 index 0000000..457043f --- /dev/null +++ b/man/getenv_ne.3libsimple @@ -0,0 +1 @@ +libsimple_getenv_ne.3
\ No newline at end of file diff --git a/man/libsimple_enputenvf.3 b/man/libsimple_enputenvf.3 new file mode 120000 index 0000000..1b96365 --- /dev/null +++ b/man/libsimple_enputenvf.3 @@ -0,0 +1 @@ +libsimple_envputenvf.3
\ No newline at end of file diff --git a/man/libsimple_envputenvf.3 b/man/libsimple_envputenvf.3 new file mode 120000 index 0000000..ce0929f --- /dev/null +++ b/man/libsimple_envputenvf.3 @@ -0,0 +1 @@ +libsimple_vputenvf.3
\ No newline at end of file diff --git a/man/libsimple_eputenvf.3 b/man/libsimple_eputenvf.3 new file mode 120000 index 0000000..9982fa0 --- /dev/null +++ b/man/libsimple_eputenvf.3 @@ -0,0 +1 @@ +libsimple_evputenvf.3
\ No newline at end of file diff --git a/man/libsimple_evputenvf.3 b/man/libsimple_evputenvf.3 new file mode 120000 index 0000000..1b96365 --- /dev/null +++ b/man/libsimple_evputenvf.3 @@ -0,0 +1 @@ +libsimple_envputenvf.3
\ No newline at end of file diff --git a/man/libsimple_getenv_e.3 b/man/libsimple_getenv_e.3 new file mode 100644 index 0000000..ba9cd04 --- /dev/null +++ b/man/libsimple_getenv_e.3 @@ -0,0 +1,74 @@ +.\" -*- nroff -*- +.TH LIBSIMPLE_GETENV_E 3 2018-10-20 libsimple +.SH NAME +libsimple_getenv_e \- get value of an environment variable or the empty string +.SH SYNOPSIS +.nf +#include <libsimple.h> + +static inline const char *libsimple_getenv_e(const char *\fIname\fP); + +#ifndef getenv_e +# define getenv_e libsimple_getenv_e +#endif +.fi + +Link with +.IR \-lsimple . +.SH DESCRIPTION +The +.BR libsimple_getenv_e () +function searches the environment of the calling +process for the environment variable +.IR name . +If it exists, its value is returned. If it does +not exist, the empty string is returned. +.PP +Modifications to the environment variable made from +within the process, its parent, or other ancestor, +that have not be come visible to other process via +replacement of the process image, are visible to the +.BR libsimple_getenv_e () +function. +.SH RETURN VALUE +If the environment variable +.I name +is defined, its value is returned, otherwise the +empty string is returned. +.SH ERRORS +The +.BR libsimple_getenv_e () +function cannot fail. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR libsimple_getenv_e () +T} Thread safety MT-Safe env +T{ +.BR libsimple_getenv_e () +T} Async-signal safety AS-Safe +T{ +.BR libsimple_getenv_e () +T} Async-cancel safety AC-Safe +.TE +.SH EXAMPLES +None. +.SH APPLICATION USAGE +None. +.SH RATIONALE +None. +.SH FUTURE DIRECTIONS +None. +.SH NOTES +None. +.SH BUGS +None. +.SH SEE ALSO +.BR libsimple_getenv_ne (3), +.BR getenv (3) diff --git a/man/libsimple_getenv_ne.3 b/man/libsimple_getenv_ne.3 new file mode 100644 index 0000000..337a5f5 --- /dev/null +++ b/man/libsimple_getenv_ne.3 @@ -0,0 +1,82 @@ +.\" -*- nroff -*- +.TH LIBSIMPLE_GETENV_NE 3 2018-10-20 libsimple +.SH NAME +libsimple_getenv_ne \- get non-empty value of an environment variable +.SH SYNOPSIS +.nf +#include <libsimple.h> + +static inline char *libsimple_getenv_ne(const char *\fIname\fP); + +#ifndef getenv_ne +# define getenv_ne libsimple_getenv_ne +#endif +.fi + +Link with +.IR \-lsimple . +.SH DESCRIPTION +The +.BR libsimple_getenv_ne () +function searches the environment of the calling +process for the environment variable +.IR name . +If it exists, its value is returned unless the value +is the empty string. +.PP +Modifications to the environment variable made from +within the process, its parent, or other ancestor, +that have not be come visible to other process via +replacement of the process image, are visible to the +.BR libsimple_getenv_ne () +function. +.SH RETURN VALUE +If the environment variable +.I name +is defined with a non-empty value, its value +is returned, otherwise +.I NULL +is returned. +.PP +The returned pointer must not be deallocated and +its content should not be modified. The returned +pointer becomes invalid when the environment variable +.I name +is unset or modified. +.SH ERRORS +The +.BR libsimple_getenv_ne () +function cannot fail. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR libsimple_getenv_ne () +T} Thread safety MT-Safe env +T{ +.BR libsimple_getenv_ne () +T} Async-signal safety AS-Safe +T{ +.BR libsimple_getenv_ne () +T} Async-cancel safety AC-Safe +.TE +.SH EXAMPLES +None. +.SH APPLICATION USAGE +None. +.SH RATIONALE +None. +.SH FUTURE DIRECTIONS +None. +.SH NOTES +None. +.SH BUGS +None. +.SH SEE ALSO +.BR libsimple_getenv_e (3), +.BR getenv (3) diff --git a/man/libsimple_putenvf.3 b/man/libsimple_putenvf.3 new file mode 120000 index 0000000..ce0929f --- /dev/null +++ b/man/libsimple_putenvf.3 @@ -0,0 +1 @@ +libsimple_vputenvf.3
\ No newline at end of file diff --git a/man/libsimple_vputenvf.3 b/man/libsimple_vputenvf.3 new file mode 100644 index 0000000..b18d82f --- /dev/null +++ b/man/libsimple_vputenvf.3 @@ -0,0 +1,197 @@ +.\" -*- nroff -*- +.TH LIBSIMPLE_VPUTENVF 3 2018-10-20 libsimple +.SH NAME +libsimple_vputenvf \- change or add a string formatted value to the environment +.SH SYNOPSIS +.nf +#include <libsimple.h> + +int libsimple_vputenvf(const char *\fIfmt\fP, va_list \fIap\fP); +static inline int libsimple_putenvf(const char *\fIfmt\fP, ...); +void libsimple_envputenvf(int \fIstatus\fP, const char *\fIfmt\fP, va_list \fIap\fP); +static inline void libsimple_enputenvf(int \fIstatus\fP, const char *\fIfmt\fP, ...); +static inline void libsimple_evputenvf(const char *\fIfmt\fP, va_list \fIap\fP); +static inline void libsimple_eputenvf(const char *\fIfmt\fP, ...); + +#ifndef vputenvf +# define vputenvf libsimple_vputenvf +#endif +#ifndef putenvf +# define putenvf libsimple_putenvf +#endif +#ifndef envputenvf +# define envputenvf libsimple_envputenvf +#endif +#ifndef enputenvf +# define enputenvf libsimple_enputenvf +#endif +#ifndef evputenvf +# define evputenvf libsimple_evputenvf +#endif +#ifndef eputenvf +# define eputenvf libsimple_eputenvf +#endif +.fi + +Link with +.IR \-lsimple . +.SH DESCRIPTION +The +.BR libsimple_vputenvf () +function constructs a string using the +.BR vsprintf (3) +function, and adds it to the environment, overriding +its old value if it already exists. The string shall be on +the format \fB\(dq\fP\fIname\fP\fB=\fP\fIvalue\fP\fB\(dq\fP; +however this is not strictly enforced, see +.BR NOTES . +The parameter +.I fmt +is used as the format string for the +.BR vsprintf (3) +function, and the parameter +.I ap +is used as the formatting arguments. +.PP +The +.BR libsimple_putenvf () +function is a version of the +.BR libsimple_vputenvf () +that uses variadic arguments instead of +.IR va_list . +.PP +The +.BR libsimple_envputenvf () +and +.BR libsimple_evputenvf () +functions are versions of the +.BR libsimple_vputenvf () +function that call the +.BR libsimple_enprintf (3) +function on failure, causing the process to print +an error message and exit. See +.BR libsimple_enprintf () +for more information. +.PP +The +.BR libsimple_enputenvf () +and +.BR libsimple_eputenvf () +functions are versions of the +.BR libsimple_putenvf () +function that call the +.BR libsimple_enprintf (3) +function on failure, causing the process to print +an error message and exit. See +.BR libsimple_enprintf () +for more information. +.PP +Modifications made to the environment do not become +visible to other process until the process image is +changed. +.SH RETURN VALUE +Upon successful completion, the +.BR libsimple_vputenvf () +and +.BR libsimple_putenvf () +functions return 0; otherwise, they return \-1 and set +.I errno +to indicate the error. +.SH ERRORS +The +.BR libsimple_vputenvf () +and +.BR libsimple_putenvf () +functions will fail if: +.TP +.B EINVAL +The construct string is empty or starts with the +.B '=' +character. +.TP +.B ENOMEM +Insufficient memory was available. +.PP +They may also fail for any reason specified for the +.BR vsnprintf (3) +function. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lb +l l l. +Interface Attribute Value +T{ +.BR libsimple_vputenvf (), +.br +.BR libsimple_putenvf (), +.br +.BR libsimple_envputenvf (), +.br +.BR libsimple_enputenvf (), +.br +.BR libsimple_evputenvf (), +.br +.BR libsimple_eputenvf () +T} Thread safety MT-Safe env +T{ +.BR libsimple_vputenvf (), +.br +.BR libsimple_putenvf (), +.br +.BR libsimple_envputenvf (), +.br +.BR libsimple_enputenvf (), +.br +.BR libsimple_evputenvf (), +.br +.BR libsimple_eputenvf () +T} Async-signal safety AS-Safe +T{ +.BR libsimple_vputenvf (), +.br +.BR libsimple_putenvf (), +.br +.BR libsimple_envputenvf (), +.br +.BR libsimple_enputenvf (), +.br +.BR libsimple_evputenvf (), +.br +.BR libsimple_eputenvf () +T} Async-cancel safety AC-Safe +.TE +.SH EXAMPLES +None. +.SH APPLICATION USAGE +None. +.SH RATIONALE +None. +.SH FUTURE DIRECTIONS +None. +.SH NOTES +If the construct does not contain the +.B '=' +character, it may still be added to the environment, +however this can cause problem for some programs, and +the behaviour is unspecified when countered by the +.BR getenv (3), +.BR putenv (3), +.BR setenv (3), +and +.BR unsetenv (3) +functions. +.SH BUGS +There is no mechanism for detecting which entries in the +environment are statically allocated and which are +dynamically allocated, this can lead to memory leaks +with are detected by +.BR valgrind (1). +.SH SEE ALSO +.BR putenv (3), +.BR setenv (3), +.BR unsetenv (3), +.BR getenv (3), +.BR environ (3) diff --git a/man/putenvf.3libsimple b/man/putenvf.3libsimple new file mode 120000 index 0000000..c2a50ed --- /dev/null +++ b/man/putenvf.3libsimple @@ -0,0 +1 @@ +libsimple_putenvf.3
\ No newline at end of file diff --git a/man/vputenvf.3libsimple b/man/vputenvf.3libsimple new file mode 120000 index 0000000..ce0929f --- /dev/null +++ b/man/vputenvf.3libsimple @@ -0,0 +1 @@ +libsimple_vputenvf.3
\ No newline at end of file |