sam_advise(3)

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  a SAM-QFS 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  compati-
          bility.

     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.  Other-
     wise, 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 superuser.

     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 com-
                         ponent    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.

SEE ALSO
     setfa(1),     sam_setfa(3),     directio(3C),     mlock(3C),
     mount_samfs(1M), mcf(4)