sect5/package.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="package5">
   3   <refmeta>
   4     <refentrytitle>package</refentrytitle>
   5     <manvolnum>5</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>package</refname>
   9     <refpurpose>Provides instructions for the package command</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Description</title>
  13     <para>The package configuration file defines the file system elements that the
  14     <emphasis role="bold">package</emphasis> command creates or alters on the local disk of an AFS client
  15     machine it is configuring. Use the <emphasis role="bold">-config</emphasis> or <emphasis role="bold">-fullconfig</emphasis> argument
  16     to the <emphasis role="bold">package</emphasis> command to identify the configuration file to use.</para>
  17
  18     <refsect2>
  19       <title>Summary of Configuration File Instructions</title>
  20       <para>The configuration file can include one or more instances of each of the
  21       following instructions, each on its own line. A more detailed description
  22       of each instruction's syntax follows this list.</para>
  23
  24       <variablelist>
  25         <varlistentry>
  26           <term>B</term>
  27           <listitem>
  28             <para>Defines a block special device, such as a disk, which deals with input in
  29             units of multi-byte command blocks.</para>
  30
  31           </listitem>
  32         </varlistentry>
  33         <varlistentry>
  34           <term>C</term>
  35           <listitem>
  36             <para>Defines a character special device, such as a terminal or tty, which deals
  37             with input in single character units.</para>
  38
  39           </listitem>
  40         </varlistentry>
  41         <varlistentry>
  42           <term>D</term>
  43           <listitem>
  44             <para>Creates a directory.</para>
  45
  46           </listitem>
  47         </varlistentry>
  48         <varlistentry>
  49           <term>F</term>
  50           <listitem>
  51             <para>Creates or alters a file to match the contents of a specified source file.</para>
  52
  53           </listitem>
  54         </varlistentry>
  55         <varlistentry>
  56           <term>L</term>
  57           <listitem>
  58             <para>Creates a symbolic link.</para>
  59
  60           </listitem>
  61         </varlistentry>
  62         <varlistentry>
  63           <term>S</term>
  64           <listitem>
  65             <para>Defines a socket, which is a communications device for UDP and TCP/IP
  66             connections.</para>
  67
  68           </listitem>
  69         </varlistentry>
  70         <varlistentry>
  71           <term>%define</term>
  72           <listitem>
  73             <para>Defines a variable or declares a string as defined.</para>
  74
  75           </listitem>
  76         </varlistentry>
  77         <varlistentry>
  78           <term>%ifdef</term>
  79           <listitem>
  80             <para>Specifies an action to perform if a certain string is declared or defined.</para>
  81
  82           </listitem>
  83         </varlistentry>
  84         <varlistentry>
  85           <term>%ifndef</term>
  86           <listitem>
  87             <para>Specifies an action to perform if a certain string is not declared or
  88             defined.</para>
  89
  90           </listitem>
  91         </varlistentry>
  92         <varlistentry>
  93           <term>%include</term>
  94           <listitem>
  95             <para>Includes a library file.</para>
  96
  97           </listitem>
  98         </varlistentry>
  99         <varlistentry>
 100           <term>%undef</term>
 101           <listitem>
 102             <para>Declares a string not to be defined, or a variable no longer to have a
 103             value.</para>
 104
 105           </listitem>
 106         </varlistentry>
 107       </variablelist>
 108     </refsect2>
 109     <refsect2>
 110       <title>The B and C Instructions for Defining Special Devices</title>
 111       <para>The <computeroutput>B</computeroutput> instruction in a package configuration file defines a block
 112       special device, such as a disk, that deals with input in units of
 113       multi-byte command blocks. The <computeroutput>C</computeroutput> instruction defines a character
 114       special device, such as a terminal or tty, that deals with input in single
 115       character units. They share a common syntax:</para>
 116
 117 <programlisting>
 118    (B | C) &amp;lt;device&amp;gt; &amp;lt;major&amp;gt; &amp;lt;minor&amp;gt; &amp;lt;owner&amp;gt; &amp;lt;group&amp;gt; &amp;lt;mode&amp;gt;
 119
 120 </programlisting>
 121         <para>where</para>
 122
 123         <variablelist>
 124           <varlistentry>
 125             <term>B</term>
 126             <listitem>
 127               <para>Indicates the definition of a block special device. It must be a capital
 128               letter.</para>
 129
 130             </listitem>
 131           </varlistentry>
 132           <varlistentry>
 133             <term>C</term>
 134             <listitem>
 135               <para>Indicates the definition of character special device. It must be a capital
 136               letter.</para>
 137
 138             </listitem>
 139           </varlistentry>
 140           <varlistentry>
 141             <term>&lt;device&gt;</term>
 142             <listitem>
 143               <para>Names the special device to define. To learn the name format appropriate
 144               to the machine's system type, consult the hardware or operating system
 145               documentation.</para>
 146
 147             </listitem>
 148           </varlistentry>
 149           <varlistentry>
 150             <term>&lt;major&gt;</term>
 151             <listitem>
 152               <para>Specifies the device's major device number in decimal format.  To learn
 153               the correct value for the machine's system type, consult the hardware or
 154               operating system documentation.</para>
 155
 156             </listitem>
 157           </varlistentry>
 158           <varlistentry>
 159             <term>&lt;minor&gt;</term>
 160             <listitem>
 161               <para>Specifies the device's minor device number in one of hexadecimal, octal,
 162               or decimal format. Precede a hexadecimal number with the string <computeroutput>0x</computeroutput>
 163               (zero and the letter <computeroutput>x</computeroutput>) or an octal number with a <computeroutput>0</computeroutput> (zero). A number
 164               without either prefix is interpreted as a decimal. To learn the correct
 165               value for the machine's system type, consult the hardware or operating
 166               system documentation.</para>
 167
 168             </listitem>
 169           </varlistentry>
 170           <varlistentry>
 171             <term>&lt;owner&gt;</term>
 172             <listitem>
 173               <para>Specifies the username or UNIX user ID (UID) of the user to be designated
 174               the device's owner in the output from the UNIX <computeroutput>ls -l</computeroutput> command.</para>
 175
 176             </listitem>
 177           </varlistentry>
 178           <varlistentry>
 179             <term>&lt;group&gt;</term>
 180             <listitem>
 181               <para>Specifies the group name or UNIX group ID (GID) of the group to be
 182               designated the device's group in the output from the UNIX <computeroutput>ls -lg</computeroutput>
 183               command.</para>
 184
 185             </listitem>
 186           </varlistentry>
 187           <varlistentry>
 188             <term>&lt;mode&gt;</term>
 189             <listitem>
 190               <para>Defines the device's UNIX mode bits. Acceptable values are the standard
 191               three- or four-digit numbers corresponding to combinations of
 192               permissions. Examples: <computeroutput>755</computeroutput> corresponds to <computeroutput>rwxr-xr-x</computeroutput>, and <computeroutput>644</computeroutput> to
 193               <computeroutput>rw-r--r--</computeroutput>.</para>
 194
 195             </listitem>
 196           </varlistentry>
 197         </variablelist>
 198       </refsect2>
 199       <refsect2>
 200         <title>The D Instruction for Creating a Directory</title>
 201         <para>The <computeroutput>D</computeroutput> instruction in a package configuration file creates a directory
 202         on the local disk. If a symbolic link, file, or other element on the local
 203         disk has the same name, it is replaced with a directory. If the directory
 204         already exists, its owner, group, and mode bits are changed if necessary
 205         to conform with the instruction. The instruction has the following syntax:</para>
 206
 207 <programlisting>
 208    D[I&amp;lt;update_code&amp;gt;] &amp;lt;directory&amp;gt; &amp;lt;owner&amp;gt; &amp;lt;group&amp;gt; &amp;lt;mode&amp;gt;
 209
 210 </programlisting>
 211           <para>where</para>
 212
 213           <variablelist>
 214             <varlistentry>
 215               <term>D</term>
 216               <listitem>
 217                 <para>Indicates the creation of a directory. It must be a capital letter.</para>
 218
 219               </listitem>
 220             </varlistentry>
 221             <varlistentry>
 222               <term>&lt;update_code&gt;</term>
 223               <listitem>
 224                 <para>Modulates the directory creation instruction. It is optional and follows
 225                 the letter <computeroutput>D</computeroutput> directly, without an intervening space.  Choose one of the
 226                 two acceptable values:</para>
 227
 228                 <variablelist>
 229                   <varlistentry>
 230                     <term>X</term>
 231                     <listitem>
 232                       <para>Indicates that the directory is a lost+found directory (used by the
 233                       <emphasis role="bold">fsck</emphasis> program).</para>
 234
 235                     </listitem>
 236                   </varlistentry>
 237                   <varlistentry>
 238                     <term>R</term>
 239                     <listitem>
 240                       <para>Removes any subdirectory (along its contents) or file that exists in the
 241                       existing directory on the local disk but for which an instruction does not
 242                       appear in the configuration file.</para>
 243
 244                     </listitem>
 245                   </varlistentry>
 246                 </variablelist>
 247               </listitem>
 248             </varlistentry>
 249             <varlistentry>
 250               <term>&lt;directory&gt;</term>
 251               <listitem>
 252                 <para>Specifies the full pathname of the directory to create.</para>
 253
 254               </listitem>
 255             </varlistentry>
 256             <varlistentry>
 257               <term>&lt;owner&gt;</term>
 258               <listitem>
 259                 <para>Specifies the username or UNIX user ID (UID) of the user to be designated
 260                 the directory's owner in the output from the UNIX <computeroutput>ls -ld</computeroutput> command.</para>
 261
 262               </listitem>
 263             </varlistentry>
 264             <varlistentry>
 265               <term>&lt;group&gt;</term>
 266               <listitem>
 267                 <para>Specifies the name or UNIX group ID (GID) of the group to be designated
 268                 the directory's group in the output from the UNIX <computeroutput>ls -lgd</computeroutput> command.</para>
 269
 270               </listitem>
 271             </varlistentry>
 272             <varlistentry>
 273               <term>&lt;mode&gt;</term>
 274               <listitem>
 275                 <para>Defines the directory's UNIX mode bits. Acceptable values are the standard
 276                 three- or four-digit numbers corresponding to combinations of
 277                 permissions. Examples: <computeroutput>755</computeroutput> corresponds to <computeroutput>drwxr-xr-x</computeroutput>, and <computeroutput>644</computeroutput> to
 278                 <computeroutput>drw-r--r--</computeroutput>.</para>
 279
 280               </listitem>
 281             </varlistentry>
 282           </variablelist>
 283         </refsect2>
 284         <refsect2>
 285           <title>The F Instruction for Creating or Updating a File</title>
 286           <para>The <computeroutput>F</computeroutput> instruction in a package configuration file creates or updates a
 287           file on the local disk by copying in the contents of the indicated source
 288           file, which can reside in AFS or on the local disk. If the <emphasis role="bold">package</emphasis>
 289           command interpreter cannot access the source file, it exits without
 290           executing any instruction in the configuration file.</para>
 291
 292           <para>If a file with the same name already exists on disk, the package command
 293           overwrites it with the contents of the source file, unless the <computeroutput>I</computeroutput> update
 294           code is used to prevent that. To add a <computeroutput>.old</computeroutput> extension to the current
 295           version of the file, include the <computeroutput>O</computeroutput> update code. To have the machine
 296           reboot automatically after the <emphasis role="bold">package</emphasis> program completes, include the
 297           <computeroutput>Q</computeroutput> update code.</para>
 298
 299           <para>If a symbolic link, directory, or other element on the local disk has the
 300           same name, it is replaced with the file (a directory's contents are first
 301           removed as necessary).</para>
 302
 303           <para>The instruction has the following syntax:</para>
 304
 305 <programlisting>
 306    F[&amp;lt;update_code&amp;gt;] &amp;lt;file&amp;gt; &amp;lt;source&amp;gt; [&amp;lt;owner&amp;gt; &amp;lt;group&amp;gt; &amp;lt;mode&amp;gt;]
 307
 308 </programlisting>
 309             <para>where</para>
 310
 311             <variablelist>
 312               <varlistentry>
 313                 <term>F</term>
 314                 <listitem>
 315                   <para>Indicates the creation or update of a file. It must be a capital letter.</para>
 316
 317                 </listitem>
 318               </varlistentry>
 319               <varlistentry>
 320                 <term>&lt;update_code&gt;</term>
 321                 <listitem>
 322                   <para>Modulates the file creation instruction. It is optional and follows the
 323                   letter <computeroutput>F</computeroutput> directly, without an intervening space. Choose one or more of
 324                   the four acceptable values, and list them in any order:</para>
 325
 326                   <variablelist>
 327                     <varlistentry>
 328                       <term>A</term>
 329                       <listitem>
 330                         <para>Indicates that the pathname in the &lt;source&gt; field is the complete pathname
 331                         of the source file, including the filename. If this argument is omitted,
 332                         the <emphasis role="bold">package</emphasis> command appends the pathname in the &lt;file&gt; field to the
 333                         pathname in the &lt;source&gt; field to derive the source file's full name. This
 334                         code allows the source and target filenames to differ.</para>
 335
 336                       </listitem>
 337                     </varlistentry>
 338                     <varlistentry>
 339                       <term>I</term>
 340                       <listitem>
 341                         <para>Preserves the existing file called &lt;file&gt;, rather than overwriting it.</para>
 342
 343                       </listitem>
 344                     </varlistentry>
 345                     <varlistentry>
 346                       <term>O</term>
 347                       <listitem>
 348                         <para>Saves the existing version of the file by appending a <computeroutput>.old</computeroutput> extension to
 349                         it.</para>
 350
 351                       </listitem>
 352                     </varlistentry>
 353                     <varlistentry>
 354                       <term>Q</term>
 355                       <listitem>
 356                         <para>Causes the package command to exit with status code <computeroutput>4</computeroutput> if it overwrites
 357                         the file. If the standard <emphasis role="bold">package</emphasis>-related changes have been made to the
 358                         machine's AFS initialization file, then status code <computeroutput>4</computeroutput> causes the
 359                         machine to reboot automatically. Use this code when the machine must
 360                         reboot if updates to the file are to have any effect (for example, if the
 361                         operating system file -- <replaceable>/vmunix</replaceable> or equivalent -- has changed).</para>
 362
 363                       </listitem>
 364                     </varlistentry>
 365                   </variablelist>
 366                 </listitem>
 367               </varlistentry>
 368               <varlistentry>
 369                 <term>&lt;file&gt;</term>
 370                 <listitem>
 371                   <para>Specifies the complete pathname on the local disk of the file to create or
 372                   update, including the filename as the final element.</para>
 373
 374                 </listitem>
 375               </varlistentry>
 376               <varlistentry>
 377                 <term>&lt;source&gt;</term>
 378                 <listitem>
 379                   <para>Specifies the pathname (local or AFS) of the file to copy to the local
 380                   disk.</para>
 381
 382                   <para>If the <computeroutput>A</computeroutput> update code is included, specify the source file's complete
 383                   pathname. Otherwise, the <emphasis role="bold">package</emphasis> command derives the source file's full
 384                   name by appending the <emphasis>file</emphasis> pathname to this pathname. For example, if
 385                   the <computeroutput>A</computeroutput> update code is not included and the file
 386                   <replaceable>/afs/abc.com/rs_aix42/bin/grep</replaceable> is the source file for the <replaceable>/bin/grep</replaceable>
 387                   binary, the proper value in this field is <replaceable>/afs/abc.com/rs_aix42</replaceable>.</para>
 388
 389                 </listitem>
 390               </varlistentry>
 391               <varlistentry>
 392                 <term>&lt;owner&gt;</term>
 393                 <listitem>
 394                   <para>Specifies the username or UNIX user ID (UID) of the user to be designated
 395                   the file's owner in the output from the UNIX <computeroutput>ls -l</computeroutput> command.</para>
 396
 397                   <para>To copy the source file's owner to the target file, leave this field
 398                   empty. In this case, the &lt;group&gt; and &lt;mode&gt; fields must also be empty.</para>
 399
 400                 </listitem>
 401               </varlistentry>
 402               <varlistentry>
 403                 <term>&lt;group&gt;</term>
 404                 <listitem>
 405                   <para>Specifies the name or UNIX group ID (GID) of the group to be designated
 406                   the file's group in the output from the UNIX <computeroutput>ls -lg</computeroutput> command.</para>
 407
 408                   <para>To copy the source file's group to the target file, leave this field
 409                   empty. In this case, the &lt;owner&gt; and &lt;mode&gt; fields must also be empty.</para>
 410
 411                 </listitem>
 412               </varlistentry>
 413               <varlistentry>
 414                 <term>&lt;mode&gt;</term>
 415                 <listitem>
 416                   <para>Defines the file's UNIX mode bits. Acceptable values are the standard
 417                   three- or four-digit numbers corresponding to combinations of
 418                   permissions. Examples: <computeroutput>755</computeroutput> corresponds to <computeroutput>rwxr-xr-x</computeroutput>, and <computeroutput>644</computeroutput> to
 419                   <computeroutput>rw-r--r--</computeroutput>.</para>
 420
 421                   <para>To copy the source file's mode bits to the target file, leave this field
 422                   empty. In this case, the &lt;owner&gt; and &lt;group&gt; fields must also be empty.</para>
 423
 424                 </listitem>
 425               </varlistentry>
 426             </variablelist>
 427           </refsect2>
 428           <refsect2>
 429             <title>The L Instruction for Creating a Symbolic Link</title>
 430             <para>The <computeroutput>L</computeroutput> instruction in a package configuration file creates a symbolic
 431             link on the local disk to a directory or file that exists either in AFS or
 432             elsewhere on the local disk. As with the standard UNIX <computeroutput>ln -s</computeroutput> command,
 433             the link is created even if the actual file or directory does not exist.</para>
 434
 435             <para>If a file or directory on the local disk already has the same name, the
 436             <emphasis role="bold">package</emphasis> command replaces it with a symbolic link.</para>
 437
 438             <para>The instruction has the following syntax:</para>
 439
 440 <programlisting>
 441    L[I&amp;lt;update_code&amp;gt;] &amp;lt;link&amp;gt; &amp;lt;path&amp;gt; [&amp;lt;owner&amp;gt; &amp;lt;group&amp;gt; &amp;lt;mode&amp;gt;]
 442
 443 </programlisting>
 444               <para>where</para>
 445
 446               <variablelist>
 447                 <varlistentry>
 448                   <term>L</term>
 449                   <listitem>
 450                     <para>Indicates the creation of a symbolic link. It must be a capital letter.</para>
 451
 452                   </listitem>
 453                 </varlistentry>
 454                 <varlistentry>
 455                   <term>&lt;update_code&gt;</term>
 456                   <listitem>
 457                     <para>Modulates the link creation instruction. It is optional and follows the
 458                     letter <computeroutput>L</computeroutput> directly, without an intervening space. Choose one or both of
 459                     the acceptable values, and list them in any order:</para>
 460
 461                     <variablelist>
 462                       <varlistentry>
 463                         <term>A</term>
 464                         <listitem>
 465                           <para>Indicates that the pathname in the &lt;path&gt; field is the complete pathname
 466                           of the actual directory or file (including the filename for a file). If
 467                           this argument is omitted, the <emphasis role="bold">package</emphasis> command appends the value in the
 468                           &lt;link&gt; field to the pathname in the &lt;path&gt; field to derive the actual
 469                           directory or file's full name. This code allows the name of the symbolic
 470                           link and actual directory or file to differ.</para>
 471
 472                         </listitem>
 473                       </varlistentry>
 474                       <varlistentry>
 475                         <term>I</term>
 476                         <listitem>
 477                           <para>Preserves the existing symbolic link called &lt;link&gt;, rather than
 478                           overwriting it.</para>
 479
 480                         </listitem>
 481                       </varlistentry>
 482                     </variablelist>
 483                   </listitem>
 484                 </varlistentry>
 485                 <varlistentry>
 486                   <term>&lt;link&gt;</term>
 487                   <listitem>
 488                     <para>Specifies the complete local disk pathname of the symbolic link to create.</para>
 489
 490                   </listitem>
 491                 </varlistentry>
 492                 <varlistentry>
 493                   <term>&lt;path&gt;</term>
 494                   <listitem>
 495                     <para>Specifies the pathname (local or AFS) of the directory or file to which
 496                     the link refers. If the <computeroutput>A</computeroutput> update code is included, specify the
 497                     directory or file's complete pathname. Otherwise, the <emphasis role="bold">package</emphasis> command
 498                     derives the actual directory or file's full name by appending the value in
 499                     the <emphasis>link</emphasis> field to this pathname. For example, if the <computeroutput>A</computeroutput> update code
 500                     is not included and <replaceable>/etc/ftpd</replaceable> is a symbolic link to the file
 501                     <replaceable>/afs/abc.com/sun4x_56/etc/ftpd</replaceable>, the proper value in this field is
 502                     <replaceable>/afs/abc.com/sun4x_56</replaceable>.</para>
 503
 504                     <para>The package command interpreter correctly handles pathnames that begin
 505                     with the <computeroutput>./</computeroutput> (period, slash) or <computeroutput>../</computeroutput> (two periods, slash) notation,
 506                     interpreting them relative to the current working directory from which the
 507                     <emphasis role="bold">package</emphasis> command is invoked.</para>
 508
 509                   </listitem>
 510                 </varlistentry>
 511                 <varlistentry>
 512                   <term>&lt;owner&gt;</term>
 513                   <listitem>
 514                     <para>Specifies the username or UNIX user ID (UID) of the user to be designated
 515                     the symbolic link's owner in the output from the UNIX <computeroutput>ls -l</computeroutput> command.</para>
 516
 517                     <para>To designate the issuer of the package command (usually, the local
 518                     superuser <computeroutput>root</computeroutput>) as the symbolic link's owner, leave this field
 519                     empty. In this case, the &lt;group&gt; and &lt;mode&gt; fields must also be empty.</para>
 520
 521                   </listitem>
 522                 </varlistentry>
 523                 <varlistentry>
 524                   <term>&lt;group&gt;</term>
 525                   <listitem>
 526                     <para>Specifies the name or UNIX group ID (GID) of the group to be designated
 527                     the link's group in the output from the UNIX <computeroutput>ls -lg</computeroutput> command.</para>
 528
 529                     <para>To have the symbolic link's group match the default group associated with
 530                     the <emphasis role="bold">package</emphasis> command's issuer, leave this field empty. The issuer is
 531                     usually the local superuser <computeroutput>root</computeroutput> and the default group is designated in
 532                     the issuer's entry in the local <replaceable>/etc/passwd</replaceable> file or equivalent. If this
 533                     field is left empty, the &lt;owner&gt; and &lt;mode&gt; fields must also be empty.</para>
 534
 535                   </listitem>
 536                 </varlistentry>
 537                 <varlistentry>
 538                   <term>&lt;mode&gt;</term>
 539                   <listitem>
 540                     <para>Defines the symbolic link's UNIX mode bits. Acceptable values are the
 541                     standard three- or four-digit numbers corresponding to combinations of
 542                     permissions. Examples: <computeroutput>755</computeroutput> corresponds to <computeroutput>rwxr-xr-x</computeroutput>, and <computeroutput>644</computeroutput> to
 543                     <computeroutput>rw-r--r--</computeroutput>.</para>
 544
 545                     <para>Leaving this field empty sets the symbolic link's mode bits to <computeroutput>777</computeroutput>
 546                     (<computeroutput>rwxrwxrwx</computeroutput>). In this case, the &lt;owner&gt; and &lt;group&gt; fields must also be
 547                     empty.</para>
 548
 549                   </listitem>
 550                 </varlistentry>
 551               </variablelist>
 552             </refsect2>
 553             <refsect2>
 554               <title>The S Instruction for Creating a Socket</title>
 555               <para>The <computeroutput>S</computeroutput> instruction in a package configuration file creates a socket (a
 556               communications device for UDP or TCP/IP connections) on the local
 557               disk. The instruction has the following syntax:</para>
 558
 559 <programlisting>
 560    S &amp;lt;socket&amp;gt; [&amp;lt;owner&amp;gt; &amp;lt;group&amp;gt; &amp;lt;mode&amp;gt;]
 561
 562 </programlisting>
 563                 <para>where</para>
 564
 565                 <variablelist>
 566                   <varlistentry>
 567                     <term>S</term>
 568                     <listitem>
 569                       <para>Indicates the creation of a socket. It must be a capital letter.</para>
 570
 571                     </listitem>
 572                   </varlistentry>
 573                   <varlistentry>
 574                     <term>&lt;socket&gt;</term>
 575                     <listitem>
 576                       <para>Names the socket. The proper format depends on the local machine's
 577                       operating system.</para>
 578
 579                     </listitem>
 580                   </varlistentry>
 581                   <varlistentry>
 582                     <term>&lt;owner&gt;</term>
 583                     <listitem>
 584                       <para>Specifies the username or UNIX user ID (UID) of the user to be designated
 585                       the socket's owner in the output from the UNIX <computeroutput>ls -l</computeroutput> command.</para>
 586
 587                       <para>To designate the issuer of the package command (usually, the local
 588                       superuser <computeroutput>root</computeroutput>) as the socket's owner, leave this field empty. In this
 589                       case, the &lt;group&gt; and &lt;mode&gt; fields must also be empty.</para>
 590
 591                     </listitem>
 592                   </varlistentry>
 593                   <varlistentry>
 594                     <term>&lt;group&gt;</term>
 595                     <listitem>
 596                       <para>Specifies the name or UNIX group ID (GID) of the group to be designated
 597                       the socket's group in the output from the UNIX <computeroutput>ls -lg</computeroutput> command.</para>
 598
 599                       <para>To have the symbolic link's group match the default group associated with
 600                       the <emphasis role="bold">package</emphasis> command's issuer, leave this field empty. The issuer is
 601                       usually the local superuser <computeroutput>root</computeroutput> and the default group is designated in
 602                       the issuer's entry in the local <replaceable>/etc/passwd</replaceable> file or equivalent. If this
 603                       field is left empty, the &lt;owner&gt; and &lt;mode&gt; fields must also be empty.</para>
 604
 605                     </listitem>
 606                   </varlistentry>
 607                   <varlistentry>
 608                     <term>&lt;mode&gt;</term>
 609                     <listitem>
 610                       <para>Defines the socket's UNIX mode bits. Acceptable values are the standard
 611                       three- or four-digit numbers corresponding to combinations of
 612                       permissions. Examples: <computeroutput>755</computeroutput> corresponds to <computeroutput>rwxr-xr-x</computeroutput>, and <computeroutput>644</computeroutput> to
 613                       <computeroutput>rw-r--r--</computeroutput>.</para>
 614
 615                       <para>Leaving this field empty sets the symbolic link's mode bits to <computeroutput>777</computeroutput>
 616                       (<computeroutput>rwxrwxrwx</computeroutput>), modulated by the cell's umask. In this case, the &lt;owner&gt;
 617                       and &lt;group&gt; fields must also be empty.</para>
 618
 619                     </listitem>
 620                   </varlistentry>
 621                 </variablelist>
 622               </refsect2>
 623               <refsect2>
 624                 <title>The %define or %undef Instructions</title>
 625                 <para>The <computeroutput>%define</computeroutput> instruction in a package configuration file declares or
 626                 defines a variable, depending on its number of arguments:</para>
 627
 628                 <itemizedlist>
 629                   <listitem>
 630                     <para>If followed by a single argument, it declares that argument to be
 631                     defined. The argument is then available as a controller when mentioned in
 632                     <computeroutput>%ifdef</computeroutput> and <computeroutput>%ifndef</computeroutput> statements, which evaluate to <computeroutput>true</computeroutput> and
 633                     <computeroutput>false</computeroutput> respectively.</para>
 634
 635                   </listitem>
 636                   <listitem>
 637                     <para>If followed by two arguments, it defines the second argument as the value
 638                     of the first. When the first argument appears later in this prototype or
 639                     other prototype or library files as a variable -- surrounded by curly
 640                     braces and preceded by a dollar sign, as in the example <computeroutput>${variable}</computeroutput> --
 641                     the <emphasis role="bold">package</emphasis> command interpreter substitutes the second argument for it.</para>
 642
 643                   </listitem>
 644                 </itemizedlist>
 645                 <para>The <computeroutput>%undef</computeroutput> statement negates the effect of a previous <computeroutput>%define</computeroutput>
 646                 statement, declaring its argument to be defined no longer, or to have a
 647                 value no longer if it is a variable.</para>
 648
 649                 <para>The syntax for the two types of instruction are as follows:</para>
 650
 651 <programlisting>
 652    %define &amp;lt;declaration&amp;gt;
 653    %define &amp;lt;variable&amp;gt; &amp;lt;value&amp;gt;
 654    %undef  &amp;lt;declaration&amp;gt;
 655    %undef  &amp;lt;variable&amp;gt;
 656
 657 </programlisting>
 658                   <para>where</para>
 659
 660                   <variablelist>
 661                     <varlistentry>
 662                       <term>%define</term>
 663                       <listitem>
 664                         <para>Indicates a definition statement.</para>
 665
 666                       </listitem>
 667                     </varlistentry>
 668                     <varlistentry>
 669                       <term>%undef</term>
 670                       <listitem>
 671                         <para>Indicates a statement that negates a definition.</para>
 672
 673                       </listitem>
 674                     </varlistentry>
 675                     <varlistentry>
 676                       <term>&lt;declaration&gt;</term>
 677                       <listitem>
 678                         <para>Names the string being declared by a <computeroutput>%define</computeroutput> statement, or
 679                         negated by an <computeroutput>%undef</computeroutput> statement.</para>
 680
 681                       </listitem>
 682                     </varlistentry>
 683                     <varlistentry>
 684                       <term>&lt;variable&gt;</term>
 685                       <listitem>
 686                         <para>Specifies the name of the variable that a <computeroutput>%define</computeroutput> statement is
 687                         defining, or an <computeroutput>%undef</computeroutput> statement is negating.</para>
 688
 689                       </listitem>
 690                     </varlistentry>
 691                     <varlistentry>
 692                       <term>&lt;value&gt;</term>
 693                       <listitem>
 694                         <para>Specifies the value to substitute for the string in the &lt;variable&gt; field
 695                         when it appears in the appropriate format (surrounded by curly braces and
 696                         preceded by a dollar sign, as in the example <computeroutput>${variable}</computeroutput>), in this or
 697                         other prototype and library files. It can include one or more words.</para>
 698
 699                       </listitem>
 700                     </varlistentry>
 701                   </variablelist>
 702                 </refsect2>
 703                 <refsect2>
 704                   <title>The %ifdef and %ifndef Instructions</title>
 705                   <para>The <computeroutput>%ifdef</computeroutput> instruction in a package configuration file specifies one or
 706                   more actions to perform if the indicated string has been declared by a
 707                   single-argument <computeroutput>%define</computeroutput> statement, or is a variable for which a value
 708                   has been defined by a two-argument <computeroutput>%define</computeroutput> statement.</para>
 709
 710                   <para>Similarly, the <computeroutput>%ifndef</computeroutput> instruction specifies one or more actions to
 711                   perform if the indicated string has not been declared or is a variable
 712                   without a value, either because no <computeroutput>%define</computeroutput> statement has defined it or
 713                   an <computeroutput>%undef</computeroutput> statement has undefined it.</para>
 714
 715                   <para>In both cases, the optional <computeroutput>%else</computeroutput> statement specifies one or more
 716                   alternate actions to perform if the first statement evaluates to
 717                   <computeroutput>false</computeroutput>. (For an <computeroutput>%ifdef</computeroutput> statement, the <computeroutput>%else</computeroutput> statement is executed
 718                   if the indicated string has never been declared or is a variable without a
 719                   value, or if an <computeroutput>%undef</computeroutput> statement has undefined either one; for an
 720                   <computeroutput>%ifndef</computeroutput> statement, it is executed if the string has been declared or is
 721                   a variable with a value.)</para>
 722
 723                   <para>It is possible to nest any number of <computeroutput>%ifdef</computeroutput> and <computeroutput>%ifndef</computeroutput> statements.</para>
 724
 725                   <para>The two types of statement share a common syntax:</para>
 726
 727 <programlisting>
 728    (%ifdef | %ifndef) &amp;lt;declaration&amp;gt;
 729        &amp;lt;action&amp;gt;+
 730    [%else [&amp;lt;declaration&amp;gt;]
 731        &amp;lt;alternate_action&amp;gt;+]
 732    %endif &amp;lt;declaration&amp;gt;
 733
 734 </programlisting>
 735                     <para>where</para>
 736
 737                     <variablelist>
 738                       <varlistentry>
 739                         <term>%ifdef</term>
 740                         <listitem>
 741                           <para>Indicates that the statement evaluates as true if the string in the
 742                           &lt;declaration&gt; field is declared or is a variable with a defined value.</para>
 743
 744                         </listitem>
 745                       </varlistentry>
 746                       <varlistentry>
 747                         <term>%ifndef</term>
 748                         <listitem>
 749                           <para>Indicates that the statement evaluates as true if the string in the
 750                           &lt;declaration&gt; field is not declared or is a variable without a defined
 751                           value.</para>
 752
 753                         </listitem>
 754                       </varlistentry>
 755                       <varlistentry>
 756                         <term>&lt;declaration&gt;</term>
 757                         <listitem>
 758                           <para>Specifies the string that must be declared or the variable name that must
 759                           have a defined value for an <computeroutput>%ifdef</computeroutput> statement to evaluate as <computeroutput>true</computeroutput>,
 760                           which results in the specified action being performed.  For an <computeroutput>%ifndef</computeroutput>
 761                           statement, the string must not be declared or the variable must have no
 762                           defined value for the statement to evaluate as <computeroutput>true</computeroutput>. The first and
 763                           third occurrences of &lt;declaration&gt; (the latter following the string
 764                           <computeroutput>%endif</computeroutput>) are required. The second occurrence (following the string
 765                           <computeroutput>%else</computeroutput>) is optional, serving only to clarify to which <computeroutput>%ifdef</computeroutput> or
 766                           <computeroutput>%ifndef</computeroutput> statement the <computeroutput>%else</computeroutput> statement belongs.</para>
 767
 768                         </listitem>
 769                       </varlistentry>
 770                       <varlistentry>
 771                         <term>&lt;action&gt;</term>
 772                         <listitem>
 773                           <para>Specifies each action to perform if the <computeroutput>%ifdef</computeroutput> or <computeroutput>%ifndef</computeroutput> statement
 774                           evaluates as <computeroutput>true</computeroutput>. Each action must appear on a separate
 775                           line. Acceptable types of actions are other statements beginning with a
 776                           percent sign and definition instructions.</para>
 777
 778                         </listitem>
 779                       </varlistentry>
 780                       <varlistentry>
 781                         <term>&lt;alternate_action&gt;</term>
 782                         <listitem>
 783                           <para>Specifies each action to perform if the <computeroutput>%ifdef</computeroutput> or <computeroutput>%ifndef</computeroutput> statement
 784                           evaluates to <computeroutput>false</computeroutput>. Each action must appear on a separate
 785                           line. Acceptable types of actions are other statements beginning with a
 786                           percent sign and definition instructions.</para>
 787
 788                         </listitem>
 789                       </varlistentry>
 790                     </variablelist>
 791                   </refsect2>
 792                   <refsect2>
 793                     <title>The %include Instruction for Including a Library File</title>
 794                     <para>The <computeroutput>%include</computeroutput> instruction in a package configuration file includes the
 795                     contents of the indicated library file in a configuration file that
 796                     results from the compilation of the prototype file in which the
 797                     <computeroutput>%include</computeroutput> instruction appears. It has the following syntax:</para>
 798
 799 <programlisting>
 800    %include &amp;lt;pathname&amp;gt;
 801
 802 </programlisting>
 803                       <para>where</para>
 804
 805                       <variablelist>
 806                         <varlistentry>
 807                           <term>%include</term>
 808                           <listitem>
 809                             <para>Indicates a library file include statement.</para>
 810
 811                           </listitem>
 812                         </varlistentry>
 813                         <varlistentry>
 814                           <term>&lt;pathname&gt;</term>
 815                           <listitem>
 816                             <para>Specifies the complete pathname of the library file to include. It can be
 817                             in AFS or on the local disk, and can include one or more variables.</para>
 818
 819                           </listitem>
 820                         </varlistentry>
 821                       </variablelist>
 822                     </refsect2>
 823                   </refsect1>
 824                   <refsect1>
 825                     <title>Cautions</title>
 826                     <para>The configuration file must be completely correct. If there are any syntax
 827                     errors or incorrect values, the <emphasis role="bold">package</emphasis> command interpreter exits
 828                     without executing any instruction.</para>
 829
 830                   </refsect1>
 831                   <refsect1>
 832                     <title>Examples</title>
 833                     <para>The following example <computeroutput>B</computeroutput> and <computeroutput>C</computeroutput> instructions define a disk
 834                     <replaceable>/dev/hd0a</replaceable> with major and minor device numbers <computeroutput>1</computeroutput> and <computeroutput>0</computeroutput> and mode
 835                     bits of <computeroutput>-rw-r--r--</computeroutput>, and a tty <replaceable>/dev/ttyp5</replaceable> with major and minor device
 836                     numbers <computeroutput>6</computeroutput> and <computeroutput>5</computeroutput> and mode bits of <computeroutput>-rw-rw-rw</computeroutput>. In both cases, the
 837                     owner is <computeroutput>root</computeroutput> and the owning group <computeroutput>wheel</computeroutput>.</para>
 838
 839 <programlisting>
 840    B /dev/hd0a 1 0 root wheel 644
 841    C /dev/ttyp5 6 5 root wheel 666
 842
 843 </programlisting>
 844                       <para>The following example <computeroutput>D</computeroutput> instruction creates the local <replaceable>/usr</replaceable> directory
 845                       with owner <computeroutput>root</computeroutput> and group <computeroutput>wheel</computeroutput> and mode bits of <computeroutput>drwxr-xr-x</computeroutput>. The
 846                       <computeroutput>R</computeroutput> update code removes any files and subdirectories that reside in the
 847                       <replaceable>/usr</replaceable> directory (if it already exists) but do not appear in the
 848                       configuration file.</para>
 849
 850 <programlisting>
 851    DR /usr root wheel 755
 852
 853 </programlisting>
 854                         <para>The following example <computeroutput>F</computeroutput> instruction, appropriate for a machine running
 855                         AIX 4.2 in the ABC Corporation cell, creates or updates the local disk
 856                         file <replaceable>/bin/grep</replaceable>, using <replaceable>/afs/abc.com/rs_aix42/bin/grep</replaceable> as the source.</para>
 857
 858 <programlisting>
 859    F /bin/grep /afs/abc.com/rs_aix42 root wheel 755
 860
 861 </programlisting>
 862                           <para>The next example <computeroutput>F</computeroutput> instruction creates the <replaceable>/usr/vice/etc/ThisCell</replaceable>
 863                           file and specifies an absolute pathname for the source file, as indicated
 864                           by the <computeroutput>A</computeroutput> update code. The <computeroutput>Q</computeroutput> code makes the <emphasis role="bold">package</emphasis> command return
 865                           status code 4 as it exits, prompting a reboot of the machine if the
 866                           standard <emphasis role="bold">package</emphasis>-related changes have been made to the machine's AFS
 867                           initialization file. No values are provided for the owner, group and mode
 868                           bits, so the file inherits them from the source file.</para>
 869
 870 <programlisting>
 871    FAQ /usr/vice/etc/ThisCell /afs/abc.com/common/etc/ThisCell
 872
 873 </programlisting>
 874                             <para>The following example <computeroutput>L</computeroutput> instruction, appropriate for a machine running
 875                             AIX 4.2 in the ABC Corporation cell, creates a symbolic link from
 876                             <replaceable>/etc/ftpd</replaceable> on the local disk to the file
 877                             <replaceable>/afs/abc.com/rs_aix42/etc/ftpd</replaceable>.</para>
 878
 879 <programlisting>
 880    L /etc/ftpd /afs/abc.com/rs_aix42 root wheel 644
 881
 882 </programlisting>
 883                               <para>The following example S instruction defines the socket <replaceable>/dev/printer</replaceable>.</para>
 884
 885 <programlisting>
 886    S /dev/printer root wheel 777
 887
 888 </programlisting>
 889                                 <para>The following example <computeroutput>%define</computeroutput> instruction defines the value for the
 890                                 variable <computeroutput>${diskmode}</computeroutput>. This variable is used elsewhere in the template
 891                                 to fill the &lt;owner&gt;, &lt;group&gt;, and &lt;mode&gt; fields in a <computeroutput>D</computeroutput>, <computeroutput>F</computeroutput>, or <computeroutput>L</computeroutput>
 892                                 instruction.</para>
 893
 894 <programlisting>
 895    %define diskmode root wheel 644
 896
 897 </programlisting>
 898                                   <para>The following example <computeroutput>%undef</computeroutput> instruction declares the string <emphasis role="bold">afsd</emphasis>
 899                                   not to be defined.</para>
 900
 901 <programlisting>
 902    %undef afsd
 903
 904 </programlisting>
 905                                     <para>The following example <computeroutput>%ifdef</computeroutput> instruction specifies that if the string
 906                                     <computeroutput>rs_aix42</computeroutput> is currently declared, then when the prototype file containing
 907                                     the instruction is compiled the three indicated library files are
 908                                     included. There is no alternate action defined. There must be <computeroutput>%define</computeroutput>
 909                                     statements earlier in the prototype file to declare <computeroutput>rs_aix42</computeroutput> and to
 910                                     assign a value to the <computeroutput>${wsadmin}</computeroutput> variable.</para>
 911
 912 <programlisting>
 913    %ifdef rs_aix42
 914    %include ${wsadmin}/lib/rs_aix42.readonly
 915    %include ${wsadmin}/lib/rs_aix42.generic
 916    %include ${wsadmin}/lib/rs_aix42.generic.dev
 917    %endif rs_aix42
 918
 919 </programlisting>
 920                                       <para>The following example <computeroutput>%ifndef</computeroutput> instruction, appropriate for the State
 921                                       University cell, defines <computeroutput>stateu.edu</computeroutput> as the value of the <computeroutput>${cell}</computeroutput>
 922                                       variable if it does not already have a value.</para>
 923
 924 <programlisting>
 925    %ifndef cell
 926    %define cell stateu.edu
 927    %endif cell
 928
 929 </programlisting>
 930                                         <para>The following example <computeroutput>%include</computeroutput> instruction includes the library file
 931                                         <computeroutput>base.generic</computeroutput> from the <replaceable>lib</replaceable> subdirectory of the directory in which
 932                                         <emphasis role="bold">package</emphasis>-related files reside. The <computeroutput>${wsadmin}</computeroutput> variable resolves to an
 933                                         actual pathname (such as <replaceable>/afs/abc.com/wsadmin</replaceable>) during compilation.</para>
 934
 935 <programlisting>
 936    %include ${wsadmin}/lib/base.generic
 937
 938 </programlisting>
 939                                         </refsect1>
 940                                         <refsect1>
 941                                           <title>See Also</title>
 942                                           <para><link linkend="package8">package(8)</link></para>
 943
 944                                         </refsect1>
 945                                         <refsect1>
 946                                           <title>Copyright</title>
 947                                           <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 948
 949                                           <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 950                                           converted from HTML to POD by software written by Chas Williams and Russ
 951                                           Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 952
 953                                         </refsect1>
 954                                       </refentry>