NAME

sam_stage - Sets stage attributes on a file

SYNOPSIS

cc [ flag … ] file … -L∕opt∕SUNWsamfs∕lib -lsam [ library … ]

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

int sam_stage(const char * path , const char * ops );

DESCRIPTION

sam_stage() sets stage attributes on a file or directory using a StorageTek QFS or Oracle HSM system call. path is the file on which to set the attributes. ops is the character string of options, for example: dn. Individual options are described below.

OPTIONS

a: Sets the associative staging attribute on the file or directory. Associative staging is activated when a regular file that has the associative staging attribute set is staged. All files in the same directory that have the associative staging attribute set are staged. If a symbolic link has the associative staging attribute set, the file pointed to by the symbolic link is staged. Not valid with stage never attribute -n.
d: Return the stage attributes on the file to the default, i.e. stage automatically as needed. When this option is specified attributes are reset to the default. If it is used, it should be the first character in the string.
i: Specifies that the file be staged immediately.
n: Specifies that the file never be automatically staged. The file will be read directly from the archive media. The mmap function is not supported if the sam_stage n attribute is set. The sam_stage n attribute is not valid with the associative staging attribute a. The sam_stage n attribute is not valid with either of the checksum g (generate) or u (use) attributes. (See ssum (1) or sam_ssum (3x)). The stage -n attribute is not supported on StorageTek QFS shared file system clients; the entire file is staged when accessed on a client.
p: Stage the partial blocks back online.
s: Disable associative staging for the current stage. This is only useful with the i option. This causes only the named file to be staged, not other files in the same directory with the associative attribute set.
w: Wait for the file to be staged back on-line before completing. Not valid with d or n.
1, 2, 3, 4: Stage in the archive copy specified by the 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_stage() fails if one or more of the following are true:

EINVAL: An invalid option was specified
EPERM: Not the owner or super-user.
ENXIO: No archive copy exists, or the specified archive copy does not exist.
EFAULT: path or ops points to an illegal address.
EINTR: A signal was caught during the sam_stage() 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.
ENOTSUP: License does not support option.

NOTE

If the application writes (see write (2)) to a file or the application mmaps (see mmap(2)) a file with prot set to PROT_WRITE, the file is staged in and the application waits until the stage has completed. The stage -n attribute is ignored and the file is completely staged back online.