BSD 4_4_Lite1 release

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

diff --git a/usr/src/lib/libc/gen/fts.3 b/usr/src/lib/libc/gen/fts.3
index ea25880..dde076d 100644 (file)
--- a/usr/src/lib/libc/gen/fts.3
+++ b/usr/src/lib/libc/gen/fts.3
@@ -1,11 +1,37 @@
-.\" Copyright (c) 1989, 1991 The Regents of the University of California.
-.\" All rights reserved.
+.\" Copyright (c) 1989, 1991, 1993, 1994
+.\"    The Regents of the University of California.  All rights reserved.

 .\"
 .\"

-.\" %sccs.include.redist.man%
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.

 .\"
 .\"

-.\"     @(#)fts.3      5.16 (Berkeley) %G%
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.

 .\"
 .\"

-.Dd 
+.\"     @(#)fts.3      8.5 (Berkeley) 4/16/94
+.\"
+.Dd April 16, 1994

 .Dt FTS 3
 .Os
 .Sh NAME
 .Dt FTS 3
 .Os
 .Sh NAME


@@ -16,11 +42,11 @@
 .Fd #include <sys/stat.h>
 .Fd #include <fts.h>
 .Ft FTS *
 .Fd #include <sys/stat.h>
 .Fd #include <fts.h>
 .Ft FTS *

-.Fn fts_open "char * const *path_argv" "int options" "int *compar(const FTSENT *, const FTSENT *)"
+.Fn fts_open "char * const *path_argv" "int options" "int *compar(const FTSENT **, const FTSENT **)"

 .Ft FTSENT *
 .Fn fts_read "FTS *ftsp"
 .Ft FTSENT *
 .Ft FTSENT *
 .Fn fts_read "FTS *ftsp"
 .Ft FTSENT *

-.Fn fts_children "FTS *ftsp"
+.Fn fts_children "FTS *ftsp" "int options"

 .Ft int
 .Fn fts_set "FTS ftsp" "FTSENT *f" "int options"
 .Ft int
 .Ft int
 .Fn fts_set "FTS ftsp" "FTSENT *f" "int options"
 .Ft int


@@ -83,13 +109,13 @@ typedef struct _ftsent {
        char *fts_name;                 /* file name */
        short fts_namelen;              /* strlen(fts_name) */
        short fts_level;                /* depth (\-1 to N) */
        char *fts_name;                 /* file name */
        short fts_namelen;              /* strlen(fts_name) */
        short fts_level;                /* depth (\-1 to N) */

-       int fts_error;                  /* file errno */
+       int fts_errno;                  /* file errno */

        long fts_number;                /* local numeric value */
        void *fts_pointer;              /* local address value */
        struct ftsent *fts_parent;      /* parent directory */
        struct ftsent *fts_link;        /* next file structure */
        struct ftsent *fts_cycle;       /* cycle structure */
        long fts_number;                /* local numeric value */
        void *fts_pointer;              /* local address value */
        struct ftsent *fts_parent;      /* parent directory */
        struct ftsent *fts_link;        /* next file structure */
        struct ftsent *fts_cycle;       /* cycle structure */

-       struct stat fts_statb;          /* stat(2) information */
+       struct stat *fts_statp;         /* stat(2) information */

 } FTSENT;
 .Ed
 .Pp
 } FTSENT;
 .Ed
 .Pp


@@ -156,7 +182,7 @@ A file for which no
 .Xr stat 2
 information was available.
 The contents of the
 .Xr stat 2
 information was available.
 The contents of the

-.Fa fts_statb
+.Fa fts_statp

 field are undefined.
 This is an error return, and the
 .Fa fts_errno
 field are undefined.
 This is an error return, and the
 .Fa fts_errno


@@ -166,15 +192,15 @@ A file for which no
 .Xr stat 2
 information was requested.
 The contents of the
 .Xr stat 2
 information was requested.
 The contents of the

