Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 237 insertions, 0 deletions

diff --git a/man/man3/argz_add.3 b/man/man3/argz_add.3
new file mode 100644
index 0000000..0e8f468
--- /dev/null
+++ b/man/man3/argz_add.3
@@ -0,0 +1,237 @@
+'\" 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 argz_add 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+argz_add, argz_add_sep, argz_append, argz_count, argz_create,
+argz_create_sep, argz_delete, argz_extract, argz_insert,
+argz_next, argz_replace, argz_stringify \- functions to handle an argz list
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B "#include <argz.h>"
+.P
+.BI "error_t argz_add(char **restrict " argz ", size_t *restrict " argz_len ,
+.BI "                const char *restrict " str );
+.P
+.BI "error_t argz_add_sep(char **restrict " argz \
+", size_t *restrict " argz_len ,
+.BI "                const char *restrict " str ", int " delim );
+.P
+.BI "error_t argz_append(char **restrict " argz ", size_t *restrict " argz_len ,
+.BI "                const char *restrict " buf ", size_t " buf_len );
+.P
+.BI "size_t argz_count(const char *" argz ", size_t " argz_len );
+.P
+.BI "error_t argz_create(char *const " argv "[], char **restrict " argz ,
+.BI "                size_t *restrict " argz_len );
+.P
+.BI "error_t argz_create_sep(const char *restrict " str ", int " sep ,
+.BI "                char **restrict " argz ", size_t *restrict " argz_len );
+.P
+.BI "void argz_delete(char **restrict " argz ", size_t *restrict " argz_len ,
+.BI "                char *restrict " entry );
+.P
+.BI "void argz_extract(const char *restrict " argz ", size_t " argz_len ,
+.BI "                char **restrict " argv );
+.P
+.BI "error_t argz_insert(char **restrict " argz ", size_t *restrict " argz_len ,
+.BI "                char *restrict " before ", const char *restrict " entry );
+.P
+.BI "char *argz_next(const char *restrict " argz ", size_t " argz_len ,
+.BI "                const char *restrict " entry );
+.P
+.BI "error_t argz_replace(char **restrict " argz \
+", size_t *restrict " argz_len ,
+.BI "                const char *restrict " str ", const char *restrict " with ,
+.BI "                unsigned int *restrict " replace_count );
+.P
+.BI "void argz_stringify(char *" argz ", size_t " len ", int " sep );
+.fi
+.SH DESCRIPTION
+These functions are glibc-specific.
+.P
+An argz vector is a pointer to a character buffer together with a length.
+The intended interpretation of the character buffer is an array
+of strings, where the strings are separated by null bytes (\[aq]\e0\[aq]).
+If the length is nonzero, the last byte of the buffer must be a null byte.
+.P
+These functions are for handling argz vectors.
+The pair (NULL,0) is an argz vector, and, conversely,
+argz vectors of length 0 must have null pointer.
+Allocation of nonempty argz vectors is done using
+.BR malloc (3),
+so that
+.BR free (3)
+can be used to dispose of them again.
+.P
+.BR argz_add ()
+adds the string
+.I str
+at the end of the array
+.IR *argz ,
+and updates
+.I *argz
+and
+.IR *argz_len .
+.P
+.BR argz_add_sep ()
+is similar, but splits the string
+.I str
+into substrings separated by the delimiter
+.IR delim .
+For example, one might use this on a UNIX search path with
+delimiter \[aq]:\[aq].
+.P
+.BR argz_append ()
+appends the argz vector
+.RI ( buf ,\  buf_len )
+after
+.RI ( *argz ,\  *argz_len )
+and updates
+.I *argz
+and
+.IR *argz_len .
+(Thus,
+.I *argz_len
+will be increased by
+.IR buf_len .)
+.P
+.BR argz_count ()
+counts the number of strings, that is,
+the number of null bytes (\[aq]\e0\[aq]), in
+.RI ( argz ,\  argz_len ).
+.P
+.BR argz_create ()
+converts a UNIX-style argument vector
+.IR argv ,
+terminated by
+.IR "(char\ *)\ 0" ,
+into an argz vector
+.RI ( *argz ,\  *argz_len ).
+.P
+.BR argz_create_sep ()
+converts the null-terminated string
+.I str
+into an argz vector
+.RI ( *argz ,\  *argz_len )
+by breaking it up at every occurrence of the separator
+.IR sep .
+.P
+.BR argz_delete ()
+removes the substring pointed to by
+.I entry
+from the argz vector
+.RI ( *argz ,\  *argz_len )
+and updates
+.I *argz
+and
+.IR *argz_len .
+.P
+.BR argz_extract ()
+is the opposite of
+.BR argz_create ().
+It takes the argz vector
+.RI ( argz ,\  argz_len )
+and fills the array starting at
+.I argv
+with pointers to the substrings, and a final NULL,
+making a UNIX-style argv vector.
+The array
+.I argv
+must have room for
+.IR argz_count ( argz ", " argz_len ") + 1"
+pointers.
+.P
+.BR argz_insert ()
+is the opposite of
+.BR argz_delete ().
+It inserts the argument
+.I entry
+at position
+.I before
+into the argz vector
+.RI ( *argz ,\  *argz_len )
+and updates
+.I *argz
+and
+.IR *argz_len .
+If
+.I before
+is NULL, then
+.I entry
+will inserted at the end.
+.P
+.BR argz_next ()
+is a function to step through the argz vector.
+If
+.I entry
+is NULL, the first entry is returned.
+Otherwise, the entry
+following is returned.
+It returns NULL if there is no following entry.
+.P
+.BR argz_replace ()
+replaces each occurrence of
+.I str
+with
+.IR with ,
+reallocating argz as necessary.
+If
+.I replace_count
+is non-NULL,
+.I *replace_count
+will be incremented by the number of replacements.
+.P
+.BR argz_stringify ()
+is the opposite of
+.BR argz_create_sep ().
+It transforms the argz vector into a normal string by replacing
+all null bytes (\[aq]\e0\[aq]) except the last by
+.IR sep .
+.SH RETURN VALUE
+All argz 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 argz_add (),
+.BR argz_add_sep (),
+.BR argz_append (),
+.BR argz_count (),
+.BR argz_create (),
+.BR argz_create_sep (),
+.BR argz_delete (),
+.BR argz_extract (),
+.BR argz_insert (),
+.BR argz_next (),
+.BR argz_replace (),
+.BR argz_stringify ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+GNU.
+.SH BUGS
+Argz vectors without a terminating null byte may lead to
+Segmentation Faults.
+.SH SEE ALSO
+.BR envz_add (3)