.\" 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 ENVZ_ADD 3
.SH NOMBRE
envz_add, envz_entry, envz_get, envz_merge,
envz_remove, envz_strip \- soporte para las cadenas de entorno
.SH SINOPSIS
.nf
.sp
.B "#include <envz.h>"
.sp
.BI "error_t"
.BI "envz_add(char **" envz ", size_t *" envz_len ,
.ti 16n
.BI "const char *" nombre ", const char *" valor );
.sp
.BI "char *"
.BI "envz_entry(const char *" envz ", size_t *" envz_len ", const char *" nombre );
.sp
.BI "char *"
.BI "envz_get(const char *" envz ", size_t *" envz_len ", const char *" nombre );
.sp
.BI "error_t"
.BI "envz_merge(char **" envz ", size_t *" envz_len ,
.ti 16n
.BI "const char *" envz2 ", size_t " envz2_len ", int " override );
.sp
.BI "void"
.BI "envz_remove(char **" envz ", size_t *" envz_len ", const char *" nombre );
.sp
.BI "void"
.BI "envz_strip(char **" envz ", size_t *" envz_len );
.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,
véase
.BR argz_add (3).
Un vector envz es un vector argz especial, donde las cadenas son de la forma
"nombre=valor". Todo lo que sigue al primer '=' se considera el valor.
Si no hay un carácter '=', el valor se considera NULL.
(Mientras que el valor en el caso en que haya un '=' al final es la cadena vacía "".)
.LP
Estas funciones se usan para manejar vectores envz.
.LP
.B envz_add()
añade la cadena
.RI \&" nombre = valor \&"
(en el caso en que
.I valor
sea distinto de NULL) o
.RI \&" nombre \&"
(en el caso en que
.I valor
sea NULL) al vector envz
.RI (* envz ,* envz_len )
y actualiza
.RI * envz
y
.RI * envz_len .
Si ya existe una entrada con el mismo
.I nombre
, se elimina.
.LP
.B envz_entry()
busca el
.I nombre
en el vector envz
.RI ( envz , envz_len )
y devuelve la entrada si se encuentra, o NULL en caso contrario.
.LP
.B envz_get()
busca el 
.I nombre
en el vector envz
.RI ( envz , envz_len )
y devuelve el valor si se encuentra, o NULL en caso contrario.
(Observe que el valor también puede ser NULL, este caso se da cuando
hay una entrada para
.I nombre
sin el carácter '='.)
.LP
.B envz_merge()
añada cada entrada en
.I envz2
a
.RI * envz ,
de la misma manera que
.BR envz_add() .
Si
.I override
es verdadero, los valores de
.I envz2
reemplazarán aquellos con el mismo nombre en
.RI * envz.
.LP
.B envz_remove()
elimina la entrada para
.I nombre
de
.RI (* envz ,* envz_len )
si existe una.
.LP
.B envz_strip
elimina todas las entradas con valor NULL.
.SH "VALOR DEVUELTO"
Todas las funciones envz que realizan reserva de memoria devuelven un tipo
\fIerror_t\fP, y devuelven \fB0\fP en caso de éxito, y \fBENOMEM\fP
si ocurre un error con la asignación de memoria.
.SH EJEMPLO
.sp
.nf
#include <stdio.h>
#include <envz.h>
int
main(int argc, char *argv[], char *envp[]) {
	int i, e_len = 0;
	char *str;

	for (i=0; envp[i] != NULL; i++)
		e_len += strlen(envp[i]) + 1;

	str = envz_entry(*envp, e_len, "HOME");
	printf("%s\en", str);
	str = envz_get(*envp, e_len, "HOME");
	printf("%s\en", str);
	return 0;
}
.fi
.SH OBSERVACIONES
Estas funciones son extensiones de GNU. Manéjelas con cuidado.
.SH "VÉASE TAMBIÉN"
.BR argz (3)