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 QFS or 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 reg-
          ular 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 attri-
          bute 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 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 com-
          pleting.  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.  Other-
     wise, 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 superuser.

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

     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).