unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



tar(1)								       tar(1)



NAME

  tar -	Manipulates tape archives

SYNOPSIS

  tar function_key[bBfFEhilLmpPsSvVwzn]	[n | o]	[option_argument...] [-e
  exception]...	[-C directory]... [file...]

  tar -function_key[options] [option_argument]... [n | o]
  [option_argument...] [-e exception]... [-C directory]... [file...]

  The tar command saves	and restores multiple files on a single	file (usually
  a magnetic tape, but it can be any file).

				     Note

       [Tru64 UNIX]  The syntax	of the tar command has recently	changed. The
       minus sign (-) at the beginning of a key/option set is no longer
       optional.  If tar sees a	minus sign in front of an option that
       requires	an argument, tar expects the argument to follow	the option
       immediately.  In	order to use the original tar syntax in	existing
       scripts,	you must remove	the minus sign if more than one	option
       requiring an argument is	given.	Consider this command in the old
       form:

	    tar	-xbfp 20 /dev/ntape/tape0

       Under the new implementation, this command becomes

	    tar	xbfp 20	/dev/ntape/tape0

       or

	    tar	-xb 20 -f /dev/ntape/tape0 -p

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  tar:	XCU5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.









FUNCTION KEYS

  [Tru64 UNIX]	The function performed by tar is specified by one of the fol-
  lowing key letters:

  c   Creates a	new archive.  When writing to a	tape device, tar begins	from
      the current tape position.

  r   Writes the named files at	the end	of the specified archive.  If the
      archive is on tape, tar expects that the tape is currently positioned
      to the beginning of the archive.

  t   Lists the	contents of the	archive. If the	file argument does not res-
      trict the	operation to one or more specific directories or files,	tar
      lists all	of the file names in the archive.

  u   Adds the named files to the tape,	if the files are not already there or
      if they were modified since last copied to the tape.

  x   Extracts the named files from the	tape.  If a named file matches a
      directory	whose contents were written to the tape, this directory	is
      (recursively) extracted.	The owner, modification	time, and mode are
      restored (if possible).  If no file argument is given, the entire	con-
      tent of the tape is extracted.  If multiple entries specifying the same
      file are on the tape, the	last one overwrites all	earlier	ones.

