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 catalog 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 following members:

catalog table entry
status;	uint_t	Catalog entry status
media[4];	char	Media type
vsn[32];	char	VSN
access;	int	Count of accesses
capacity;	uint64_t	Capacity of volume
space;	uint64_t	Space left on volume
ptoc_fwa;	uint64_t	First word address of PTOC
reserved[3];	int	Reserved space
modification_time;	time_t	Last modification time
mount_time;	time_t	Last mount time
bar_code[BARCODE_LEN + 1];	uchar_t	Bar code (zero filled)
lvtime;	time_t	Last verified time
lvpos;	uint64_t	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().