[hcoop/debian/openafs.git] / doc / man-pages / pod1 / up.pod

=head1 NAME

up - Recursively copy directories, preserving AFS metadata

=head1 SYNOPSIS

=for html
<div class="synopsis">

B<up> [B<-v>] [B<-1>] [B<-f>] [B<-r>] [B<-x>] [B<-m>]
    <I<source directory>> <I<destination directory>>

=for html
</div>

=head1 DESCRIPTION

The B<up> command recursively copies the files and subdirectories in a
specified source directory to a specified destination directory.  The
command interpreter changes the destination directory and the files and
subdirectories in it in the following ways:

=over 4

=item *

It copies the source directory's access control list (ACL) to the
destination directory and its subdirectories, overwriting any existing
ACLs.

=item *

If the issuer is logged on as the local superuser root and has AFS tokens
as a member of the group system:administrators, then the source
directory's owner (as reported by the C<ls -ld> command) becomes the owner
of the destination directory and all files and subdirectories in
it. Otherwise, the issuer's user name is recorded as the owner.

=item *

If a file or directory exists in both the source and destination
directories, the source version overwrites the destination version. The
overwrite operation fails if the first (user) C<w> (write) mode bit is
turned off on the version in the destination directory, unless the B<-f>
flag is provided.

=item *

The modification timestamp on a file (as displayed by the C<ls -l>
command) in the source directory overwrites the timestamp on a file of the
same name in the destination directory, but the timestamp on an existing
subdirectory in the destination directory remains unchanged. If the
command creates a new subdirectory in the destination directory, the new
subdirectory's timestamp is set to the time of the copy operation, rather
than to the timestamp that the subdirectory has in the source directory.

=back

The up command is idempotent, meaning that if its execution is interrupted
by a network, server machine, or process outage, then a subsequent reissue
of the same command continues from the interruption point, rather than
starting over at the beginning. This saves time and reduces network
traffic in comparison to the UNIX commands that provide similar
functionality.

The B<up> command returns a status code of C<0> (zero) only if it
succeeds. Otherwise, it returns a status code of C<1> (one).

This command does not use the syntax conventions of the AFS command
suites. Provide the command name and all option names in full.

=head1 OPTIONS

=over 4

=item B<-v>

Prints a detailed trace to the standard output stream as the command runs.

=item B<-1>

Copies only the files in the top level source directory to the destination
directory, rather than copying recursively through subdirectories. The
source directory's ACL still overwrites the destination directory's. (This
is the number one, not the letter C<l>.)

=item B<-f>

Overwrites existing directories, subdirectories, and files even if the
first (user) C<w> (write) mode bit is turned off on the version in the
destination directory.

=item B<-m>

Recognize and copy mount points rather than traversing the volumes they
reference during the recursive copy operation.  Without B<-m>, B<up>'s
default behavior is to copy the contents of all volumes and subvolumes
mounted under the source directory into the volume containing the
destination directory.

=item B<-r>

Creates a backup copy of all files overwritten in the destination
directory and its subdirectories, by adding a C<.old> extension to each
filename.

=item B<-x>

Sets the modification timestamp on each file to the time of the copying
operation.

=item I<source directory>

Names the directory to copy recursively.

=item I<destination directory>

Names the directory to which to copy. It does not have to exist already.

=back

=head1 EXAMPLES

The following command copies the contents of the directory F<dir1> to
directory F<dir2>:

   % up dir1 dir2

=head1 PRIVILEGE REQUIRED

The issuer must have the C<a> (administer) permission on the ACL of both
the source and destination directories.

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

This documentation is covered by the IBM Public License Version 1.0.  It was
converted from HTML to POD by software written by Chas Williams and Russ
Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
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.