GETINVENT(3)                                                      GETINVENT(3)


NAME
     getinvent, setinvent, endinvent, scaninvent, getinvent_r, setinvent_r,
     endinvent_r - get hardware inventory entry

SYNOPSIS
     #include <invent.h>

     inventory_t *getinvent (void);

     int setinvent (void);

     void endinvent (void);

     inventory_t *getinvent_r (inv_state_t *st);

     int setinvent_r (inv_state_t **st);

     void endinvent_r (inv_state_t *st);

     int scaninvent (int (*)(inventory_t *, void *), void *);

     int _keepinvent;

DESCRIPTION
     getinvent returns a pointer to an object with the following structure
     containing an entry from the system hardware inventory table.  Each entry
     in the table contains an ``inventory'' structure, declared in the
     <sys/invent.h> header file:

          typedef struct inventory_s {
               struct inventory_s *inv_next;
               int  inv_class;
               int  inv_type;
               char inv_controller;
               char inv_unit;
               long inv_state;
          } inventory_t;


     Each inventory entry is described by a class and a class-specific type.
     The remaining fields provide further information on the inventory entry.
     See the comments in the header file for an explanation of these fields.
     The <invent.h> header file includes <sys/invent.h>, and should be
     included before calling inventory functions.

     getinvent when first called returns a pointer to the first inventory
     structure in the table; thereafter, it returns a pointer to the next
     inventory structure in the table; so successive calls can be used to
     search the entire table.


     A call to setinvent has the effect of rewinding the table to allow
     repeated searches.  It should always be called before calling getinvent.
     endinvent may be called to free allocated storage when processing is
     complete.

     A reentrant version of these functions also exists.  These should be used
     in multi-threaded applications where the shared data implicit in the
     functions described above is inappropriate.  The reentrant version
     requires that a state structure inv_state_t be initialized via
     setinvent_r and passed to getinvent_r and endinvent_r.  The first time
     setinvent_r is called, its parameter should be the address of a pointer
     initialized to NULL.  Subsequent calls to setinvent_r with the
     initialized pointer have the effect of rewinding the table to allow
     repeated searches.  This structure holds a pointer to the data and the
     current location in the data, and therefore permits multiple threads to
     call the functions simultaneously with no possibility of losing data.

     scaninvent applies fun to each inventory entry, passing the entry's
     address and arg to fun.  If fun returns a non-zero value, scaninvent
     stops scanning and returns that value.  Otherwise scaninvent returns 0
     after scanning all entries.  scaninvent normally calls endinvent before
     returning.  To prevent this call, set _keepinvent to a non-zero value.

DIAGNOSTICS
     getinvent and getinvent_r return a NULL pointer when they have read all
     entries.  setinvent and setinvent_r return -1 on failure.  scaninvent
     returns -1 if it cannot successfully setinvent or setinvent_r before
     scanning.


                                                                        Page 2