sam_opencat(3)

NAME
     sam_opencat - Accesses an  automated  library's  catalog  to
     read entries

SYNOPSIS
     cc [ flag  ... ] file    ...  -L/opt/SUNWsamfs/lib  -lsam  [
     library ... ]

     #include "/opt/SUNWsamfs/include/catalog.h"

     int sam_opencat(const char *path, struct  sam_cat_tbl  *buf,
     size_t bufsize);

AVAILABILITY
     32-bit programs only

DESCRIPTION
     sam_opencat() initiates  access  to  the  automated  library
     catalog pointed to by path.  The string which path points to
     is limited to 127  characters.   It  returns  a  sam_cat_tbl
     structure  in  the  area  pointed to by buf . bufsize is the
     length of the user's  buffer  to  which  buf  points.   This
     should   be   equal   to   or   greater  than  sizeof(struct
     sam_cat_tbl).

     The user may have access to at most MAX_CAT catalogs at  any
     one time.

     The contents of a sam_cat_tbl structure include the  follow-
     ing members:

          /* catalog table */
          time_t   audit_time;  /* Audit time */
          int      version;     /* Catalog version number */
          int      count;       /* Number of slots */
          char     media[4];    /* Media type, if entire catalog is one */

     Following the call to sam_opencat(), entries in the  library
     catalog are obtained using sam_getcatalog().

RETURN VALUES
     Upon successful completion, a catalog "handle" is  returned,
     which is an integer equal to or greater than zero.

     This   "handle"   is   used   on   subsequent    calls    to
     sam_getcatalog()  to  specify  the catalog to access, and is
     also used by sam_closecat() to deallocate the  "handle"  and
     end access to the catalog.

     If the call  to  sam_opencat()  fails,  a  value  of  -1  is
     returned and errno is set to indicate the error.

ERRORS
     sam_opencat() fails if one or more of  the  following  error
     conditions are true:

     EMFILE              The user already has access  to  MAX_CAT
                         catalogs  ,  or the process has too many
                         open files.

     EINVAL              bufsize is set to an invalid  value,  or
                         either path or buf is a null pointer.

     ER_UNABLE_TO_INIT_CATALOG
                         This process was  unable  to  initialize
                         the catalog data.

     ENOENT              There is no active catalog file with the
                         name given.

SEE ALSO
     sam_closecat(3), sam_getcatalog(3)