%++++++++
%.IDENTIFICATION fcat.tex
%.PURPOSE        Man page of fcat, can be edited in LaTeX
%.AUTHOR         Francois Ochsenbein
%.VERSION   1.0	 17-Feb-2000
%----------

\def\pgm{{\bf fcat}\ }
\def\file{{\em file}}
\def\fih{{\em $\ast$.fih }}

\begin{manpage} {1}{fcat}{Print the contents of a file, even when compressed}
	{Nov-2007}{Compressions}
\syntax{ \pgm [{\bf--f1hv}]
	[{\bf--b {\em blocksize}}]
	[{\bf--i {\em skip\_records}}]
	[{\bf--s {\em max\_records}}]
	[{\em input\_file...}] }

\mansec{ Description }
The \pgm command can be used in place of {\bf cat} (1) to print the
file contents to the standard output. \pgm takes care of uncompressing
the file when compressed, or to concatenate the components of large files
when necessary.

\pgm prints the {\em input\_file}'s  specified as argument(s);
when the file specified is not existing, \pgm looks for files with
the following suffixes:

\begin{itemize}
\item	{ } {\bf.gz} {\em(gnu zip)}, and applies the unzip
	(1) utility
\item	{\bf.Z} {\em(Unix Compress)}, and applies the uncompress
	(1) utility
\item	{\bf.bz2} {\em(bzip2)}, and applies the bunzip2 (1) utility
\item	{\bf.fz} {\em(fpack, FITS tile compressing)}, and applies 
        the funpack utility (http://heasarc.gsfc.nasa.gov/fitsio/fpack/)
\item	{\bf.$n$} {\em(numeric suffix of 1 to 3 digits)}
	part of la larger file. The numeric suffix of the first
	file can be  {\tt.0}, {\tt.00} or {\tt.000}.
	Note that the numeric suffix can itself be suffixed by a
	{\bf.Z} or {\bf.gz} extension.
\end{itemize}

\mansec{Options}
Without any option, \pgm writes to its standard output the
file(s) in sequence, after application of the decompression if necessary.

%Usage: fcat -[mf1] [-s maxbytes] [file...]
%   -f: Just test if the file exists and can be read
%   -1: List all the files making up the catalog
%   -m: Add a message before starting each file
%   -v: verbose option
%   -s: stop after maxbytes

\option{--f}
	only tests for the existence of the file(s) specifed as
	argument(s), and returns the appropriate status.
	In order to be is considered as ``existant'',
	a file must be readable.

\option{--1}
	provides a list of the file(s) corresponding to the argument(s).
	The result is the actual file name, i.e. {\em file}{\tt.gz}
	if the file exists as a gzipped file, or the list of all files
	in case of numeric suffixes.


\option{--h}
	prints a header for each of the argument files.

\option{--v}
	is a verbose option (lists all the files examined)

\option{--version}
	prints out the version number and exit

\option{--b {\em blocksize}}
	indicates to issue full blocks of a given size.
	The size may be followed by a
	{\bf b} suffix to express sizes in blocks (512bytes),
	or by {\bf k} for Kbytes (1024bytes),
	or by {\bf f} for FITS blocks (2880bytes),
	or by {\bf m} for Mbytes ($1024^2$bytes).
	\\ \underline{{\bf Note}}: This argument may also be written
	{\tt bs=}{\em nn..} ({\em \`a la} {\bf dd})

\option{--i {\em ignore\_records}}
	asks to ignore a specified number of records.
	%The number may be follwed by a suffix, like the {\bf--b} option.
	\\ \underline{{\bf Note}}: This argument may also be written
	{\tt skip=}{\em nn..} ({\em \`a la} {\bf dd})

\option{--s {\em max\_records}}
	asks to stop after a given number of records.
	%The number may be follwed by a suffix, like the {\bf--b} option.
	\\ \underline{{\bf Note}}: This argument may also be written
	{\tt count=}{\em nn..} ({\em \`a la} {\bf dd})

\mansec{Condition of Usage}
\pgm requires an access to the compressing programs:
{\bf compress}(1), {\bf gzip}(1),
and {\bf bunzip2}(1) utilities.

\pgm does not require an access to any shell, and can therefore be used
in {\bf chroot}'ed programs like {\bf ftpd}(8)

\mansec{Returned Status}
The \pgm command returns 0 in case of success,
and non-zero if one of the files does not exist or cannot be opened
for input.

\mansec{Examples}
	The large file {\tt tyc2.dat} was split and gzipped as the 20 files
	{\tt tyc2.dat.00.gz}, {\tt tyc2.dat.01.gz} $\cdots$
	{\tt tyc2.dat.19.gz}.

\begin{itemize}
\item	{\tt fcat -1 tyc2.dat} \quad
	lists on the standard output the 20 files names, one per line

\item	{\tt fcat tyc2.dat} \quad
	lists on the standard output the 2.5 million lines if the catalog...
\end{itemize}

\seealso{cat(1)  dd(1)   compress(1)   gzip(1)  bunzip2(1)  ftpd(8) }
\end{manpage}
