Add man pages for putenvf and getenv functions

Signed-off-by: Mattias Andrée <maandree@kth.se>

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