sam_unarchive(3)

NAME
     sam_unarchive - Removes archive copies for a file or  directory

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

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

     int sam_unarchive(const char *path, int num_opts, ... );

DESCRIPTION
     sam_unarchive() lets you remove an archive copy of a file or
     a directory using a Sun Storage Archive Manager system call.
     path is the file of which to delete  archive  entries,  fol-
     lowed by a sequence of num_opts input characters or options.
     Individual options are described below.

     For example, if you have used the sam_archive(3) function to
     request   that   a   file  be  archived,  you  can  use  the
     sam_unarchive(3) function to delete that archive copy.   The
     specifications  for  the archive copy (c copy_no) and/or the
     media type and VSN (m media_type  [v vsn])  determine  which
     archive copy is deleted.

     There are several  ways  to  specify  one  or  more  archive
     entries to be unarchived. These ways are as follows:

     o  By copy number

     o  By copy number, media type, and VSN

     o  By copy number and media type

     o  By media type

     o  By media type and VSN

OPTIONS
     c copy_no
          Deletes the specified archive copy_no.  Specify  1,  2,
          3,  or  4  for copy_no.  If one or more 'c' options are
          are specified, only those archive copies (1, 2,  3,  or
          4)  are  deleted.   Either a "c copy_no" or a "m media"
          option must be specified.

     M    Unarchives metadata only.  This  includes  directories,
          the  segment index, and removable media files.  Regular
          files and symbolic links are not  unarchived.   If  you
          are  unarchiving  a directory, you must specify the "M"
          option.

     m media
          Deletes all archive copies on the specified media_type.
          For the list of possible media_type specifications, see
          the mcf(4) man page.  Either a  "c  copy_no"  or  a  "m
          media"  option  must be specified.  If you specify a "m
          media" option, you can also specify a "v vsn" option.

     o    Specifies that the  file  must  be  online  before  its
          archive  entry  is deleted. If the file is offline, the
          sam_unarchive function stages the file to  disk  before
          deleting any entries.

     v vsn
          Deletes the archive copies on vsn.  For vsn, specify  a
          volume  serial  name  (VSN).   If you specify a "v vsn"
          option, you must also specify a "m media" option.

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_unarchive() fails if one or more of  the  following  are
     true:

     EINVAL              An invalid option was specified, or  the
                         file  is  neither  a  regular file nor a
                         directory.

     EPERM               Not the owner or superuser.

     EFAULT              Argument points to an illegal address.

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

     ELOOP               Too many symbolic links were encountered
                         in translating path.

     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.

NOTE
     If the last (undamaged) copy of a file would be  unarchived,
     sam_unarchive would not unarchive that copy.

SEE ALSO
     unarchive(1m), archive(1m), sam_archive(3), mcf(4)