--- name: "argz_extract" section: "3" platform: "linux" package: "man-pages" version: "6.19-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/argz_add" --- # argz\_extract(3) functions to handle an argz list Part of [argz\_add(3)](/argz_add/3.md). ## 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 ## LIBRARY Standard C library (*libc*, *-lc*) ## SYNOPSIS ``` #include ``` **error\_t argz\_add(char \*\*restrict** *argz***, size\_t \*restrict** *argz\_len***,** **const char \*restrict** *str***);** **error\_t argz\_add\_sep(char \*\*restrict** *argz***, size\_t \*restrict** *argz\_len***,** **const char \*restrict** *str***, int** *delim***);** **error\_t argz\_append(char \*\*restrict** *argz***, size\_t \*restrict** *argz\_len***,** **const char \*restrict** *buf***, size\_t** *buf\_len***);** **size\_t argz\_count(const char \****argz***, size\_t** *argz\_len***);** **error\_t argz\_create(char \*const** *argv***\[\], char \*\*restrict** *argz***,** **size\_t \*restrict** *argz\_len***);** **error\_t argz\_create\_sep(const char \*restrict** *str***, int** *sep***,** **char \*\*restrict** *argz***, size\_t \*restrict** *argz\_len***);** **void argz\_delete(char \*\*restrict** *argz***, size\_t \*restrict** *argz\_len***,** **char \*restrict** *entry***);** **void argz\_extract(const char \*restrict** *argz***, size\_t** *argz\_len***,** **char \*\*restrict** *argv***);** **error\_t argz\_insert(char \*\*restrict** *argz***, size\_t \*restrict** *argz\_len***,** **char \*restrict** *before***, const char \*restrict** *entry***);** **char \*argz\_next(const char \*restrict** *argz***, size\_t** *argz\_len***,** **const char \*restrict** *entry***);** **error\_t argz\_replace(char \*\*restrict** *argz***, size\_t \*restrict** *argz\_len***,** **const char \*restrict** *str***, const char \*restrict** *with***,** **unsigned int \*restrict** *replace\_count***);** **void argz\_stringify(char \****argz***, size\_t** *len***, int** *sep***);** ## DESCRIPTION These functions are glibc-specific. An argz vector is a pointer to a character buffer together with a length. The intended interpretation of the character buffer is an array of strings, where the strings are separated by null bytes ('\\0'). If the length is nonzero, the last byte of the buffer must be a null byte. 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 [**malloc**(3)](/malloc/3.md), so that [**free**(3)](/free/3.md) can be used to dispose of them again. **argz\_add**() adds the string *str* at the end of the array *\*argz*, and updates *\*argz* and *\*argz\_len*. **argz\_add\_sep**() is similar, but splits the string *str* into substrings separated by the delimiter *delim*. For example, one might use this on a UNIX search path with delimiter ':'. **argz\_append**() appends the argz vector (*buf*, *buf\_len*) after (*\*argz*, *\*argz\_len*) and updates *\*argz* and *\*argz\_len*. (Thus, *\*argz\_len* will be increased by *buf\_len*.) **argz\_count**() counts the number of strings, that is, the number of null bytes ('\\0'), in (*argz*, *argz\_len*). **argz\_create**() converts a UNIX-style argument vector *argv*, terminated by *(char \*) 0*, into an argz vector (*\*argz*, *\*argz\_len*). **argz\_create\_sep**() converts the null-terminated string *str* into an argz vector (*\*argz*, *\*argz\_len*) by breaking it up at every occurrence of the separator *sep*. **argz\_delete**() removes the substring pointed to by *entry* from the argz vector (*\*argz*, *\*argz\_len*) and updates *\*argz* and *\*argz\_len*. **argz\_extract**() is the opposite of **argz\_create**(). It takes the argz vector (*argz*, *argz\_len*) and fills the array starting at *argv* with pointers to the substrings, and a final NULL, making a UNIX-style argv vector. The array *argv* must have room for *argz\_count*(*argz*, *argz\_len*) + 1 pointers. **argz\_insert**() is the opposite of **argz\_delete**(). It inserts the argument *entry* at position *before* into the argz vector (*\*argz*, *\*argz\_len*) and updates *\*argz* and *\*argz\_len*. If *before* is NULL, then *entry* will inserted at the end. **argz\_next**() is a function to step through the argz vector. If *entry* is NULL, the first entry is returned. Otherwise, the entry following is returned. It returns NULL if there is no following entry. **argz\_replace**() replaces each occurrence of *str* with *with*, reallocating argz as necessary. If *replace\_count* is non-NULL, *\*replace\_count* will be incremented by the number of replacements. **argz\_stringify**() is the opposite of **argz\_create\_sep**(). It transforms the argz vector into a normal string by replacing all null bytes ('\\0') except the last by *sep*. ## RETURN VALUE All argz functions that do memory allocation have a return type of *error\_t* (an integer type), and return 0 for success, and **ENOMEM** if an allocation error occurs. ## ATTRIBUTES For an explanation of the terms used in this section, see [**attributes**(7)](/attributes/7.md). | | | | | --- | --- | --- | | **Interface** | **Attribute** | **Value** | | **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**() | Thread safety | MT-Safe | ## STANDARDS GNU. ## BUGS Argz vectors without a terminating null byte may lead to Segmentation Faults. ## SEE ALSO [**envz\_add**(3)](/envz_add/3.md)