use getchar() for queryuser function; lots of minor lint

[unix-history] / usr / src / lib / libc / gen / fts.3

.\" Copyright (c) 1989 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"	@(#)fts.3	5.6 (Berkeley) %G%
.\"
.TH FTS 3 ""
.UC 7
.SH NAME
fts \- traverse a file hierarchy
.SH SYNOPSIS
.nf
.ft B
#include <sys/types.h>
#include <sys/stat.h>
#include <fts.h>

FTS *
ftsopen(path_argv, options, compar)
char *path_argv[];
int options, (*compar)();

FTSENT *
ftsread(ftsp);
FTS *ftsp;

FTSENT *
ftschildren(ftsp)
FTS *ftsp;

ftsset(ftsp, f, options)
FTS *ftsp;
FTSENT *f;
int options;

ftsclose(ftsp)
FTS *ftsp;
.ft R
.fi
.SH DESCRIPTION
The
.IR fts (3)
utilities are provided for traversing UNIX file hierarchies.
Two structures are defined (and typedef'd) in the include file <\fIfts.h\fP>.
The first is FTS, the structure that defines the file hierarchy stream.
The second is FTSENT, the structure that defines a file in the file
hierarchy.
.PP
The
.I ftsopen
routine takes a pointer to an array of character pointers (``argv'')
naming the file hierarchies to be traversed.
The array must be terminated by a pointer to a NULL string.
.PP
The 
.I options
specified are formed by
.IR or 'ing
one or more of the following values:
.TP
FTS_LOGICAL
This option causes 
.I ftsread
to use the function
.IR stat (2),
by default, to determine the status of each file.
If this option is set, the only symbolic links returned to the application
are those referencing non-existent files.
Either FTS_LOGICAL or FTS_PHYSICAL
.B must
be provided to the 
.I ftsopen
routine.
.TP
FTS_NOCHDIR
As a performance optimization,
.I ftsread
changes directories as it descends the hierarchy.
This has the side-effect that applications cannot rely on being
in any particular directory.
The FTS_NOCHDIR option turns off this optimization.
Note that applications should not change the current directory
(even if FTS_NOCHDIR is specified) unless absolute pathnames were
provided as arguments to
.IR ftsopen .
.TP
FTS_NOSTAT
By default,
.I ftsread
and
.I ftschildren
provide file characteristic information (the
.I statb
field) for each file they return.
This option relaxes that requirement; the contents of the
.I statb
field may be undefined, and the
.I info
field may be set to FTS_NS.
.TP
FTS_PHYSICAL
This option causes 
.I ftsread
to use the function
.IR lstat (2),
by default, to determine the status of each file.
If this option is set, all symbolic links are returned to the application
program.
Either FTS_LOGICAL or FTS_PHYSICAL
.B must
be provided to the 
.I ftsopen
routine.
.TP
FTS_SEEDOT
This option causes the routine
.I ftsread
to return structures for the directory entries ``.'' and ``..''.
By default they are ignored unless specified as an argument to
.IR ftsopen .
.TP
FTS_XDEV
This option keeps
.I fts
from descending into directories that have a different device number
than the file the descent began from.
.PP
The argument
.I compar
specifies a user-defined routine which is used to order the traversal
of directories.
.I Compar
takes two pointers to pointers to FTSENT structures as arguments and
should return a negative value, zero, or a positive value to indicate
if the file referenced by its first argument comes before, in any order
with respect to, or after, the file referenced by its second argument.
.PP
The
.I fts_accpath
and
.I fts_path
fields of the FTSENT structures may not be used in this comparison.
If the option
.I FTS_NOSTAT
is specified, the
.I fts_stab
field may not be used as well.
If the
.I compar
argument is NULL the directory traversal order is unspecified except
for the root paths which are traversed in the order listed in
.IR path_argv .
.PP
The
.I ftsclose
routine closes a file hierarchy stream and changes the current
directory to the directory
.I ftsopen
was called from.
.I Ftsclose
returns 0 on success, and -1 if an error occurs.
.PP
Each call to the
.I ftsread 
routine returns a pointer to an FTSENT structure describing a file in
the hierarchy.
Directories (that are readable, searchable and do not cause cycles)
are visited at least twice, before any of their descendants have been
visited (pre-order) and after all their descendants have been visited
(post-order).
All other files are visited at least once.
.PP
The FTSENT structure contains at least the following fields:
.sp
.RS
.nf
.ta .5i +.5i +\w'struct ftsent *parent;\0\0\0'u
typedef struct ftsent {
	struct ftsent *fts_parent;		/* parent structure */
	struct ftsent *fts_link;		/* cycle or file structure */
	union {
		long number;		/* local numeric value */
		void *pointer;		/* local address value */
	} fts_local;
	char *fts_accpath;			/* path from current directory */
	char *fts_path;			/* path from starting directory */
	char *fts_name;			/* file name */
	short fts_pathlen;			/* strlen(path) */
	short fts_namelen;			/* strlen(name) */
	short fts_level;			/* depth (\-1 to N) */
	unsigned short fts_info;		/* flags for entry */
	struct stat fts_statb;			/* stat(2) information */
} FTSENT;
.fi
.RE
.PP
The fields are as follows:
.TP
fts_parent
A pointer to a structure referencing the file in the hierarchy
immediately above the current file/structure.
A parent structure for the initial entry point is provided as well,
however, only the
.I fts_local
and
.I fts_level
fields are guaranteed to be initialized.
.TP
fts_link
If a directory causes a cycle in the hierarchy, either because of a
hard link between two directories, or a symbolic link pointing to a
directory, the
.I fts_link
field of the structure will point to the structure in the hierarchy 
that references the same file as the current structure.
Upon return from the
.I ftschildren
routine, the
.I fts_link
field points to the next structure in the linked list of entries
from the directory.
Otherwise, the contents of the
.I fts_link
field are undefined.
.TP
fts_local
This field is provided for the use of the application program.
It can be used to store either a long value or an address.
.TP
fts_accpath
A path that can be used to access the file.
.TP
fts_path
The path for the file relative to the root of the traversal.
.TP
fts_name
The basename of the file.
.TP
fts_pathlen
The length of the string referenced by
.IR fts_path .
.TP
fts_namelen
The length of the string referenced by
.IR fts_name .
.TP 
fts_level
The depth of the traversal, numbered from \-1 to N.
The parent structure of the root of the traversal is numbered \-1, and
the structure for the root of the traversal is numbered 0.
.TP 
fts_info
Information describing the file.
With the exception of directories (FTS_D), all of these entries are
terminal, i.e. they will not be revisited, nor will their descendants
be visited (if they have not been visited already).
.RS
.TP
FTS_D
A directory being visited in pre-order.
.TP
FTS_DC
A directory that causes a cycle.
The 
.I fts_link
field of the structure will be filled in as well.
.TP
FTS_DEFAULT
Anything that's not one of the others.
.TP
FTS_DNR
A directory that cannot be read.
.TP
FTS_DNX
A directory that cannot be searched.
.TP
FTS_DOT
A file named ``.'' or ``..'' with a
.I fts_level
field not equal to zero, i.e. one not specified as an argument to
.IR ftsopen .
(See FTS_SEEDOT.)
.TP
FTS_DP
A directory that is being visited in post-order.
The contents of the structure will be unchanged from when the
directory was visited in pre-order.
.TP
FTS_ERR
An error indicator; the external variable
.I errno
contains an error number indicating the reason for the error.
.TP
FTS_F
A regular file.
.TP
FTS_NS
No
.IR stat (2)
information is available at this time (see FTS_NOSTAT); the
contents of the
.I fts_statb
field are undefined.
.TP
FTS_SL
A symbolic link.
.TP
FTS_SLNONE
A symbolic link with a non-existent target.
.RE
.TP
fts_statb
.IR Stat (2)
information for the file.
.PP
The
.I fts_accpath
and
.I fts_path
fields are guaranteed to be NULL-terminated
.B only
for the file most recently returned by
.IR ftsread .
The
.I fts_name
field is always NULL-terminated.
To use these fields to reference any other active files may require
that they be modified using the information contained in the
.I fts_pathlen
field.
Any such modifications should be undone before further calls to
.I ftsread
are attempted.
.PP
If all the members of the hierarchy have been returned,
.I ftsread
returns NULL and sets the external variable
.I errno
to 0.
If an error unrelated to a file in the hierarchy occurs,
.I ftsread
returns NULL and sets errno appropriately.
Otherwise, a pointer to an FTSENT structure is returned, and an
error may or may not have occurred; see FTS_ERR above.
.PP
When the most recently returned file from 
.I ftsread
is a directory being visited in pre-order, 
.I ftschildren
returns a pointer to the first entry in a linked list (sorted by
the comparison routine, if provided) of the directory entries
it contains.
The linked list is linked through the
.I fts_link
field of the FTSENT structure.
Each call to
.I ftschildren
recreates the list.
Note, cycles are not detected until a directory is actually visited,
therefore
.I ftschildren
will never return a structure with an
.I fts_info
field set to FTS_DC.
If the current file is not a directory being visited in pre-order,
or if an error occurs, or the file does not contain any entries
.I ftschildren
returns NULL.
If an error occurs,
.I ftschildren
sets errno appropriately, otherwise it sets errno to zero.
.PP
The pointers returned by
.I ftsread
and
.I ftschildren
point to structures which may be overwritten.
Structures returned by
.I ftschildren
and
.I ftsread
may be overwritten after a call to
.I ftsclose
on the same file hierarchy.
Otherwise, structures returned by
.I ftschildren
will not be overwritten until a subsequent call to either
.I ftschildren
or
.I ftsread
on the same file hierarchy.
Structures returned by
.I ftsread
will not not be overwritten until a subsequent call to
.I ftsread
on the same file hierarchy stream, unless it represents a file of type
directory, in which case it will not be overwritten until after a
subsequent call to
.I ftsread
after it has been returned by the function
.I ftsread
in post-order.
.PP
The routine
.I ftsset
allows the user application to determine further processing for the
file
.I f
of the stream
.IR ftsp .
.I Ftsset
returns 0 on success, and -1 if an error occurs.
.I Option
may be set to any one of the following values.
.TP
FTS_AGAIN
Re-visit the file; any file type may be re-visited.
The next call to
.I ftsread
will return the referenced file.
The 
.I fts_stat
and
.I fts_info
fields of the structure will be reinitialized at that time,
but no other fields will have been modified.
This option is meaningful only for the most recently returned
file from
.IR ftsread .
Normal use is for post-order directory visits, where it causes the
directory to be re-visited (in both pre and post-order) as well as all
of its descendants.
.TP
FTS_FOLLOW
The referenced file must be a symbolic link.
If the referenced file is the one most recently returned by
.IR ftsread ,
the next call to
.I ftsread
returns the file with the
.I fts_info
and
.I fts_statb
fields reinitialized to reflect the target of the symbolic link instead
of the symbolic link itself.
If the file is one of those most recently returned by
.IR ftschildren ,
the
.I fts_info
and
.I fts_statb
fields of the structure, when returned by
.IR ftsread ,
will reflect the target of the symbolic link instead of the symbolic link
itself.
In either case, if the target of the link is a directory, the pre-order
return, followed by the return of all of its descendants, followed by a
post-order return, is done.
.TP
FTS_SKIP
No descendants of this file are visited.
.PP
Hard links between directories that do not cause cycles or symbolic
links to symbolic links may cause files to be visited more than once,
or directories more than twice.
.SH ERRORS
.I Ftsopen
may fail and set errno for any of the errors specified for the library
routine
.IR malloc (3).
.PP
.I Ftsclose
may fail and set errno for any of the errors specified for the library
routine
.IR chdir (2).
.PP
.I Ftsread
and
.I ftschildren
may fail and set errno for any of the errors specified for the library
routines
.IR chdir (2),
.IR getgroups (2),
.IR malloc (3),
.IR opendir (3),
.IR readdir (3)
and
.IR stat (2).
.SH SEE ALSO
find(1), chdir(2), stat(2), qsort(3)
.SH STANDARDS
The
.I fts
utility is expected to be a superset of the POSIX 1003.1 specification.