gandi_list(3) - Linux man page

Name

Here is a description of what GANDI provides for working with null-terminated arrays of pointers to arrays of bytes.

Synopsis

#include <gandi_core.h>

size_t GANDI_countlist(void ***list);

int GANDI_declist(void ***list, void *memb);

void **GANDI_duplist(void ***list, size_t msize);

void **GANDI_duplist_q(void ***list, size_t msize, size_t count);

void ***GANDI_freelist(void ***list);

int GANDI_inclist(void ***list, void *memb);

int GANDI_inclist_q(void ***list, void *memb, size_t c);

int GANDI_inslist(void ***list, void *memb, size_t index);

size_t GANDI_listind(void ***list, void *memb);

void **GANDI_listmemb(void ***list, void *memb);

Description

All these routines require, as their first argument, a pointer to the null-terminated array of pointers. The structure is simple. An array consist of pointers to some data. And the last element is a well known NULL pointer.

size_t GANDI_countlist(void ***list);

Returns the number of elements or an array.

int GANDI_declist(void ***list, void *memb);

Looks for memb in *list and removes it if found. Returns ERR if *list does not contains memb or the realloc(3) failed. On success the return value is OK.

void GANDI_duplist(void *list, size_t msize);

Returns an exact copy of *list. msize is the size of an array member. Each member will be copied to the new array! You'll get a new independent array. If one of the elements cannot be supplied with enough memory, the whole array will be disposed and NULL returned. On success the return value is the array just created the same as *list.

void GANDI_freelist(void list);

Frees memory of an array and of all its members. Returns its only argument.

int GANDI_inclist(void ***list, void *memb);

Adds memb to the end of an array. Returns either OK or ERR.

int GANDI_inslist(void ***list, void *memb, size_t index);

Inserts memb just before the indexth member. It does not copy *memb! It only pastes the pointer to it. Returns either OK or ERR.

size_t GANDI_listind(void ***list, void *memb);

Searches for memb and returns its index. It will return the index of the NULL element if there was no memb found.

void GANDI_listmemb(void list, void memb);

Searches for memb and returns its pointer from *list. You can use

( (*list) + GANDI_listind(list, memb) )

instead but it is longer.

Notes

There are _q prototypes for some functions. They do the same things but a bit quicker for they assume you know the array size and requires it as the last argument.

The GANDI_duplist creates an empty array (i.e. with no elements) if either list or *list is NULL. All the other of these routines DO NOT handle this exception and will cause unpredictable application behavior.

On error any function leaves *list unchanged. It is safe to use an array even after you got the return value ERR.