doc/man-pages/pod1/up.pod

   1 =head1 NAME
   2
   3 up - Recursively copy directories, preserving AFS metadata
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<up> [B<-v>] [B<-1>] [B<-f>] [B<-r>] [B<-x>] [B<-m>]
  11     <I<source directory>> <I<destination directory>>
  12
  13 =for html
  14 </div>
  15
  16 =head1 DESCRIPTION
  17
  18 The B<up> command recursively copies the files and subdirectories in a
  19 specified source directory to a specified destination directory.  The
  20 command interpreter changes the destination directory and the files and
  21 subdirectories in it in the following ways:
  22
  23 =over 4
  24
  25 =item *
  26
  27 It copies the source directory's access control list (ACL) to the
  28 destination directory and its subdirectories, overwriting any existing
  29 ACLs.
  30
  31 =item *
  32
  33 If the issuer is logged on as the local superuser root and has AFS tokens
  34 as a member of the group system:administrators, then the source
  35 directory's owner (as reported by the C<ls -ld> command) becomes the owner
  36 of the destination directory and all files and subdirectories in
  37 it. Otherwise, the issuer's user name is recorded as the owner.
  38
  39 =item *
  40
  41 If a file or directory exists in both the source and destination
  42 directories, the source version overwrites the destination version. The
  43 overwrite operation fails if the first (user) C<w> (write) mode bit is
  44 turned off on the version in the destination directory, unless the B<-f>
  45 flag is provided.
  46
  47 =item *
  48
  49 The modification timestamp on a file (as displayed by the C<ls -l>
  50 command) in the source directory overwrites the timestamp on a file of the
  51 same name in the destination directory, but the timestamp on an existing
  52 subdirectory in the destination directory remains unchanged. If the
  53 command creates a new subdirectory in the destination directory, the new
  54 subdirectory's timestamp is set to the time of the copy operation, rather
  55 than to the timestamp that the subdirectory has in the source directory.
  56
  57 =back
  58
  59 The up command is idempotent, meaning that if its execution is interrupted
  60 by a network, server machine, or process outage, then a subsequent reissue
  61 of the same command continues from the interruption point, rather than
  62 starting over at the beginning. This saves time and reduces network
  63 traffic in comparison to the UNIX commands that provide similar
  64 functionality.
  65
  66 The B<up> command returns a status code of C<0> (zero) only if it
  67 succeeds. Otherwise, it returns a status code of C<1> (one).
  68
  69 This command does not use the syntax conventions of the AFS command
  70 suites. Provide the command name and all option names in full.
  71
  72 =head1 OPTIONS
  73
  74 =over 4
  75
  76 =item B<-v>
  77
  78 Prints a detailed trace to the standard output stream as the command runs.
  79
  80 =item B<-1>
  81
  82 Copies only the files in the top level source directory to the destination
  83 directory, rather than copying recursively through subdirectories. The
  84 source directory's ACL still overwrites the destination directory's. (This
  85 is the number one, not the letter C<l>.)
  86
  87 =item B<-f>
  88
  89 Overwrites existing directories, subdirectories, and files even if the
  90 first (user) C<w> (write) mode bit is turned off on the version in the
  91 destination directory.
  92
  93 =item B<-m>
  94
  95 Recognize and copy mount points rather than traversing the volumes they
  96 reference during the recursive copy operation.  Without B<-m>, B<up>'s
  97 default behavior is to copy the contents of all volumes and subvolumes
  98 mounted under the source directory into the volume containing the
  99 destination directory.
 100
 101 =item B<-r>
 102
 103 Creates a backup copy of all files overwritten in the destination
 104 directory and its subdirectories, by adding a C<.old> extension to each
 105 filename.
 106
 107 =item B<-x>
 108
 109 Sets the modification timestamp on each file to the time of the copying
 110 operation.
 111
 112 =item I<source directory>
 113
 114 Names the directory to copy recursively.
 115
 116 =item I<destination directory>
 117
 118 Names the directory to which to copy. It does not have to exist already.
 119
 120 =back
 121
 122 =head1 EXAMPLES
 123
 124 The following command copies the contents of the directory F<dir1> to
 125 directory F<dir2>:
 126
 127    % up dir1 dir2
 128
 129 =head1 PRIVILEGE REQUIRED
 130
 131 The issuer must have the C<a> (administer) permission on the ACL of both
 132 the source and destination directories.
 133
 134 =head1 COPYRIGHT
 135
 136 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 137
 138 This documentation is covered by the IBM Public License Version 1.0.  It was
 139 converted from HTML to POD by software written by Chas Williams and Russ
 140 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.