-.Fa fts_statb
+.Fa fts_statp

 field are undefined.
 .It Dv FTS_SL
 A symbolic link.
 .It Dv FTS_SLNONE
 A symbolic link with a non-existent target.
 The contents of the
 field are undefined.
 .It Dv FTS_SL
 A symbolic link.
 .It Dv FTS_SLNONE
 A symbolic link with a non-existent target.
 The contents of the

-.Fa fts_statb
-field contain the file characteristic information for the symbolic link
+.Fa fts_statp
+field reference the file characteristic information for the symbolic link

 itself.
 .El
 .It Fa fts_accpath
 itself.
 .El
 .It Fa fts_accpath


@@ -230,12 +256,6 @@ not modified by the
 .Nm fts
 functions.
 It is initialized to 0.
 .Nm fts
 functions.
 It is initialized to 0.

-The
-.Fa fts_number
-and
-.Fa fts_pointer
-fields occupy the same physical location; using both may cause undefined
-results.

 .It Fa fts_pointer
 This field is provided for the use of the application program and is
 not modified by the
 .It Fa fts_pointer
 This field is provided for the use of the application program and is
 not modified by the


@@ -243,12 +263,6 @@ not modified by the
 functions.
 It is initialized to
 .Dv NULL .
 functions.
 It is initialized to
 .Dv NULL .

-The
-.Fa fts_number
-and
-.Fa fts_pointer
-fields occupy the same physical location; using both may cause undefined
-results.

 .It Fa fts_parent
 A pointer to the
 .Fa FTSENT
 .It Fa fts_parent
 A pointer to the
 .Fa FTSENT


@@ -287,8 +301,9 @@ structure.
 Otherwise, the contents of the
 .Fa fts_cycle
 field are undefined.
 Otherwise, the contents of the
 .Fa fts_cycle
 field are undefined.

-.It Fa fts_statb
-.Xr Stat 2
+.It Fa fts_statp
+A pointer to
+.Xr stat 2

 information for the file.
 .El
 .Pp
 information for the file.
 .El
 .Pp


@@ -337,6 +352,11 @@ The options are selected by
 .Em or Ns 'ing
 the following values:
 .Bl -tag -width "FTS_PHYSICAL"
 .Em or Ns 'ing
 the following values:
 .Bl -tag -width "FTS_PHYSICAL"

+.It Dv FTS_COMFOLLOW
+This option causes any symbolic link specified as a root path to be
+followed immediately whether or not
+.Dv FTS_LOGICAL
+is also specified.

 .It Dv FTS_LOGICAL
 This option causes the
 .Nm fts
 .It Dv FTS_LOGICAL
 This option causes the
 .Nm fts


@@ -376,9 +396,8 @@ pathnames were provided as arguments to
 .It Dv FTS_NOSTAT
 By default, returned
 .Fa FTSENT
 .It Dv FTS_NOSTAT
 By default, returned
 .Fa FTSENT

-structures contain file characteristic
-information (the
-.Fa statb
+structures reference file characteristic information (the
+.Fa statp

 field) for each file visited.
 This option relaxes that requirement as a performance optimization,
 allowing the
 field) for each file visited.
 This option relaxes that requirement as a performance optimization,
 allowing the


@@ -388,7 +407,7 @@ functions to set the
 field to
 .Dv FTS_NSOK
 and leave the contents of the
 field to
 .Dv FTS_NSOK
 and leave the contents of the

-.Fa statb
+.Fa statp

 field undefined.
 .It Dv FTS_PHYSICAL
 This option causes the
 field undefined.
 .It Dv FTS_PHYSICAL
 This option causes the


@@ -455,17 +474,18 @@ If the
 field is set to
 .Dv FTS_NS
 or
 field is set to
 .Dv FTS_NS
 or

-.DV FTS_NSOK ,
+.Dv FTS_NSOK ,

 the
 the

-.Fa fts_stab
+.Fa fts_statp

 field may not either.
 If the
 .Fn compar
 argument is
 .Dv NULL ,
 field may not either.
 If the
 .Fn compar
 argument is
 .Dv NULL ,

