diff options
Diffstat (limited to 'man3/argz_add.3')
| -rw-r--r-- | man3/argz_add.3 | 207 |
1 files changed, 207 insertions, 0 deletions
diff --git a/man3/argz_add.3 b/man3/argz_add.3 new file mode 100644 index 000000000..544091b04 --- /dev/null +++ b/man3/argz_add.3 @@ -0,0 +1,207 @@ +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" Distributed under GPL +.\" based on the description in glibc source and infopages +.\" +.\" Corrections and additions, aeb +.TH ARGZ_ADD 3 +.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 SYNOPSIS +.nf +.sp +.B "#include <argz.h>" +.sp +.BI "error_t" +.BI "argz_add(char **" argz ", size_t *" argz_len ", const char *" str ); +.sp +.BI "error_t" +.BI "argz_add_sep(char **" argz ", size_t *" argz_len , +.ti 20n +.BI "const char *" str ", int " delim ); +.sp +.BI "error_t" +.BI "argz_append(char **" argz ", size_t *" argz_len , +.ti 20n +.BI "const char *" buf ", size_t " buf_len ); +.sp +.BI "size_t" +.BI "argz_count(const char *" argz ", size_t " argz_len ); +.sp +.BI "error_t" +.BI "argz_create(char * const " argv "[], char **" argz , +.ti 20n +.BI "size_t *" argz_len ); +.sp +.BI "error_t" +.BI "argz_create_sep(const char *" str ", int " sep ", char **" argz , +.ti 20n +.BI "size_t *" argz_len ); +.sp +.BI "error_t" +.BI "argz_delete(char **" argz ", size_t *" argz_len ", char *" entry ); +.sp +.BI "void" +.BI "argz_extract(char *" argz ", size_t " argz_len ", char **" argv ); +.sp +.BI "error_t" +.BI "argz_insert (char **" argz ", size_t *" argz_len ", char *" before , +.ti 20n +.BI "const char *" entry ); +.sp +.BI "char *" +.BI "argz_next(char *" argz ", size_t " argz_len ", const char *" entry ); +.sp +.BI "error_t" +.BI "argz_replace(char **" argz ", size_t *" argz_len ", const char *" str , +.ti 20n +.BI "const char *" with ", unsigned int *" replace_count ); +.sp +.BI "void" +.BI "argz_stringify(char *" argz ", size_t " len ", int " sep ); +.sp +.SH DESCRIPTION +These functions are glibc-specific. +.LP +An argz vector is a pointer to a character buffer together with a length. +The intended interpretation of the character buffer is array +of strings, where the strings are separated by NUL bytes. +If the length is nonzero, the last byte of the buffer must be a NUL. +.LP +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. +.LP +.B argz_add() +adds the string +.I str +at the end of the array +.RI * argz , +and updates +.RI * argz +and +.RI * argz_len . +.LP +.B 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 ':'. +.LP +.B argz_append() +appends the argz vector +.RI ( buf , buf_len ) +after +.RI (* argz ,* argz_len ) +and updates +.RI * argz +and +.RI * argz_len . +(Thus, +.RI * argz_len +will be increased by +.IR buf_len .) +.LP +.B argz_count() +counts the number of strings, that is, the number of NUL bytes, in +.RI ( argz , argz_len ). +.LP +.B argz_create() +converts a Unix-style argument vector +.IR argv , +terminated by (char *) 0, into an argz vector +.RI (* argz ,* argz_len ). +.LP +.B argz_create_sep() +converts the NUL-terminated string +.I str +into an argz vector +.RI (* argz ,* argz_len ) +by breaking it up at every occurrence of the separator +.IR sep . +.LP +.B argz_delete() +removes the substring pointed to by +.I entry +from the argz vector +.RI (* argz ,* argz_len ) +and updates +.RI * argz +and +.RI * argz_len . +.LP +.B 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. +.LP +.B 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 +.RI * argz +and +.RI * argz_len . +If +.I before +is NULL, then +.I entry +will inserted at the end. +.LP +.B argz_next() +is a function to step trough 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. +.LP +.B argz_replace() +replaces each occurrence of +.I str +with +.IR with , +reallocating argz as necessary. If +.I replace_count +is non-NULL, +.RI * replace_count +will be incremented by the number of replacements. +.LP +.B argz_stringify() +is the opposite of +.BR argz_create_sep() . +It transforms the argz vector into a normal string by replacing +all NULs except the last by +.IR sep . +.SH "RETURN VALUE" +All argz functions that do memory allocation have a return type of +\fIerror_t\fP, and return \fB0\fP for success, and \fBENOMEM\fP +if an allocation error occurs. +.SH BUGS +Argz vectors without final NUL may lead to Segmentation Faults. +.SH NOTES +These functions are a GNU extension. Handle with care. +.SH "SEE ALSO" +.BR envz (3) |