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

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 -- Operate on argz vectors

Synopsis

#include <argz.h>

error_t argz_add(char ** argz, size_t * argz_len, const char * str);

error_t argz_add_sep(char ** argz, size_t * argz_len, const char * str, int sep);

error_t argz_append(char ** argz, size_t * argz_len, const char * buf, size_t buf_len);

size_t argz_count(const char * argz, size_t * argz_len);

error_t argz_create(char * const argv, char ** argz, size_t * argz_len);

error_t argz_create_sep(const char * str, int sep, char ** argz, size_t * argz_len);

void argz_delete(char ** argz, size_t * argz_len, char * entry);

void argz_extract(const char * argz, size_t argz_len, char ** argv);

error_t argz_insert(char ** argz_insert, size_t * argz_len, char * before, const char * entry);

char argz_next(const char * argz, size_t argz_len, const char * entry);

error_t argz_replace(char ** argz, size_t * argz_len, const char * str, const char * with, unsigned int * replace_count);

void argz_stringify(char * argz, size_t argz_len, int sep);

Description

The argz functions operate on argz vectors, which are typically used to more easily manipulate program arguments, of the form described in ISO C (1999) in section 5.1.2.2.1, Program Startup. While an argv is an array of character pointers to strings, an argz vector is a set of strings, separated by null characters, in contiguous memory; the vector is described by a pointer to the first element and a size. There is no limitation that the argz must be made up of program arguments.

The argz functions which change argz vectors expect them to use memory allocated using malloc(), and will themselves use malloc() or realloc().

The argz_create() function converts an argv vector identified by argv to an argz vector with the same elements, identified by argz and argz_len.

The argz_create_sep() function converts the string identified by str, spliting into a separate string at each occurence of sep, to an argz vector identified by argz and argz_len.

The argz_add() function adds the string identified by str to the vector identified by argz and argz_len, updating argz and argz_len.

The argz_add_sep() function adds the string identified by str, spliting into a separate string at each occurence of sep, to the vector identified by argz, updating argz and argz_len.

The argz_append() function appends the argz vector identified by buf and buf_len to the argz vector identified by argz and argz_len, thus updating argz and argz_len.

The argz_count() function returns the number of strings in the argz vector identified by argz and argz_len.

The argz_delete() function removes the string identified by entry from the the argz vector identified by argz, argz_len, updating argz and argz_len.

The argz_extract() function performs the inverse of argz_create(). It converts an argz vector identified by argz and argz_len to an argv vector identified by argv with the same elements.

The argz_insert() function inserts the string identified by entry at position before to the the argz vector identified by argz and argz_len, updating argz and argz_len.

The argz_next() function returns the entry following the entry identfied by entry in the argz vector identified by argz and argz_len. If entry is NULL the first entry is returned. This function can be used to step through an argz vector by obtaining the first entry by passing NULL, then passing the just obtained value to the next call, and so on. NULL is returned if there is no following entry.

The argz_replace() function replaces each occurrence of str in the argz vector identified by argz and argz_len with with, updating argz and argz_len. The counter pointed to by replace_count will be incremented by the number of replacements unless NULL is passed for replace_count.

The argz_stringify() function performs the inverse of argz_create_sep(). It converts the argz vector identified by argz and argz_len into a regular string, with the strings in the original vector separated by sep in the converted string. The conversion is done in place, so in effect each null byte in argz but the last one is replaced by sep.

Return Value

All of the argz functions that perform memory allocation return an error_t type. These functions return 0 on success; if memory allocation fails, they return ENOMEM.

argz_count() returns a count of substrings in the argz vector as a size_t type.

argz_next() returns a pointer to a substring in an argz vector, or NULL.

See Also

envz_add, envz_entry, envz_get, envz_merge, envz_remove, envz_strip