-the directory traversal order is unspecified except
-for the root paths which are traversed in the order listed in
-.Fa path_argv .
+the directory traversal order is in the order listed in
+.Fa path_argv
+for the root paths, and in the order listed in the directory for
+everything else.

 .Sh FTS_READ
 The
 .Fn fts_read
 .Sh FTS_READ
 The
 .Fn fts_read


@@ -574,6 +594,19 @@ may be overwritten after a call to
 or
 .Fn fts_read
 on the same file hierarchy stream.
 or
 .Fn fts_read
 on the same file hierarchy stream.

+.Pp
+.Em Option
+may be set to the following value:
+.Bl -tag -width FTS_NAMEONLY
+.It Dv FTS_NAMEONLY
+Only the names of the files are needed.
+The contents of all the fields in the returned linked list of structures
+are undefined with the exception of the
+.Fa fts_name
+and
+.Fa fts_namelen
+fields.
+.El

 .Sh FTS_SET
 The function
 .Fn fts_set
 .Sh FTS_SET
 The function
 .Fn fts_set


@@ -615,7 +648,7 @@ the next call to
 returns the file with the
 .Fa fts_info
 and
 returns the file with the
 .Fa fts_info
 and

-.Fa fts_statb
+.Fa fts_statp

 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
 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


@@ -623,7 +656,7 @@ If the file is one of those most recently returned by
 the
 .Fa fts_info
 and
 the
 .Fa fts_info
 and

-.Fa fts_statb
+.Fa fts_statp

 fields of the structure, when returned by
 .Fn fts_read ,
 will reflect the target of the symbolic link instead of the symbolic link
 fields of the structure, when returned by
 .Fn fts_read ,
 will reflect the target of the symbolic link instead of the symbolic link


@@ -660,16 +693,18 @@ returns 0 on success, and \-1 if an error occurs.
 .Sh ERRORS
 The function
 .Fn fts_open
 .Sh ERRORS
 The function
 .Fn fts_open

-may fail and set errno for any of the errors specified for the library
-functions
+may fail and set
+.Va errno
+for any of the errors specified for the library functions

 .Xr open 2
 and
 .Xr malloc 3 .
 .Pp
 The function
 .Fn fts_close
 .Xr open 2
 and
 .Xr malloc 3 .
 .Pp
 The function
 .Fn fts_close

-may fail and set errno for any of the errors specified for the library
-functions
+may fail and set
+.Va errno
+for any of the errors specified for the library functions

 .Xr chdir 2
 and
 .Xr close 2 .
 .Xr chdir 2
 and
 .Xr close 2 .


@@ -678,14 +713,28 @@ The functions
 .Fn fts_read
 and
 .Fn fts_children
 .Fn fts_read
 and
 .Fn fts_children

-may fail and set errno for any of the errors specified for the library
-functions
+may fail and set
+.Va errno
+for any of the errors specified for the library functions

 .Xr chdir 2 ,
 .Xr malloc 3 ,
 .Xr opendir 3 ,
 .Xr readdir 3
 and
 .Xr stat 2 .
 .Xr chdir 2 ,
 .Xr malloc 3 ,
 .Xr opendir 3 ,
 .Xr readdir 3
 and
 .Xr stat 2 .

+.Pp
+In addition,
+.Fn fts_children ,
+.Fn fts_open
+and
+.Fn fts_set
+may fail and set
+.Va errno
+as follows:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The options were invalid.
+.El

 .Sh SEE ALSO
 .Xr find 1 ,
 .Xr chdir 2 ,
 .Sh SEE ALSO
 .Xr find 1 ,
 .Xr chdir 2 ,


@@ -694,6 +743,6 @@ and
 .Sh STANDARDS
 The
 .Nm fts
 .Sh STANDARDS
 The
 .Nm fts

-utility is expected to be a superset of the
+utility is expected to be included in a future

 .St -p1003.1-88
 .St -p1003.1-88

-specification.
+revision.