Principios metodológicos y evaluativos

Each argz vector is represented by a pointer to the first element, of typechar *, and a size, of typesize_t, both of which can be initialized to0to represent an empty argz vector. All argz functions accept either a pointer and a size argument, or pointers to them, if they will be modified.

The argz functions use malloc/realloc to allocate and grow argz vectors, so any argz vector created using these functions may be freed by using free; conversely, any argz function that may grow a string expects that string to have been allocated usingmalloc(those argz functions that only examine their arguments or modify them in place will work on any sort of memory). See Section 3.2.2 [Unconstrained Allocation], page 42, for more information.

All argz functions that do memory allocation have a return type oferror_t, and return0for success orENOMEMif an allocation error occurs.

These functions are declared in the standard include file ‘argz.h’.

Function

error_targz create (char *constargv[], char **argz, size_t *argz len)

Theargz_createfunction converts the Unix-style argument vectorargv(a vector of pointers to normal C strings, terminated by (char *)0; see Sec- tion 14.1 [Program Arguments], page 379) into an argz vector with the same elements, which is returned inargzandargz len.

Function

error_targz create sep (const char *string, intsep, char **argz, size_t *argz len)

The argz_create_sep function converts the null-terminated string string

into an argz vector (returned inargz andargz len) by splitting it into elements at every occurrence of the charactersep.

Function

size_targz count (const char *argz, size_targ len)

Returns the number of elements in the argz vectorargzandargz len.

Function

voidargz extract (char *argz, size_targz len, char **argv)

Theargz_extractfunction converts the argz vectorargzandargz leninto a Unix-style argument vector stored inargv, by putting pointers to every element inargz into successive positions inargv, followed by a terminator of 0. Argv

must be preallocated with enough space to hold all the elements inargzplus the terminating (char *)0 ((argz_count (argz,argz len) + 1) * sizeof (char *)bytes should be enough). The string pointers stored intoargvpoint intoargz—they are not copies—and soargzmust be copied if it will be changed whileargvis still active. This function is useful for passing the elements inargz

to an exec function.6

Function

voidargz stringify (char *argz, size_tlen, intsep)

The argz_stringifyconvertsargz into a normal string with the elements separated by the charactersep, by replacing each’\0’insideargz (except the last one, which terminates the string) withsep. This is handy for printingargz

in a readable manner.

Function

error_targz add (char **argz, size_t *argz len, const char *str)

Theargz_addfunction adds the stringstr to the end of the argz vector*argz,

and updates*argzand*argz lenaccordingly.

Function

error_targz add sep (char **argz, size_t *argz len, const char *str, intdelim)

The argz_add_sepfunction is similar to argz_add, but str is split into separate elements in the result at occurrences of the character delim. This is useful, for instance, for adding the components of a Unix search path to an argz vector, by using a value of’:’fordelim.

Function

error_targz append (char **argz, size_t *argz len, const char *buf, size_tbuf len)

Theargz_appendfunction appendsbuf len bytes starting atbuf to the argz vector *argz, reallocating *argz to accommodate it, and adding buf len to

*argz len. 6

Chapter 5: String and Array Utilities 129 Function

error_targz delete (char **argz, size_t *argz len, char *entry)

Ifentrypoints to the beginning of one of the elements in the argz vector*argz, theargz_deletefunction will remove this entry and reallocate*argz, mod- ifying*argz and*argz len accordingly. As destructive argz functions usually reallocate their argz argument, pointers into argz vectors such asentrywill then become invalid.

Function

error_targz insert (char **argz, size_t *argz len, char *before, const char *entry)

Theargz_insertfunction inserts the stringentryinto the argz vector*argz

at a point just before the existing element pointed to by before, reallocating

*argz and updating*argzand*argz len. Ifbefore is0,entry is added to the

end instead (as if byargz_add). Since the first element is in fact the same as

*argz, passing in*argzas the value ofbeforewill result inentrybeing inserted

at the beginning.

Function

char *argz next (char *argz, size_targz len, const char *entry)

The argz_nextfunction provides a convenient way of iterating over the el- ements in the argz vector argz. It returns a pointer to the next element inargz

after the elemententry, or0if there are no elements followingentry. Ifentryis

0, the first element ofargz is returned. This behavior suggests two styles of iteration:

char *entry = 0;

while ((entry = argz_next (argz, argz len, entry)))

action;

(the double parentheses are necessary to make some C compilers shut up about what they consider a questionablewhile-test) and:

char *entry; for (entry = argz;

entry;

entry = argz_next (argz, argz len, entry))

action;

The latter depends on argz having a value of 0 if it is empty (rather than a pointer to an empty block of memory); this invariant is maintained for argz vectors created by the functions here.

Function

error_targz replace (char **argz, size_t *argz len, const char *str, const char *with,

unsigned *replace count)

Replace any occurrences of the stringstr inargzwithwith, reallocatingargzas necessary. Ifreplace count is nonzero,*replace count will be incremented by