doc/xml/AdminReference/sect1/up.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="up1">
   3   <refmeta>
   4     <refentrytitle>up</refentrytitle>
   5     <manvolnum>1</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>up</refname>
   9     <refpurpose>Recursively copy directories, preserving AFS metadata</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Synopsis</title>
  13     <para><emphasis role="bold">up</emphasis> [<emphasis role="bold">-v</emphasis>] [<emphasis role="bold">-1</emphasis>] [<emphasis role="bold">-f</emphasis>] [<emphasis role="bold">-r</emphasis>] [<emphasis role="bold">-x</emphasis>]
  14         &lt;<emphasis>source directory</emphasis>&gt; &lt;<emphasis>destination directory</emphasis>&gt;</para>
  15
  16   </refsect1>
  17   <refsect1>
  18     <title>Description</title>
  19     <para>The <emphasis role="bold">up</emphasis> command recursively copies the files and subdirectories in a
  20     specified source directory to a specified destination directory.  The
  21     command interpreter changes the destination directory and the files and
  22     subdirectories in it in the following ways:</para>
  23
  24     <itemizedlist>
  25       <listitem>
  26         <para>It copies the source directory's access control list (ACL) to the
  27         destination directory and its subdirectories, overwriting any existing
  28         ACLs.</para>
  29
  30       </listitem>
  31       <listitem>
  32         <para>If the issuer is logged on as the local superuser root and has AFS tokens
  33         as a member of the group system:administrators, then the source
  34         directory's owner (as reported by the <computeroutput>ls -ld</computeroutput> command) becomes the owner
  35         of the destination directory and all files and subdirectories in
  36         it. Otherwise, the issuer's user name is recorded as the owner.</para>
  37
  38       </listitem>
  39       <listitem>
  40         <para>If a file or directory exists in both the source and destination
  41         directories, the source version overwrites the destination version. The
  42         overwrite operation fails if the first (user) <computeroutput>w</computeroutput> (write) mode bit is
  43         turned off on the version in the destination directory, unless the <emphasis role="bold">-f</emphasis>
  44         flag is provided.</para>
  45
  46       </listitem>
  47       <listitem>
  48         <para>The modification timestamp on a file (as displayed by the <computeroutput>ls -l</computeroutput>
  49         command) in the source directory overwrites the timestamp on a file of the
  50         same name in the destination directory, but the timestamp on an existing
  51         subdirectory in the destination directory remains unchanged. If the
  52         command creates a new subdirectory in the destination directory, the new
  53         subdirectory's timestamp is set to the time of the copy operation, rather
  54         than to the timestamp that the subdirectory has in the source directory.</para>
  55
  56       </listitem>
  57     </itemizedlist>
  58     <para>The up command is idempotent, meaning that if its execution is interrupted
  59     by a network, server machine, or process outage, then a subsequent reissue
  60     of the same command continues from the interruption point, rather than
  61     starting over at the beginning. This saves time and reduces network
  62     traffic in comparison to the UNIX commands that provide similar
  63     functionality.</para>
  64
  65     <para>The <emphasis role="bold">up</emphasis> command returns a status code of <computeroutput>0</computeroutput> (zero) only if it
  66     succeeds. Otherwise, it returns a status code of <computeroutput>1</computeroutput> (one).</para>
  67
  68     <para>This command does not use the syntax conventions of the AFS command
  69     suites. Provide the command name and all option names in full.</para>
  70
  71   </refsect1>
  72   <refsect1>
  73     <title>Options</title>
  74     <variablelist>
  75       <varlistentry>
  76         <term><emphasis role="bold">-v</emphasis></term>
  77         <listitem>
  78           <para>Prints a detailed trace to the standard output stream as the command runs.</para>
  79
  80         </listitem>
  81       </varlistentry>
  82       <varlistentry>
  83         <term><emphasis role="bold">-1</emphasis></term>
  84         <listitem>
  85           <para>Copies only the files in the top level source directory to the destination
  86           directory, rather than copying recursively through subdirectories. The
  87           source directory's ACL still overwrites the destination directory's. (This
  88           is the number one, not the letter <computeroutput>l</computeroutput>.)</para>
  89
  90         </listitem>
  91       </varlistentry>
  92       <varlistentry>
  93         <term><emphasis role="bold">-f</emphasis></term>
  94         <listitem>
  95           <para>Overwrites existing directories, subdirectories, and files even if the
  96           first (user) <computeroutput>w</computeroutput> (write) mode bit is turned off on the version in the
  97           destination directory.</para>
  98
  99         </listitem>
 100       </varlistentry>
 101       <varlistentry>
 102         <term><emphasis role="bold">-r</emphasis></term>
 103         <listitem>
 104           <para>Creates a backup copy of all files overwritten in the destination
 105           directory and its subdirectories, by adding a <computeroutput>.old</computeroutput> extension to each
 106           filename.</para>
 107
 108         </listitem>
 109       </varlistentry>
 110       <varlistentry>
 111         <term><emphasis role="bold">-x</emphasis></term>
 112         <listitem>
 113           <para>Sets the modification timestamp on each file to the time of the copying
 114           operation.</para>
 115
 116         </listitem>
 117       </varlistentry>
 118       <varlistentry>
 119         <term><emphasis>source directory</emphasis></term>
 120         <listitem>
 121           <para>Names the directory to copy recursively.</para>
 122
 123         </listitem>
 124       </varlistentry>
 125       <varlistentry>
 126         <term><emphasis>destination directory</emphasis></term>
 127         <listitem>
 128           <para>Names the directory to which to copy. It does not have to exist already.</para>
 129
 130         </listitem>
 131       </varlistentry>
 132     </variablelist>
 133   </refsect1>
 134   <refsect1>
 135     <title>Examples</title>
 136     <para>The following command copies the contents of the directory <replaceable>dir1</replaceable> to
 137     directory <replaceable>dir2</replaceable>:</para>
 138
 139 <programlisting>
 140    % up dir1 dir2
 141
 142 </programlisting>
 143     </refsect1>
 144     <refsect1>
 145       <title>Privilege Required</title>
 146       <para>The issuer must have the <computeroutput>a</computeroutput> (administer) permission on the ACL of both
 147       the source and destination directories.</para>
 148
 149     </refsect1>
 150     <refsect1>
 151       <title>Copyright</title>
 152       <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 153
 154       <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 155       converted from HTML to POD by software written by Chas Williams and Russ
 156       Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 157
 158     </refsect1>
 159   </refentry>