OPTIONS

  [Tru64 UNIX]	The following options can be used with function	keys:

  b   The tar command uses the next argument as	the blocking factor for	tape
      records. The default is 20 (larger values	can be specified at the	risk
      of creating a tape archive that some systems' tape drives	might not be
      able to restore).	 Use this option only with raw magnetic	tape
      archives.	The block size is determined automatically when	reading	tapes
      (key letters x and t).

  B   [Tru64 UNIX]  Forces input and output blocking to	the blocking factor
      (see the b option).  The B option	exists so that tar can work across a
      communications channel where the blocking	cannot be maintained.

  e   [Tru64 UNIX]  The	tar command uses the next argument, exception, as the
      name of the file to be excluded from the archive.

  E   Processes	extended headers, allowing you to archive or extract extended
      UIDs and GIDs, long filenames, link-names, large files, and long user
      and group	names

  f   The tar command uses the next argument as	the name of the	archive
      instead of /dev/ntape/tapen. (See	the entry for the n option.) If	the
      name of the file is - (dash), tar	writes to standard output or reads
      from standard input, whichever is	appropriate.  Thus, tar	can be used
      as the head or tail of a filter chain.  The tar utility can also be
      used to move hierarchies with the	command:
	   cd fromdir; tar cf -	. | (cd	todir; tar xpf -)

  F   [Tru64 UNIX]  Checks certain file	names before archiving.	 Source	Code
      Control System (SCCS), Revision Control System (RCS), files named	core,
      errs, a.out, and files ending in .o are not archived.

  h   [Tru64 UNIX]  Forces tar to follow symbolic links	as if they were	nor-
      mal files	or directories.	 Normally, tar does not	follow symbolic
      links, but instead saves the link	text in	the archive.

  i   [Tru64 UNIX]  Ignores checksum errors.  The tar command writes a file
      header containing	a checksum for each file in the	archive.  When this
      option is	not specified, the system verifies the contents	of the header
      blocks by	recomputing the	checksum and stops with	a directory checksum
      error when a mismatch occurs.  When this option is specified, tar	logs
      the error	and then scans forward until it	finds a	valid header block.
      This permits restoring files from	later volumes of a multivolume
      archive without reading earlier volumes.

  l   [Tru64 UNIX]  Tells tar to complain if it	cannot resolve all of the
      links to the files dumped.  If this option is not	specified, no error
      messages are printed.

  L   [Tru64 UNIX]  Tries to create a symbolic link if tar is unsuccessful in
      its attempt to link (hard	link) two files.

  m   Tells tar	not to restore the modification	times. The modification	time
      is the time of extraction.  This is always the case with symbolic
      links.

  n   [Tru64 UNIX]  Allows tar headers to be created with file names that
      cannot be	null-terminated	if they	are exactly the	maximum	length (as
      specified	in POSIX).  This option	is mutually exclusive with the o
      option (that is, new versus old).	 When specified, each of these
      options turns off	the other; neither option is turned on by default,
      however.

  o   The o option is provided for backward compatibility.  Specify this
      option if	the archive is to be restored on a system with an older	ver-
      sion of tar.  On output, tar normally places information specifying
      owner and	modes of directories in	the archive.  Former versions of tar,
      when encountering	this information will give an error message of the
      following	form:

      name: cannot create

      [Tru64 UNIX]  This option	suppresses the directory information. It also
      prevents archiving special files and FIFOs that earlier versions of tar
      would not	be able	to extract properly. (Although anyone can archive
      special files, who has superuser authority can extract them from the
      archives.)

      When o is	used for reading, it causes the	extracted file to take on the
      User and Group ID	(UID and GID) of the user running the program, rather
      than those of the	tape.  This is the default for the ordinary user.

      [Tru64 UNIX]  This option	is mutually exclusive with the n option	(that
      is, new vs.  old).  When specified, each of these	options	turns off the
      other; neither option is turned on by default, however.

  p   [Tru64 UNIX]  Restores files to their original modes, ignoring the
      present umask.  Set-user-ID and sticky information will also be
      restored if the user is superuser.

  P   [Tru64 UNIX]  Specifies the prefix that is to be stripped	off of the
      file names archived to or	extracted from tape.  (See also	the s
      option.)

  s   [Tru64 UNIX]  Tells tar to strip off any leading slashes from pathnames
      during extraction.  This is useful when restoring	a tape that was
      created on a system with a different file	system structure.  (See	also
      the P option.)

  R   [Tru64 UNIX]  The	named file immediately following this option contains
      a	list of	file names separated by	newlines.  This	list is	added to (c
      function key, r function key) or extracted from (x function key) the
      archive.	The -R option is incompatible with the -C option.

  S blocksb | feet[@density]
      [Tru64 UNIX]  Specifies the number of 512-byte blocks per	volume (first
      form), independent of the	tape blocking factor.  You can also specify
      the size of the tape in feet, and	optionally density, by using the
      second form.  Feet are assumed to	be 11 inches long to be	conservative.
      This option lets you deal	more easily with multivolume tape archives,
      where tar	must be	able to	determine how many blocks fit on each volume.

      [Tru64 UNIX]  Tape drives	vary in	density	capabilities.  The density
      argument is used in the amount of	data that tar can fit on a tape.

  v   Normally tar does	its work silently.  The	v (verbose) option makes tar
      print the	name of	each file it processes as specified by the function
      key.  With the t function	key, the verbose option	gives more informa-
      tion about the tape entries than just their names.

  V   [Tru64 UNIX]  Prevents any extended attributes from being	archived with
      associated files.	 This option is	particularly useful for	archiving
      files that are to	be restored with previous versions of tar and cpio.

  w   Causes tar to print the action to	be taken followed by the name of the
      file, and	then to	wait for the user's confirmation. If a word beginning
      with y, or the locale's definition of an affirmative response, is
      given, the action	is performed.  If any other input is given, the
      action is	not performed.

  z   [Tru64 UNIX]  Positions the tape after the EOF marker on extraction or
      listing.	The z option lets the user extract or list tapes that have
      multiple archives	on them	one after the other without error as a result
      of the tape not being positioned correctly for the next extraction or
      listing.

  n   [Tru64 UNIX]  Selects /dev/ntape/tapen (the variable n means 0-9)	as
      the tape drive on	which the tape is mounted.  The	default	is drive 0
      (/dev/ntape/tape0).

  e   [Tru64 UNIX]  Adds the following argument	to a list of exception
      strings that prevent files whose names match exactly from	being
      archived.	When used with the -C option, the list of exceptions becomes
      relative to each new directory.

  C   [Tru64 UNIX]  If a file name is preceded by -C, tar performs a chdir()
      to that file name.  This allows multiple directories not related by a
      close common parent to be	archived using short relative pathnames.  For
      example, to archive files	from /usr/include and from /etc, one might
      use the following	command	line:
	   tar c -C /usr/include . -C /etc .

      [Tru64 UNIX]  Therefore, if you do not specify an	absolute file name,
      the file name is considered relative to the previous -C directory.
      When you specify this option multiple times on the command line, make
      sure to specify subsequent -C directories	relative to the	preceding -C
      directories.

      [Tru64 UNIX]  If an error	occurs while trying to change to the
      requested	directory, subsequent file names on the	command	line that are
      not absolute (that is, have no leading / (slash))	are skipped until the
      next -C option is	specified.

  [Tru64 UNIX]	Only the -e and	-C options must	be preceded by a - (dash) and
  can be specified more	than once on a single command line or interspersed
  within the list of file names.  All other options must be specified
  together (with no separating spaces) before -e, -C, and the file list.  For
  all options that require arguments, the arguments must follow	the string of
  options and be ordered in the	same way as the	specified options.

  [Tru64 UNIX]	Previous restrictions on the tar command's ability to prop-
  erly handle blocked archives have been lifted.




