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 an Oracle HSM system call. path is the file of which to delete archive entries, followed by a sequence of num_opts input characters or options. Individual options are described below.

For example, if you have used the sam_archive (3x) 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:

By copy number
By copy number, media type, and VSN
By copy number and media type
By media type
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. Otherwise, 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 super-user.
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 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.

NOTE

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