sam_getcatalog(3)

NAME
     sam_getcatalog,  sam_getcatalogl,  sam_getcataloglv  -  Gets
     catalog entries

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

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

     int sam_getcatalog(int cat_handle,  uint  start_entry,  uint
     end_entry, struct sam_cat_ent *buf, size_t entbufsize);

     int sam_getcatalogl(int cat_handle, uint  start_entry,  uint
     end_entry, struct sam_cat_entl *buf, size_t entbufsize);

     int sam_getcataloglv(int cat_handle, uint start_entry,  uint
     end_entry, struct sam_cat_entlv *buf, size_t entbufsize);

DESCRIPTION
     sam_getcatalog() and  sam_getcatalogl()  are  obsolete,  use
     sam_getcataloglv().

     sam_getcataloglv() obtains a range of entries from the cata-
     log  of  an automated library or the historian.  The catalog
     from  which  entries  will  be  obtained  is  indicated   by
     cat_handle.  cat_handle is similar to a file descriptor, and
     is returned from a previous call to sam_opencat(). The range
     of  entries  is  indicated  by  start_entry  and  end_entry.
     start_entry must be less than or  equal  to  end_entry,  and
     must be in the range of valid slot numbers for the automated
     library (or historian).  buf is a pointer  to  an  array  of
     sam_cat_entlv  structures,  into  which  the  catalog  entry
     information is placed.  This array should be large enough to
     hold  the  number  of  entries requested.  entbufsize is the
     size of a single sam_cat_entlv structure, usually  indicated
     by sizeof(struct sam_cat_entlv).

     The contents of a sam_cat_entlv structure include  the  fol-
     lowing members:

          /* catalog table entry */
          uint_t   status;      /* Catalog entry status */
          char     media[4];    /* Media type */
          char     vsn[32];     /* VSN */
          int      access;      /* Count of accesses */
          uint64_t capacity;    /* Capacity of volume */
          uint64_t space;       /* Space left on volume */
          uint64_t ptoc_fwa;    /* First word address of PTOC */
          int      reserved[3]; /* Reserved space */
          time_t   modification_time;/* Last modification time */
          time_t   mount_time;  /* Last mount time */

          uchar_t  bar_code[BARCODE_LEN + 1];/* Bar code (zero filled) */
          time_t   lvtime;      /* Last verified time */
          uint64_t lvpos;       /* Last verified position */

     The  last  verified  time  and   position   are   valid   if
     CS_DIV(status) is non-zero.

RETURN VALUES
     Upon successful completion the  number  of  catalog  entries
     obtained  is returned.  Otherwise, a value of -1 is returned
     and errno is set to indicate the error.

ERRORS
     sam_getcataloglv() fails if one or more of the following are
     true:

     EBADF               The catalog handle provided is invalid.

     EFAULT              buf is an invalid address.

     EOVERFLOW           The catalog  library  software  returned
                         more information than was requested.

     ENOENT              This is no longer an active catalog.

     EINVAL              The buffer size provided is invalid,  or
                         start_entry  or  end_entry  is  invalid.
                         (Either start_entry is less  than  zero,
                         end_entry  is greater than the number of
                         entries in the catalog,  or  start_entry
                         is greater than end_entry.)

     E2BIG               For sam_getcatalog() only.  The capacity
                         or  space  is larger than UINT_MAX.  Use
                         sam_getcataloglv().

     sam_closecat(3), sam_opencat(3), tpverify(1M).