.\" 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
.\" 
.\" Traducido por Miguel Pérez Ibars <mpi79470@alu.um.es> el 10-julio-2004
.\"
.TH ARGZ_ADD 3
.SH NOMBRE
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 \- funciones para manejar una lista argz
.SH SINOPSIS
.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 DESCRIPCIÓN
Estas funciones son específicas de glibc.
.LP
Un vector argz es un puntero a un buffer de caracteres junto con una longitud.
Se pretende que el buffer de caracteres sea interpretado como un array
de cadenas, donde las cadenas están separadas por bytes NUL.
Si la longitud es distinta de cero, el último byte del buffer debe ser NUL.
.LP
Estas funciones se ofrecen para manejar vectores argz.
El par (NULL,0) es un vector argz, y, al contrario,
los vectores argz de longitud 0 deben tener un puntero NULL.
La reserva de memoria de los vectores argz no vacíos se realiza mediante
.BR malloc (3),
así
.BR free (3)
puede utilizarse para liberarla después.
.LP
.B argz_add()
añade la cadena
.I str
al final del array
.RI * argz ,
y actualiza
.RI * argz
y
.RI * argz_len .
.LP
.B argz_add_sep()
es similar, pero separa la cadena
.I str
en dos subcadenas separadas por el delimitador
.IR delim .
Por ejemplo, se puede utilizar está función en una ruta de búsqueda Unix
con el delimitador ':'.
.LP
.B argz_append()
añade el vector argz
.RI ( buf , buf_len )
después de
.RI (* argz ,* argz_len )
y actualiza
.RI * argz
y
.RI * argz_len .
(Así,
.RI * argz_len
se incrementará en
.IR buf_len .)
.LP
.B argz_count()
cuenta el número de cadenas, esto es, el número de bytes NUL, en
.RI ( argz , argz_len ).
.LP
.B argz_create()
convierte un vector de argumentos al estilo Unix
.IR argv ,
terminado en (char *) 0, en un vector argz
.RI (* argz ,* argz_len ).
.LP
.B argz_create_sep()
convierte la cadena terminada en NUL
.I str
en un vector argz
.RI (* argz ,* argz_len )
partiéndola en cada ocurrencia del separador
.IR sep .
.LP
.B argz_delete()
elimina la subcadena apuntada por
.I entry
del vector argz
.RI (* argz ,* argz_len )
y actualiza
.RI * argz
y
.RI * argz_len .
.LP
.B argz_extract()
es la contraria de
.BR argz_create() .
Toma un vector argz
.RI ( argz , argz_len )
y rellena el array que comienza en
.I argv
con punteros a las subcadenas, añadiendo un NULL al final,
formando un vector argv al estilo Unix.
El array
.I argv
debe tener suficiente espacio para
.IR argz_count ( argz , argz_len ") + 1"
punteros.
.LP
.B argz_insert()
es la opuesta de
.BR argz_delete() .
Inserta el argumento
.I entry
en la posición
.I before
en el vector argz
.RI (* argz ,* argz_len )
y actualiza
.RI * argz
y
.RI * argz_len .
Si
.I before
es NULL, 
.I entry
será insertada al final.
.LP
.B argz_next()
es una función para recorrer el vector argz. Si
.I entry
es NULL, se devuelve la primera entrada. En otro caso, se devuelve
la siguiente entrada. Devuelve NULL si no quedan más entradas.
.LP
.B argz_replace()
reemplaza cada ocurrencia de
.I str
con
.IR with ,
reasignando argz si es necesario. Si
.I replace_count
es distinto de NULL,
.RI * replace_count
se incrementará con el número de reemplazos.
.LP
.B argz_stringify()
es la opuesta de
.BR argz_create_sep() .
Transforma el vector argz en una cadena normal reemplazando
todos los NULs excepto el último por
.IR sep .
.SH "VALOR DEVUELTO"
Todas las funciones argz que realizan reserva de memoria devuelven un tipo
\fIerror_t\fP, devolviendo \fB0\fP en caso de éxito, y \fBENOMEM\fP
si ocurre un error de asignación de memoria.
.SH FALLOS
Los vectores argz sin un NUL final pueden provocar Violaciones de Segmento.
.SH OBSERVACIONES
Estas funciones son extensiones de GNU. Manejar con cuidado.
.SH "VÉASE TAMBIÉN"
.BR envz (3)