system call is unmount not umount

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

.\" Copyright (c) 1989 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms are permitted
.\" provided that the above copyright notice and this paragraph are
.\" duplicated in all such forms and that any documentation,
.\" advertising materials, and other materials related to such
.\" distribution and use acknowledge that the software was developed
.\" by the University of California, Berkeley.  The name of the
.\" University may not be used to endorse or promote products derived
.\" from this software without specific prior written permission.
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
.\"
.\"	@(#)fts.3	5.1 (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, options, compar)
char *path;
int options, (*compar)();

FTS *
ftsopen(path_argv, options | FTS_MULTIPLE, 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 returns a pointer to a file hierarchy rooted at
.IR path .
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_MULTIPLE
.I Ftsopen
takes a single file name as a path argument by default.
If the FTS_MULTIPLE option is specified, the path argument is a pointer
to an array of character pointers (``argv'') to the paths to be traversed.
The array must be terminated by a pointer to a NULL string.
In this case the ``logical'' hierarchy is traversed, i.e. it's as if
there's a virtual directory that contains the list of paths supplied,
and the hierarchy is rooted in that directory.
.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 .
.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.
Note, the
.I accpath
and
.I path
fields of the FTSENT structures may not be used in this comparison.
.PP
If both FTS_MULTIPLE and the user comparison routine are specified,
the root paths are processed in sorted order.
Otherwise, the root paths are processed in the order specified by
the user.
.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 *parent;		/* parent structure */
	struct ftsent *link;		/* cycle or file structure */
	union {
		long number;		/* local numeric value */
		void *pointer;		/* local address value */
	} local;
	char *accpath;			/* path from current directory */
	char *path;			/* path from starting directory */
	char *name;			/* file name */
	short pathlen;			/* strlen(path) */
	short namelen;			/* strlen(name) */
	short level;			/* depth (\-1 to N) */
	unsigned short info;		/* flags for entry */
	struct stat statb;			/* stat(2) information */
} FTSENT;
.fi
.RE
.PP
The fields are as follows:
.TP
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 local
and
.I level
fields are guaranteed to be initialized.
.TP
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 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 link
field points to the next structure in the linked list of entries
from the directory.
Otherwise, the contents of the link field are undefined.
.TP
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
accpath
A path that can be used to access the file.
.TP
path
The path for the file relative to the root of the traversal.
.TP
name
The basename of the file.
.TP
pathlen
The length of the string referenced by
.IR path .
.TP
namelen
The length of the string referenced by
.IR name .
.TP 
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 
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 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 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 statb
field are undefined.
.TP
FTS_SL
A symbolic link.
.TP
FTS_SLNONE
A symbolic link with a non-existent target.
.RE
.TP
statb
.IR Stat (2)
information for the file.
.PP
The
.IR accpath
and
.I path
fields are guaranteed to be NULL-terminated
.B only
for the file most recently returned by
.IR ftsread .
The
.I 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 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 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 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 stat
and
.I 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 info
and
.I 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 info
and
.I 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 POSIX 1003.1 compliant.