Commit | Line | Data |
---|---|---|
805e021f CE |
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. |