sam_stage(3)

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 Sun StorageTek SAM-FS or Sun SAM-QFS 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(3)). The stage -n attribute is not supported on Sun SAM-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.

SEE ALSO
stage(1), ssum(1).

sam-stagealld(1M), mount_samfs(1M).

mmap(2), write(2).

sam_ssum(3).