DESCRIPTION

  The tar command is used to save and restore data from	traditional format
  tar archives.

  The actions of the tar command are controlled	by a string containing,	at
  most,	one function key and possibly one or more options.  Other arguments
  to tar are file or directory names specifying	which files to dump or
  restore.  In all cases, appearance of	a directory name refers	to the files
  and (recursively) subdirectories of that directory.

  The LC_MESSAGES variable determines the locale's equivalent of y or n	(for
  yes/no responses).

NOTES

  The tar command is marked as LEGACY in XCU Issue 5.

   1.  [Tru64 UNIX]  There is no way to	ask for	the nth	occurrence of a	file.

   2.  [Tru64 UNIX]  Tape errors are handled ungracefully.

   3.  [Tru64 UNIX]  The u function can	be slow.

   4.  [Tru64 UNIX]  The current limit on file name length is 256 bytes.  The
       current limit on	file links (hard or soft) is 100 bytes.

   5.  [Tru64 UNIX]  There is no way selectively to follow symbolic links.

   6.  [Tru64 UNIX]  When extracting tapes created with	the r or u functions,
       directory modification times might not be set correctly.

   7.  [Tru64 UNIX]  After encountering	tape write errors, tar queries the
       operator	about performing a rewrite.  If	the operator requests a
       rewrite,	a rewind is performed, followed	by an attempt to rewrite the
       data.  In the event the no-rewind device	is used, the user should
       always load a new tape to avoid the possibility of overwriting previ-
       ously written archives.

   8.  [Tru64 UNIX]  Socket files are ignored while archiving through thetar.

EXIT STATUS

  The following	exit values are	returned:

  0   Successful completion.

  >>0  An error occurred.

EXAMPLES

   1.  To create a tar archive to device /dev/ntape/tape0, enter:
	    tar	cvfb /dev/ntape/tape0 20 -e ./foo -C /usr/glenn	. \
	    -e ./bar -e	./logs/logfile -C /usr/gaston .

       The preceding command line specifies a blocking factor of 20.  The
       resulting archive contains all files and	directories in /usr/glenn
       except for file ./foo and all files and directories in /usr/gaston
       except for files	./foor,	./bar, and ./logs/logfile.

   2.  To create a tar archive as a disk file, enter:
	    tar	cvf /tmp/mybackup.tar -e $HOME/zeugma $HOME

       The preceding command line uses the f option to create a	tar archive
       named mybackup.tar in the /tmp directory.  The archive contains the
       user's home directory and its contents, including all subdirectories
       and files except	the zeugma subdirectory	and its	contents, which	are
       excluded	by the -e (exception) option.

ENVIRONMENT VARIABLES

  The following	environment variables affect the execution of tar:

  LANG
      Provides a default value for the internationalization variables that
      are unset	or null. If LANG is unset or null, the corresponding value
      from the default locale is used. If any of the internationalization
      variables	contain	an invalid setting, the	utility	behaves	as if none of
      the variables had	been defined.

  LC_ALL
      If set to	a non-empty string value, overrides the	values of all the
      other internationalization variables.

  LC_CTYPE
      Determines the locale for	the interpretation of sequences	of bytes of
      text data	as characters (for example, single-byte	as opposed to multi-
      byte characters in arguments).

  LC_MESSAGES
      Determines the locale for	the format and contents	of diagnostic mes-
      sages written to standard	error.

  LC_TIME
      Determines the format of date and	time strings output when listing the
      contents of an archive.

  NLSPATH
      Determines the location of message catalogs for the processing of
      LC_MESSAGES.

  TZ  Determines the time zone used with date and time strings.

FILES

  /dev/ntape/tapen
      Device name used with the	n option.

  /tmp/tar*
      Temporary	file used with the u function.

SEE ALSO

  Commands:  cpio(1), pax(1)

  Functions:  chdir(2),	umask(2)

  Files:  tar(4)

  Standards:  standards(5)