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 to which buf points vary depending on the type of data stored:

		"POSIX rminfo structure."
flags;	ushort_t	"File mode (see mknod (2))"
media[4];	char	"Media type"
creation_time;	ulong_t	"Creation time of removable media file"
block_size;	uint_t	"Block size of file in bytes"
position;	u_longlong_t	"Position of file on the removable media"
required_size;	u_longlong_t	"Required size for optical only"

		"optical information only."
file_id[32];	char	"File identifier"
version;	int	"Version number"
owner_id[32];	char	"Owner identifier"
group_id[32];	char	"Group identifier"
info[160];	char	"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 Oracle HSM, 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."
vsn[32];	char	"Volume serial name"
length;	u_longlong_t	"Length of this section in bytes"
position;	u_longlong_t	"Position of this section"
offset;	u_longlong_t	"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.