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 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  opti-
               cal file label.

     group_id  The file's group ID. It is written into the  opti-
               cal 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.  Other-
     wise, 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  com-
                         ponent 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 com-
                         ponent    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).