stage(1)

NAME
     stage - Set staging attributes and copy  off-line  files  to
     disk

SYNOPSIS
     stage [-a] [-c n] [-d] [-f] [-w] [-n] [-p] [-V] [-x]
     filename...

     stage [-a] [-c n] [-d] [-f] [-w] [-n] [-p] [-V] [-x] -r
     dirname...[filename...]

AVAILABILITY
     SUNWqfs

     SUNWsamfs

DESCRIPTION
     stage sets  staging  attributes  on  a  directory  or  file,
     transfers  one or more off-line files from the archive media
     to magnetic disk, or  cancels  a  pending  or  active  stage
     request.  By default, staging is automatically done when the
     file is accessed.  If none of the -a, -d, -n, or -x  options
     is specified, staging is initiated.

     When stage attributes are  set  on  a  directory,  files  or
     directories  subsequently  created in that directory inherit
     those attributes.

     Stage attributes may be set only by the owner of the file or
     the  superuser.  Staging can be initiated or canceled either
     by the owner, superuser, or other user with read or  execute
     permission.

OPTIONS
     -a   Set 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 attri-
          bute set, the file pointed to by the symbolic  link  is
          staged.  Not valid with stage never attribute -n.

     -c n Stage from the archive copy number n.

     -d   Returns staging attributes on the file to the  default.
          When  this option is specified the attributes are first
          reset to  the  default,  then  other  attribute-setting
          options  are  processed.  The only action taken is that
          attributes are reset.

     -f   Do not report errors.

     -w   Wait for each file to be  staged  back  on-line  before
          completing.  Not valid with -d, or -n.

          Note that when staging many files at once (such as with
          stage  -r -w .)  the "-w" option causes each file to be
          completely staged before the stage request for the next
          file is issued.  This does not allow the system to sort
          the stage requests in the  order  that  the  files  are
          archived  on  the media.  In order to get the best per-
          formance in this situation, do the following:

            stage -r .
            stage -r -w .

     -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  stage  -n
          attribute  is set.  The stage -n attribute is not valid
          with the associative staging attribute -a.   The  stage
          -n  attribute is not valid with the checksum use attri-
          bute (ssum -u).  The stage -n  attribute  is  not  sup-
          ported  on a Sun SAM-QFS shared file system client; the
          entire file is staged when accessed  on  a  client.  If
          stage -n is issued while the file is being staged, EIN-
          VAL is returned.

     -p   Specifies  that  the  offline  regular  file's  partial
          blocks be staged.

     -r   Recursively performs the operation (staging or  setting
          staging  attributes)  on  any  files  contained  in the
          specified dirname or its subdirectories.

     -V   Turns on verbose display.  A message will be  displayed
          for each file on which a stage will be attempted.

     -x   Cancel a pending or active stage request for the  named
          file(s).

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
     release(1), archive(1), ssum(1),  mount_samfs(1M),  mmap(2),
     write(2)