diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/lib/libtarfile.tex | 200 |
1 files changed, 107 insertions, 93 deletions
diff --git a/Doc/lib/libtarfile.tex b/Doc/lib/libtarfile.tex index 10ecc77..fec2737 100644 --- a/Doc/lib/libtarfile.tex +++ b/Doc/lib/libtarfile.tex @@ -12,7 +12,7 @@ Some facts and figures: \begin{itemize} \item reads and writes \module{gzip} and \module{bzip2} compressed archives. -\item creates POSIX 1003.1-1990 compliant or GNU tar compatible archives. +\item creates \POSIX{} 1003.1-1990 compliant or GNU tar compatible archives. \item reads GNU tar extensions \emph{longname}, \emph{longlink} and \emph{sparse}. \item stores pathnames of unlimited length using GNU tar extensions. @@ -52,19 +52,19 @@ Some facts and figures: a file object opened for \var{name}. For special purposes, there is a second format for \var{mode}: - \code{'filemode|[compression]'}. \code{open} will return a \class{TarFile} - object that processes its data as a stream of blocks. No random - seeking will be done on the file. If given, \var{fileobj} may be any - object that has a \code{read()} resp. \code{write()} method. - \var{bufsize} specifies the blocksize and defaults to \code{20 * 512} - bytes. Use this variant in combination with e.g. \code{sys.stdin}, a socket - file object or a tape device. - However, such a \class{TarFile} object is limited in that it does not allow - to be accessed randomly, see \citetitle{Examples} (section - \ref{tar-examples}). - The currently possible modes: - - \begin{tableii}{c|l}{code}{mode}{action} + \code{'filemode|[compression]'}. \function{open()} will return a + \class{TarFile} object that processes its data as a stream of + blocks. No random seeking will be done on the file. If given, + \var{fileobj} may be any object that has a \method{read()} or + \method{write()} method (depending on the \var{mode}). + \var{bufsize} specifies the blocksize and defaults to \code{20 * + 512} bytes. Use this variant in combination with + e.g. \code{sys.stdin}, a socket file object or a tape device. + However, such a \class{TarFile} object is limited in that it does + not allow to be accessed randomly, see ``Examples'' + (section~\ref{tar-examples}). The currently possible modes: + + \begin{tableii}{c|l}{code}{Mode}{Action} \lineii{'r|'}{Open a \emph{stream} of uncompressed tar blocks for reading.} \lineii{'r|gz'}{Open a gzip compressed \emph{stream} for reading.} \lineii{'r|bz2'}{Open a bzip2 compressed \emph{stream} for reading.} @@ -77,26 +77,25 @@ Some facts and figures: \begin{classdesc*}{TarFile} Class for reading and writing tar archives. Do not use this class directly, better use \function{open()} instead. - See \citetitle{TarFile Objects} (section \ref{tarfile-objects}). + See ``TarFile Objects'' (section~\ref{tarfile-objects}). \end{classdesc*} \begin{funcdesc}{is_tarfile}{name} - Return \code{True} if \var{name} is a tar archive file, that the - \module{tarfile} module can read. + Return \constant{True} if \var{name} is a tar archive file, that + the \module{tarfile} module can read. \end{funcdesc} \begin{classdesc}{TarFileCompat}{filename\optional{, mode\optional{, - compression}}} - - Class for limited access to tar archives with a \code{zipfile}-like - interface. Please consult the documentation of \code{zipfile} for more - details. - \code{compression} must be one of the following constants: + compression}}} + Class for limited access to tar archives with a + \refmodule{zipfile}-like interface. Please consult the + documentation of the \refmodule{zipfile} module for more details. + \var{compression} must be one of the following constants: \begin{datadesc}{TAR_PLAIN} Constant for an uncompressed tar archive. \end{datadesc} \begin{datadesc}{TAR_GZIPPED} - Constant for a \code{gzip} compressed tar archive. + Constant for a \refmodule{gzip} compressed tar archive. \end{datadesc} \end{classdesc} @@ -125,7 +124,7 @@ Some facts and figures: \end{excdesc} \begin{seealso} - \seemodule{zipfile}{Documentation of the \code{zipfile} + \seemodule{zipfile}{Documentation of the \refmodule{zipfile} standard module.} \seetitle[http://www.gnu.org/manual/tar/html_chapter/tar_8.html\#SEC118] @@ -162,7 +161,7 @@ tar archive several times. Each archive member is represented by a \begin{methoddesc}{open}{...} Alternative constructor. The \function{open()} function on module level is - actually a shortcut to this classmethod. See section \ref{module-tarfile} + actually a shortcut to this classmethod. See section~\ref{module-tarfile} for details. \end{methoddesc} @@ -187,8 +186,8 @@ tar archive several times. Each archive member is represented by a \begin{methoddesc}{list}{verbose=True} Print a table of contents to \code{sys.stdout}. If \var{verbose} is - \code{False}, only the names of the members are printed. If it is - \code{True}, an \code{"ls -l"}-like output is produced. + \constant{False}, only the names of the members are printed. If it is + \constant{True}, output similar to that of \program{ls -l} is produced. \end{methoddesc} \begin{methoddesc}{next}{} @@ -219,17 +218,18 @@ tar archive several times. Each archive member is represented by a \end{notice} \end{methoddesc} -\begin{methoddesc}{add}{name\optional{, arcname\optional{, recursive=True}}} +\begin{methoddesc}{add}{name\optional{, arcname\optional{, recursive}}} Add the file \var{name} to the archive. \var{name} may be any type of file (directory, fifo, symbolic link, etc.). If given, \var{arcname} specifies an alternative name for the file in the archive. Directories are added recursively by default. - This can be avoided by setting \var{recursive} to \code{False}. + This can be avoided by setting \var{recursive} to \constant{False}; + the default is \constant{True}. \end{methoddesc} \begin{methoddesc}{addfile}{tarinfo\optional{, fileobj}} Add the \class{TarInfo} object \var{tarinfo} to the archive. - If \var{fileobj} is given, \code{tarinfo.size} bytes are read + If \var{fileobj} is given, \code{\var{tarinfo}.size} bytes are read from it and added to the archive. You can create \class{TarInfo} objects using \method{gettarinfo()}. \begin{notice} @@ -238,57 +238,57 @@ tar archive several times. Each archive member is represented by a \end{notice} \end{methoddesc} -\begin{methoddesc}{gettarinfo}{\optional{name\optional{, arcname - \optional{, fileobj}}}} - Create a \class{TarInfo} object for either the file \var{name} or the - file object \var{fileobj} (using \code{os.fstat()} on its file descriptor). - You can modify some of the \class{TarInfo}'s attributes before you add it - using \method{addfile()}. - If given, \var{arcname} specifies an alternative name for the file in the +\begin{methoddesc}{gettarinfo}{\optional{name\optional{, + arcname\optional{, fileobj}}}} + Create a \class{TarInfo} object for either the file \var{name} or + the file object \var{fileobj} (using \function{os.fstat()} on its + file descriptor). You can modify some of the \class{TarInfo}'s + attributes before you add it using \method{addfile()}. If given, + \var{arcname} specifies an alternative name for the file in the archive. \end{methoddesc} \begin{methoddesc}{close}{} - Close the \class{TarFile}. In write-mode, two finishing zero blocks are - appended to the archive. + Close the \class{TarFile}. In write mode, two finishing zero + blocks are appended to the archive. \end{methoddesc} -\begin{memberdesc}{posix=True} - If \code{True}, create a POSIX 1003.1-1990 compliant archive. GNU - extensions are not used, because they are not part of the POSIX standard. - This limits the length of filenames to at most 256 and linknames to 100 - characters. A \exception{ValueError} is raised, if a pathname exceeds this - limit. - If \code{False}, create a GNU tar compatible archive. It will not be POSIX - compliant, but can store pathnames of unlimited length. +\begin{memberdesc}{posix} + If true, create a \POSIX{} 1003.1-1990 compliant archive. GNU + extensions are not used, because they are not part of the \POSIX{} + standard. This limits the length of filenames to at most 256 and + link names to 100 characters. A \exception{ValueError} is raised + if a pathname exceeds this limit. If false, create a GNU tar + compatible archive. It will not be \POSIX{} compliant, but can + store pathnames of unlimited length. \end{memberdesc} -\begin{memberdesc}{dereference=False} - If \code{False}, add symbolic and hard links to archive. If \code{True}, - add the content of the target files to the archive. This has no effect on - systems that do not support links. +\begin{memberdesc}{dereference} + If false, add symbolic and hard links to archive. If true, add the + content of the target files to the archive. This has no effect on + systems that do not support symbolic links. \end{memberdesc} -\begin{memberdesc}{ignore_zeros=False} - If \code{False}, treat an empty block as the end of the archive. If - \code{True}, skip empty (and invalid) blocks and try to get as many - members as possible. This is only useful for concatenated or damaged +\begin{memberdesc}{ignore_zeros} + If false, treat an empty block as the end of the archive. If true, + skip empty (and invalid) blocks and try to get as many members as + possible. This is only useful for concatenated or damaged archives. \end{memberdesc} \begin{memberdesc}{debug=0} - To be set from \code{0}(no debug messages) up to \code{3}(all debug - messages). The messages are written to \code{sys.stdout}. + To be set from \code{0} (no debug messages; the default) up to + \code{3} (all debug messages). The messages are written to + \code{sys.stdout}. \end{memberdesc} -\begin{memberdesc}{errorlevel=0} - If \code{0}, all errors are ignored when using \method{extract()}. - Nevertheless, they appear as error messages in the debug output, when - debugging is enabled. - If \code{1}, all \emph{fatal} errors are raised as \exception{OSError} - or \exception{IOError} exceptions. - If \code{2}, all \emph{non-fatal} errors are raised as \exception{TarError} - exceptions as well. +\begin{memberdesc}{errorlevel} + If \code{0} (the default), all errors are ignored when using + \method{extract()}. Nevertheless, they appear as error messages + in the debug output, when debugging is enabled. If \code{1}, all + \emph{fatal} errors are raised as \exception{OSError} or + \exception{IOError} exceptions. If \code{2}, all \emph{non-fatal} + errors are raised as \exception{TarError} exceptions as well. \end{memberdesc} %----------------- @@ -297,13 +297,14 @@ tar archive several times. Each archive member is represented by a \subsection{TarInfo Objects \label{tarinfo-objects}} -A \class{TarInfo} object represents one member in a \class{TarFile}. Aside from -storing all required attributes of a file (like file type, size, time, -permissions, owner etc.), it provides some useful methods to determine its -type. It does \emph{not} contain the file's data itself. +A \class{TarInfo} object represents one member in a +\class{TarFile}. Aside from storing all required attributes of a file +(like file type, size, time, permissions, owner etc.), it provides +some useful methods to determine its type. It does \emph{not} contain +the file's data itself. -\class{TarInfo} objects are returned by \code{TarFile}'s methods -\code{getmember()}, \code{getmembers()} and \code{gettarinfo()}. +\class{TarInfo} objects are returned by \class{TarFile}'s methods +\method{getmember()}, \method{getmembers()} and \method{gettarinfo()}. \begin{classdesc}{TarInfo}{\optional{name}} Create a \class{TarInfo} object. @@ -318,6 +319,7 @@ type. It does \emph{not} contain the file's data itself. \end{methoddesc} A \code{TarInfo} object has the following public data attributes: + \begin{memberdesc}{name} Name of the archive member. \end{memberdesc} @@ -335,30 +337,42 @@ A \code{TarInfo} object has the following public data attributes: \end{memberdesc} \begin{memberdesc}{type} - File type. - \var{type} is usually one of these constants: - \code{REGTYPE, AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, CONTTYPE, - CHRTYPE, BLKTYPE, GNUTYPE_SPARSE}. - To determine the type of a \class{TarInfo} object more conveniently, use - the \code{is_*()} methods below. + File type. \var{type} is usually one of these constants: + \constant{REGTYPE}, \constant{AREGTYPE}, \constant{LNKTYPE}, + \constant{SYMTYPE}, \constant{DIRTYPE}, \constant{FIFOTYPE}, + \constant{CONTTYPE}, \constant{CHRTYPE}, \constant{BLKTYPE}, + \constant{GNUTYPE_SPARSE}. To determine the type of a + \class{TarInfo} object more conveniently, use the \code{is_*()} + methods below. \end{memberdesc} \begin{memberdesc}{linkname} - Name of the target file name, which is only present in \class{TarInfo} - objects of type LNKTYPE and SYMTYPE. + Name of the target file name, which is only present in + \class{TarInfo} objects of type \constant{LNKTYPE} and + \constant{SYMTYPE}. \end{memberdesc} -\begin{memberdesc}{uid, gid} - User and group ID of who originally stored this member. +\begin{memberdesc}{uid} + User ID of the user who originally stored this member. \end{memberdesc} -\begin{memberdesc}{uname, gname} - User and group name. +\begin{memberdesc}{gid} + Group ID of the user who originally stored this member. +\end{memberdesc} + +\begin{memberdesc}{uname} + User name. +\end{memberdesc} + +\begin{memberdesc}{gname} + Group name. \end{memberdesc} A \class{TarInfo} object also provides some convenient query methods: + \begin{methoddesc}{isfile}{} - Return \code{True} if the \class{Tarinfo} object is a regular file. + Return \constant{True} if the \class{Tarinfo} object is a regular + file. \end{methoddesc} \begin{methoddesc}{isreg}{} @@ -366,31 +380,32 @@ A \class{TarInfo} object also provides some convenient query methods: \end{methoddesc} \begin{methoddesc}{isdir}{} - Return \code{True} if it is a directory. + Return \constant{True} if it is a directory. \end{methoddesc} \begin{methoddesc}{issym}{} - Return \code{True} if it is a symbolic link. + Return \constant{True} if it is a symbolic link. \end{methoddesc} \begin{methoddesc}{islnk}{} - Return \code{True} if it is a hard link. + Return \constant{True} if it is a hard link. \end{methoddesc} \begin{methoddesc}{ischr}{} - Return \code{True} if it is a character device. + Return \constant{True} if it is a character device. \end{methoddesc} \begin{methoddesc}{isblk}{} - Return \code{True} if it is a block device. + Return \constant{True} if it is a block device. \end{methoddesc} \begin{methoddesc}{isfifo}{} - Return \code{True} if it is a FIFO. + Return \constant{True} if it is a FIFO. \end{methoddesc} \begin{methoddesc}{isdev}{} - Return \code{True} if it is one of character device, block device or FIFO. + Return \constant{True} if it is one of character device, block + device or FIFO. \end{methoddesc} %------------------------ @@ -447,4 +462,3 @@ for tarinfo in tar: tar.extract(tarinfo) tar.close() \end{verbatim} - |