packages icon



 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:  July 4, 2022






 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:  July 4, 2022