sam_request(3)

NAME
sam_request - Creates a removable media file

SYNOPSIS

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

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

int sam_request(const char *path, struct sam_rminfo *buf, size_t bufsize);

DESCRIPTION
sam_request() creates a removable media file allowing access to either tape or optical disk. The removable media file is pointed to by path.

buf is a pointer to a sam_rminfo() structure into which information is placed concerning the file.

bufsize is the length of the user's buffer to which buf points. This should be equal to or greater than sizeof(struct sam_rminfo). The maximum number of overflow VSNs is 256. The following macro can be used to calculate the size of the sam_rminfo structure for n VSNs. #define SAM_RMINFO_SIZE(n) (sizeof(struct sam_rminfo) + ((n) - 1) * sizeof(struct sam_section))

The contents of the structure pointed to by buf include the following members:

 |  | /* POSIX rminfo structure. */
ushort_t | flags; | /* File mode (see mknod(2)) */
char | media[4]; | /* Media type */
ulong_t | creation_time; | /* Creation time of removable media file */
uint_t | block_size; | /* Block size of file in bytes */
U_longlong_t | position; | /* Position of file on the removable media */
U_longlong_t | required_size; | /* Required size for optical only */
 |  | /* optical information only. */
char | file_id[32]; | /* File identifier */
int | version; | /* Version number */
char | owner_id[32]; | /* Owner identifier */
char | group_id[32]; | /* Group identifier */
char | info[160]; | /* Information */
 |  | /* all media information. */
short | n_vsns; | /* Number of vsns containing file */
short | c_vsn; | /* Current vsn ordinal -- returned */
struct sam_section | section[1]; | /* VSN array - n_vsns entries */

flags
    The access flags for the file. RI_blockio uses block I/O for data transfers. Each request buffer is a block on the device. RI_bufio uses buffered I/O for data transfers. The block size is defined by block_size. RI_foreign uses block I/O for data transfers. The tape is not written by Sun SAM-FS or Sun SAM-QFS, is barcoded, write protected, and is opened for read access only.

media
    The left adjusted string which identifies the media type. See mcf(4).

creation_time
    Specifies the time the file was created. This value is not used on entry.

block_size
    The length of the block in bytes. The block_size is set in the volume labels when the removable media is labeled. This value is returned.

position
    This field can be set by superuser to specify an initial starting position for the file.

required_size
    This size in bytes may be specified. If set, this space must be left on the removable media.

file_id
    The file's ID. It is written into the optical file label.

version
    The version number of the file. It is returned.

owner_id
    The file's owner ID. It is written into the optical file label.

group_id
    The file's group ID. It is written into the optical file label.

info
    The file's optional information field. It is written into the optical file label by .

n_vsns
    Specified the number of removable media cartridges containing the file.

c_vsn
    Specifies the current removable media ordinal.

sam_section
    Specifies the array of removable media cartridges. The contents of the sam_section structure includes the following members:

 |  | /* POSIX sam_section structure. */
char | vsn[32]; | /* Volume serial name */
U_longlong_t | length; | /* Length of this section in bytes */
U_longlong_t | position; | /* Position of this section */
U_longlong_t | offset; | /* Byte offset of this section */

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

ERRORS

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

EACCES
    Search permission is denied for a component of the path prefix.

EFAULT
    buf or path points to an illegal address.

EINTR
    A signal was caught during the sam_request() function.

ELOOP
    Too many symbolic links were encountered in translating path.

EMULTIHOP
    Components of path require hopping to multiple remote machines and the file system does not allow it.

ENAMETOOLONG
    The length of the path argument exceeds {PATH_MAX}, or the length of a path component exceeds {NAME_MAX} while {_POSIX_NO_TRUNC} is in effect.

ENOENT
    The named file does not exist or is the null pathname.

ENOLINK
    path points to a remote machine and the link to that machine is no longer active.

ENOTDIR
    A component of the path prefix is not a directory.

EOVERFLOW
    A component is too large to store in the structure pointed to by buf.

ENOTSUP
    License does not support foreign tapes.

SEE ALSO
request(1).

mcf(4).