NAME

sam_advise - Provides advice to the file system

SYNOPSIS

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

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

int sam_advise(const int fildes , const char * ops );

DESCRIPTION

sam_advise() provides advice about expected behavior of the application when accessing data in the file associated with the open file descriptor, fildes. sam_advise() provides advice for a file using an Oracle HSM ioctl call. The last caller of sam_advise() sets the advice for all applications using the file. The last close of the file sets the advice back to the default mode. ops is the character string of options, for example: "dw". Individual options are described below.

OPTIONS

b: Advises the system to use buffered (paged) I∕O. The default I∕O mode is buffered (uses the page cache). At the last close, the type of I∕O is set back to paged or direct based on the mount option forcedirectio or the directio attribute set by the setfa command.
d: Return the advice on the file to the default, i.e. the qwrite is reset to the mount setting. When this option is specified, the advice is reset to the default. If it is used, it should be the first character in the string.
p: Obsolete. Now does nothing, but remains for compatibility.
r: Advises the system to use direct (raw) I∕O (see directio (3C) for Solaris 2.6 and above). The default I∕O mode is buffered (uses the page cache). At the last close, the type of I∕O is set back to paged or direct based on the mount option forcedirectio or the directio attribute set by the setfa command.
w: Advises the system to enable simultaneous reads and writes to the same file from different threads. See the qwrite parameter on the mount command. The w option is only supported by the ma equipment type file system. (See man mcf (4)).

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

EINVAL: An invalid option was specified, or the file is not a regular file.
EPERM: Not the owner or super-user.
EFAULT: path or ops points to an illegal address.
EINTR: A signal was caught during the sam_advise() 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.