LIBAR(3) R.F. Smith LIBAR(3)
Linux Programmer's Manual Linux Programmer's Manual
$Date: 1997/12/07 12:01:20 $
NAME
ar_create, ar_destroy, ar_read, ar_size, ar_write, ar_rm - Functions
for using a flexible array.
SYNOPSIS
#include "array.h"
array_p ar_create(unsigned size, unsigned num, unsigned grow
void ar_destroy(array_p ar);
int ar_read(array_p ar, int index, int count
int ar_write(array_p ar, int index, int count
int ar_size(array_p ar);
void ar_rm(array_p ar, int index);
DESCRIPTION
This library implements a flexible array. The size of the array isn't
fixed; the array grows at runtime if needed. The size and number of
array elements is only limited by the available amount of (virtual)
memory.
The ar_create function is used to create an array, initializing the
supplied array_t structure ar. It creates an array that can hold
items of size bytes each. Initially, space for num objects is
allocated using calloc(3). But if this space is full, space for grow
extra objects is allocated. Specifying 0 for one of these paramaters
is an invalid parameter error, which will exit(3) the program that
calls this function, with a error message on stdout.
To destroy an array and free(3) the memory it occupies, use the
ar_destroy function. This function has a pointer to the array that is
to be destroyed, ar, as it's only parameter. If this is a NULL
pointer, the calling program will be exit(3)ed with a invalid
parameter error.
The ar_read function retrieves count elements from the array pointed
to by ar. It stores the read data at the location pointed to by data,
if data isn't NULL. It assumes that there is enough storage space
available at that adress! If ar is NULL, or if count or index are < 0,
this results in the program being exit(3)ed with an invalid parameter
error message on stdout.
To store in the array, the ar_write function is used. It reads count
- 1 - Formatted: November 14, 2024
LIBAR(3) R.F. Smith LIBAR(3)
Linux Programmer's Manual Linux Programmer's Manual
$Date: 1997/12/07 12:01:20 $
data elements from the location data, and stores them in the array ar
at position index. Previous enties at these locations are
overwritten! Using an index of -1, appends the elements to the array.
If ar is NULL, or if index is < 0, the program is exit(3)ed with an
invalid parameter error message on stdout. If count is 0, or if data
is NULL, nothing is written into the array.
The function ar_rm is used to remove elements from the array, and
reclaims the space they occupy. If ar is NULL, or if index is < 0, the
program is exit(3)ed with an invalid parameter error message on
stdout.
RETURN VALUES
The function ar_size returns the number of items in use in the array.
ar_create doesn't return a value.
ar_read returns the number of elements that can be read. This is a
number ranging from 0 upto and including count.
ar_write doesn't return a value.
ar_rm doesn't return a value.
SEE ALSO
calloc(3), free(3), exit(3), memcpy(3)
AUTHOR
libar is created and maintained by
Roland Smith <rsmit06@ibm.net>
- 2 - Formatted: November 14, 2024
