NAME

sam_setfa - Sets attributes on a file or directory

SYNOPSIS

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

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

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

DESCRIPTION

sam_setfa() sets attributes on a file or directory using an Oracle HSM system call. path is the file on which to set the attributes. ops is the character string of options, for example: "ds1". Individual options are described below.

OPTIONS

A n: Specifies the number of bytes to be allocated ahead of a write to the file. The n must be an integer and must be greater than or equal to one kilobyte and less than 4 terabytes. The n is rounded down to units of kilobytes. This option is only valid for a regular file. This option should be used when writing large files where more sequential allocation is desired. Note, when the file is closed the blocks are reset to the size of the file.
B: Specifies the direct I∕O attribute be permanently cleared for this file. This means data is transferred indirectly between the user's buffer and disk through the system's page cache. The default I∕O mode is buffered (uses the page cache). The directio attribute is persistent, remaining until specifically cleared or reset. See directio (3C) for Solaris 2.6 and above for more details.
d: Return the file attributes on the file to the default, i.e. the stripe is reset to the mount default. When this option is specified, the attributes are reset to the default. If it is used, it should be the first character in the string.
D: Specifies the direct I∕O attribute be permanently set for this file. This means data is transferred directly between the user's buffer and disk. This attribute should only be set for large block aligned sequential I∕O. The default I∕O mode is buffered (uses the page cache). Direct I∕O will not be used if the file is currently memory mapped. The directio attribute is persistent, remaining until specifically cleared or reset. See directio (3C) for Solaris 2.6 and above for more details.
g n: Specifies the number of the striped group where the file is to be preallocated. n is a number 0 .. 127. n must be a striped_group defined in the file system.
l n: Specifies the number of bytes to be preallocated to the file. The n must be an integer. This option can only be applied to a regular file. If an I∕O event attempts to extend a file preallocated with the L option, the caller receives an ENXIO error. The l option allocates using extent allocation. This means striping is not supported and the file is allocated on 1 disk device or 1 striped group. The L and l options are mutually exclusive. If the file has existing disk blocks, this option is changed to the L option.
L n: Specifies the number of bytes to be preallocated to the file. The n must be an integer. This option is only valid for a regular file. The L option allocates using standard allocation. This means striping is supported. This also means the file can be extended. The L and l options are mutually exclusive.
q: Specifies that this file will be linked to the pseudo character device driver, samaio, for the purpose of issuing asynchronous I∕O. Note, this option also sets Direct I∕O and qwrite. Setting this option may result in greater performance.
s n: Specifies the number of allocation units to be allocated before changing to the next unit. If n is 1, this means the file will stripe across all units with 1 disk allocation unit (DAU) allocated per unit. If n is 0, this means the file will be allocated on one unit until that unit has no space. The default stripe is specified at mount. (see mount_samfs (1m)). Note, EINVAL is returned if the user sets stripe 0 and mismatched stripe groups exist. Mismatched stripe groups means all striped groups do not have the same number of partitions. Striping across mismatched stripe groups is not allowed.

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_setfa() 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: path or ops points to an illegal address.
EINTR: A signal was caught during the sam_setfa() 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.