chase/release-0.5.2/chase.1

.TH CHASE 1 "2000-01-02" "Chase 0.5" "Chase user's manual"
\" Copyright (C) 1998-2000 Antti-Juhani Kaijanaho  <gaia@iki.fi>
\" 
\" Permission is granted to make and distribute verbatim copies of
\" this manual provided the copyright notice and this permission notice
\" are preserved on all copies.
\" 
\" Permission is granted to copy and distribute modified versions of this
\" manual under the conditions for verbatim copying, provided that the
\" entire resulting derived work is distributed under the terms of a
\" permission notice identical to this one.
\" 
\" Permission is granted to copy and distribute translations of this
\" manual into another language, under the above conditions for modified
\" versions, except that this permission notice may be included in
\" translations approved by the authors of this manual instead of in
\" the original English.
\" 
.SH NAME
chase \- chase symbolic links
.SH SYNOPSIS
.B chase
[
.B --verbose 
|
.B --from-file
| 
.B -f
|
.B --null
|
.B -0
|
.B --loop-warn-threshold 
COUNT |
.B -w
COUNT |
.B --loop-fail-threshold
COUNT |
.B -l
COUNT |
.B --disable-loop-detection
|
.B -D
]
.IR "" [ file ...]
.sp
.B chase -v
|
.B --version
.sp
.B chase -h
|
.B --help
.SH DESCRIPTION
.B Chase
is a small utility that tracks down the name of the actual file that
is truly accessed, when one hits a symbolic link.  It chases the link,
so to speak.
.PP
In normal operation, you give
.B chase
a name of an existing file.  The program will then show you (or, more
accurately, print to the standard output stream) the name of the real
file that the original file referred to.  It does not matter, if you give
the program the name of a regular file;
.B  chase
will just give you the same name back.  You can give the utility the option
.BR --verbose ,
in order to have it be more verbose in its operation.  You can also
give the program a list of files from which it will read the file
names to be chased (see the option
.BR --from-file ).
.PP
I'll give you a good example of a case where
.B chase
is useful.  In a Debian GNU/Linux system, software installation is
handled by the program
.BR dpkg (8).
There is a way to query
.BR dpkg (8),
which package a file belongs to.  Unfortunately, this does not not
grok all symlinks.  This is a problem, since the Debian system uses
symbolic links extensively for handling several flavours of a program
(say, XEmacs and GNU Emacs and the versions 19 and 20 of both).  Now
with
.BR chase,
one can determine the real file easily and then using this result
as an argument to
.BR dpkg (8).
Observe:
.nf
.sp
ajk@ugh:~$ dpkg -S `which xemacs20`
dpkg: /usr/bin/xemacs20 not found.
ajk@ugh:~$ dpkg -S `which xemacs20 | xargs chase`
xemacs20-nomule: /usr/bin/xemacs-20.4-nomule
ajk@ugh:~$ 
.fi
.PP
When given multiple file names as arguments,
.B chase
will chase every one of them in order.
.SH OPTIONS
The following options are recognized by
.BR chase :
.IP --verbose
Chat about what is being done.
.IP "-f, --from-file"
Treat the file names on the command line as sources for names to be
chased.  If this option is present,
.B chase
will read in each of the files given on the command line (both a sole
dash "\-" and the absence of file names will be taken as meaning the
standard input stream).  Each line in the files is taken as a verbatim
file name that will be chased like it had been given on the command
line of a run without this option.  There is no means for quoting the
newline character; therefore only file names that do not contain
newlines can be specified via the files.  This restriction is lifted
by the -0 option, though.  However, literal spaces are preserved and
are not interpreted as special.
.IP "-0, --null"
This option implies the option -f, which reads file names from a file.
The -0 option modifies the behviour -f so that instead of treating
lines in the file as file names, the file names are expected to be
separated by null characters.  This allows for specifying file names
with newlines in them with -f.
.IP "-w WCOUNT, --loop-warn-threshold=WCOUNT"
.IP "-l LCOUNT, --loop-fail-threshold=LCOUNT"
Set the threshold for warning about a possible symlink loop (WCOUNT)
and for failing because of one (LCOUNT).  There are default values,
which you can find out by invoking
.B chase
with the argument --help.  Using zero as WCOUNT or LCOUNT disables the
check.
.IP "-D, --disable-loop-detection"
Normally
.B chase
keeps a record of all symlinks it has visited when chasing the current
file.  It uses this record to reliably detect symlink loops.  However,
checking the record slows the process a little (more for long chains
of symlinks) and the record requires a small amount of memory (more
for long chains of symlinks), so it may be desirable in some cases to
inhibit this check.  This option disables this loop detection and the
associated recording of visited symlinks.  When this option is in
effect (assuming no bugs in the related code)
.B chase
runs in constant space and linear time relative to the length of the
symlink chains encountered.
.IP "-h, --help"
Output a usage summary and exit successfully.
.IP "-v, --version"
Show version information and exit successfully.
.SH DIAGNOSTICS
The exit status is 0 if and only if all files given in the command
lines exist and none of them are dangling symlinks.
.PP
The following messages are emitted by
.B chase
when it suspects or detects a symlink loop:
.IP "quite many symlink hops, hope we're not looping..."
This means that the chain of symlinks is longer than a given threshold.
This may mean that the chain is infinite (and thus contains a loop
somewhere).  The threshold can be specificed by using the
--loop-warn-threshold command line option.
.IP "too many symlink hops, giving up..."
This means that the chain of symlinks is longer than a given threshold.
This usually means that the chain is infinite (and thus contains a
loop somewhere).  The threshold can be specificed by using the
--loop-fail-threshold command line option.  If you see this message, it
means that
.B chase
has given up on that file.
.IP "symlink loop detected, giving up..."
The symlink chain is looping and therefore there is no result for the
chase.  
.B Chase
has given up on that file.
.PP
Additionally, 
.B Chase
emits several error messages under problemous conditions.  They
all come from the system libraries, so the program has no control over
the actual wording of the messages.  They all follow the format
"program name: file name: error message", where file name is the name
of the offending file or directory.
.SH BUGS
.B Chase
may have bugs. If you find them, please report them to <gaia@iki.fi>.
.SH AUTHOR
.B Chase
has been written by Antti-Juhani Kaijanaho <gaia@iki.fi>.
.SH "SEE ALSO"
.BR find (1),
.BR ln (1),
.BR namei (1),
.BR readlink (1),
.BR readlink (2),
.BR symlinks (1)
1	rotty	2	.TH CHASE 1 "2000-01-02" "Chase 0.5" "Chase user's manual"
2			\" Copyright (C) 1998-2000 Antti-Juhani Kaijanaho <gaia@iki.fi>
3			\"
4			\" Permission is granted to make and distribute verbatim copies of
5			\" this manual provided the copyright notice and this permission notice
6			\" are preserved on all copies.
7			\"
8			\" Permission is granted to copy and distribute modified versions of this
9			\" manual under the conditions for verbatim copying, provided that the
10			\" entire resulting derived work is distributed under the terms of a
11			\" permission notice identical to this one.
12			\"
13			\" Permission is granted to copy and distribute translations of this
14			\" manual into another language, under the above conditions for modified
15			\" versions, except that this permission notice may be included in
16			\" translations approved by the authors of this manual instead of in
17			\" the original English.
18			\"
19			.SH NAME
20			chase \- chase symbolic links
21			.SH SYNOPSIS
22			.B chase
23			[
24			.B --verbose
25			\|
26			.B --from-file
27			\|
28			.B -f
29			\|
30			.B --null
31			\|
32			.B -0
33			\|
34	rotty	11	.B --loop-warn-threshold
35	rotty	2	COUNT \|
36			.B -w
37			COUNT \|
38	rotty	11	.B --loop-fail-threshold
39	rotty	2	COUNT \|
40			.B -l
41			COUNT \|
42			.B --disable-loop-detection
43			\|
44			.B -D
45			]
46			.IR "" [ file ...]
47			.sp
48			.B chase -v
49			\|
50			.B --version
51			.sp
52			.B chase -h
53			\|
54			.B --help
55			.SH DESCRIPTION
56			.B Chase
57			is a small utility that tracks down the name of the actual file that
58			is truly accessed, when one hits a symbolic link. It chases the link,
59			so to speak.
60			.PP
61			In normal operation, you give
62			.B chase
63			a name of an existing file. The program will then show you (or, more
64			accurately, print to the standard output stream) the name of the real
65			file that the original file referred to. It does not matter, if you give
66			the program the name of a regular file;
67			.B chase
68			will just give you the same name back. You can give the utility the option
69			.BR --verbose ,
70			in order to have it be more verbose in its operation. You can also
71			give the program a list of files from which it will read the file
72			names to be chased (see the option
73			.BR --from-file ).
74			.PP
75			I'll give you a good example of a case where
76			.B chase
77			is useful. In a Debian GNU/Linux system, software installation is
78			handled by the program
79			.BR dpkg (8).
80			There is a way to query
81			.BR dpkg (8),
82			which package a file belongs to. Unfortunately, this does not not
83			grok all symlinks. This is a problem, since the Debian system uses
84			symbolic links extensively for handling several flavours of a program
85			(say, XEmacs and GNU Emacs and the versions 19 and 20 of both). Now
86			with
87			.BR chase,
88			one can determine the real file easily and then using this result
89			as an argument to
90			.BR dpkg (8).
91			Observe:
92			.nf
93			.sp
94			ajk@ugh:~$ dpkg -S `which xemacs20`
95			dpkg: /usr/bin/xemacs20 not found.
96			ajk@ugh:~$ dpkg -S `which xemacs20 \| xargs chase`
97			xemacs20-nomule: /usr/bin/xemacs-20.4-nomule
98			ajk@ugh:~$
99			.fi
100			.PP
101			When given multiple file names as arguments,
102			.B chase
103			will chase every one of them in order.
104			.SH OPTIONS
105			The following options are recognized by
106			.BR chase :
107			.IP --verbose
108			Chat about what is being done.
109			.IP "-f, --from-file"
110			Treat the file names on the command line as sources for names to be
111			chased. If this option is present,
112			.B chase
113			will read in each of the files given on the command line (both a sole
114			dash "\-" and the absence of file names will be taken as meaning the
115			standard input stream). Each line in the files is taken as a verbatim
116			file name that will be chased like it had been given on the command
117			line of a run without this option. There is no means for quoting the
118			newline character; therefore only file names that do not contain
119			newlines can be specified via the files. This restriction is lifted
120			by the -0 option, though. However, literal spaces are preserved and
121			are not interpreted as special.
122			.IP "-0, --null"
123			This option implies the option -f, which reads file names from a file.
124			The -0 option modifies the behviour -f so that instead of treating
125			lines in the file as file names, the file names are expected to be
126			separated by null characters. This allows for specifying file names
127			with newlines in them with -f.
128	rotty	11	.IP "-w WCOUNT, --loop-warn-threshold=WCOUNT"
129			.IP "-l LCOUNT, --loop-fail-threshold=LCOUNT"
130			Set the threshold for warning about a possible symlink loop (WCOUNT)
131	rotty	2	and for failing because of one (LCOUNT). There are default values,
132			which you can find out by invoking
133			.B chase
134			with the argument --help. Using zero as WCOUNT or LCOUNT disables the
135			check.
136			.IP "-D, --disable-loop-detection"
137			Normally
138			.B chase
139			keeps a record of all symlinks it has visited when chasing the current
140			file. It uses this record to reliably detect symlink loops. However,
141			checking the record slows the process a little (more for long chains
142			of symlinks) and the record requires a small amount of memory (more
143			for long chains of symlinks), so it may be desirable in some cases to
144			inhibit this check. This option disables this loop detection and the
145			associated recording of visited symlinks. When this option is in
146			effect (assuming no bugs in the related code)
147			.B chase
148			runs in constant space and linear time relative to the length of the
149			symlink chains encountered.
150			.IP "-h, --help"
151			Output a usage summary and exit successfully.
152			.IP "-v, --version"
153			Show version information and exit successfully.
154			.SH DIAGNOSTICS
155			The exit status is 0 if and only if all files given in the command
156			lines exist and none of them are dangling symlinks.
157			.PP
158			The following messages are emitted by
159			.B chase
160			when it suspects or detects a symlink loop:
161			.IP "quite many symlink hops, hope we're not looping..."
162	rotty	11	This means that the chain of symlinks is longer than a given threshold.
163	rotty	2	This may mean that the chain is infinite (and thus contains a loop
164	rotty	11	somewhere). The threshold can be specificed by using the
165			--loop-warn-threshold command line option.
166	rotty	2	.IP "too many symlink hops, giving up..."
167	rotty	11	This means that the chain of symlinks is longer than a given threshold.
168	rotty	2	This usually means that the chain is infinite (and thus contains a
169	rotty	11	loop somewhere). The threshold can be specificed by using the
170			--loop-fail-threshold command line option. If you see this message, it
171	rotty	2	means that
172			.B chase
173			has given up on that file.
174			.IP "symlink loop detected, giving up..."
175			The symlink chain is looping and therefore there is no result for the
176			chase.
177			.B Chase
178			has given up on that file.
179			.PP
180			Additionally,
181			.B Chase
182			emits several error messages under problemous conditions. They
183			all come from the system libraries, so the program has no control over
184			the actual wording of the messages. They all follow the format
185			"program name: file name: error message", where file name is the name
186			of the offending file or directory.
187			.SH BUGS
188			.B Chase
189			may have bugs. If you find them, please report them to <gaia@iki.fi>.
190			.SH AUTHOR
191			.B Chase
192			has been written by Antti-Juhani Kaijanaho <gaia@iki.fi>.
193			.SH "SEE ALSO"
194			.BR find (1),
195			.BR ln (1),
196			.BR namei (1),
197			.BR readlink (1),
198			.BR readlink (2),
199			.BR symlinks (1)