Changeset View
Standalone View
lib/libc/gen/fts.3
Show All 22 Lines | |||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" 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 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" @(#)fts.3 8.5 (Berkeley) 4/16/94 | .\" @(#)fts.3 8.5 (Berkeley) 4/16/94 | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd January 12, 2014 | .Dd May 5, 2014 | ||||
.Dt FTS 3 | .Dt FTS 3 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm fts | .Nm fts | ||||
.Nd traverse a file hierarchy | .Nd traverse a file hierarchy | ||||
.Sh LIBRARY | .Sh LIBRARY | ||||
.Lb libc | .Lb libc | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.In fts.h | .In fts.h | ||||
.Ft FTS * | .Ft FTS * | ||||
.Fn fts_open "char * const *path_argv" "int options" "int (*compar)(const FTSENT * const *, const FTSENT * const *)" | .Fn fts_open "char * const *path_argv" "int options" "int (*compar)(const FTSENT * const *, const FTSENT * const *)" | ||||
.Ft FTS * | |||||
.Fn fts_open_b "char * const *path_argv" "int options" "int (^compar)(const FTSENT * const *, const FTSENT * const *)" | |||||
.Ft FTSENT * | .Ft FTSENT * | ||||
.Fn fts_read "FTS *ftsp" | .Fn fts_read "FTS *ftsp" | ||||
.Ft FTSENT * | .Ft FTSENT * | ||||
.Fn fts_children "FTS *ftsp" "int options" | .Fn fts_children "FTS *ftsp" "int options" | ||||
.Ft int | .Ft int | ||||
.Fn fts_set "FTS *ftsp" "FTSENT *f" "int options" | .Fn fts_set "FTS *ftsp" "FTSENT *f" "int options" | ||||
.Ft void | .Ft void | ||||
.Fn fts_set_clientptr "FTS *ftsp" "void *clientdata" | .Fn fts_set_clientptr "FTS *ftsp" "void *clientdata" | ||||
.Ft void * | .Ft void * | ||||
.Fn fts_get_clientptr "FTS *ftsp" | .Fn fts_get_clientptr "FTS *ftsp" | ||||
.Ft FTS * | .Ft FTS * | ||||
.Fn fts_get_stream "FTSENT *f" | .Fn fts_get_stream "FTSENT *f" | ||||
.Ft int | .Ft int | ||||
.Fn fts_close "FTS *ftsp" | .Fn fts_close "FTS *ftsp" | ||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The | The | ||||
.Nm | .Nm | ||||
functions are provided for traversing | functions are provided for traversing | ||||
.Ux | .Ux | ||||
file hierarchies. | file hierarchies. | ||||
A simple overview is that the | A simple overview is that the | ||||
.Fn fts_open | .Fn fts_open | ||||
function returns a | and | ||||
.Fn fts_open_b | |||||
functions return a | |||||
wblock: s/returns/return/ | |||||
.Dq handle | .Dq handle | ||||
on a file hierarchy, which is then supplied to | on a file hierarchy, which is then supplied to | ||||
the other | the other | ||||
.Nm | .Nm | ||||
functions. | functions. | ||||
The function | The function | ||||
.Fn fts_read | .Fn fts_read | ||||
returns a pointer to a structure describing one of the files in the file | returns a pointer to a structure describing one of the files in the file | ||||
▲ Show 20 Lines • Show All 110 Lines • ▼ Show 20 Lines | |||||
field will be set to indicate what caused the error. | field will be set to indicate what caused the error. | ||||
.It Dv FTS_DOT | .It Dv FTS_DOT | ||||
A file named | A file named | ||||
.Ql .\& | .Ql .\& | ||||
or | or | ||||
.Ql ..\& | .Ql ..\& | ||||
which was not specified as a file name to | which was not specified as a file name to | ||||
.Fn fts_open | .Fn fts_open | ||||
or | |||||
.Fn fts_open_b | |||||
(see | (see | ||||
.Dv FTS_SEEDOT ) . | .Dv FTS_SEEDOT ) . | ||||
.It Dv FTS_DP | .It Dv FTS_DP | ||||
A directory being visited in post-order. | A directory being visited in post-order. | ||||
The contents of the | The contents of the | ||||
.Vt FTSENT | .Vt FTSENT | ||||
structure will be unchanged from when | structure will be unchanged from when | ||||
the directory was visited in pre-order, except for the | the directory was visited in pre-order, except for the | ||||
Show All 32 Lines | |||||
itself. | itself. | ||||
.El | .El | ||||
.It Fa fts_accpath | .It Fa fts_accpath | ||||
A path for accessing the file from the current directory. | A path for accessing the file from the current directory. | ||||
.It Fa fts_path | .It Fa fts_path | ||||
The path for the file relative to the root of the traversal. | The path for the file relative to the root of the traversal. | ||||
This path contains the path specified to | This path contains the path specified to | ||||
.Fn fts_open | .Fn fts_open | ||||
or | |||||
.Fn fts_open_b | |||||
as a prefix. | as a prefix. | ||||
.It Fa fts_pathlen | .It Fa fts_pathlen | ||||
The length of the string referenced by | The length of the string referenced by | ||||
.Fa fts_path . | .Fa fts_path . | ||||
.It Fa fts_name | .It Fa fts_name | ||||
The name of the file. | The name of the file. | ||||
.It Fa fts_namelen | .It Fa fts_namelen | ||||
The length of the string referenced by | The length of the string referenced by | ||||
▲ Show 20 Lines • Show All 268 Lines • ▼ Show 20 Lines | |||||
If the | If the | ||||
.Fn compar | .Fn compar | ||||
argument is | argument is | ||||
.Dv NULL , | .Dv NULL , | ||||
the directory traversal order is in the order listed in | the directory traversal order is in the order listed in | ||||
.Fa path_argv | .Fa path_argv | ||||
for the root paths, and in the order listed in the directory for | for the root paths, and in the order listed in the directory for | ||||
everything else. | everything else. | ||||
.Sh FTS_OPEN_B | |||||
.Fn fts_open_b | |||||
Not Done Inline ActionsThis line should be deleted. There is no leading "The" in this form: "blahblah is" wblock: This line should be deleted. There is no leading "The" in this form:
"blahblah is"
as opposed… | |||||
is a block-based version of | |||||
.Fn fts_open | |||||
where | |||||
.Fa compar | |||||
is a block pointer that is passed to | |||||
.Xr qsort_b 3 . | |||||
Done Inline ActionsThis sentence is ambiguous here. The "instead of" can be misinterpreted. It might not be necessary to describe what fts_open does in this sentence, just what fts_open_b does. That reduces the number of things that can be confused. A suggestion follows. Note that I also find the "The blahblah function" needlessly redundant, at least after the first use. I suggest just referring to these and other special words by their name alone, like this sentence refers to fts_open. .Fn fts_open_b A possibly better way to do this would be to say (markup omitted) "fts_open_b is a block-based version of fts_open. It works in the same way, but compar is a block pointer that is passed to qsort_b(3)." wblock: This sentence is ambiguous here. The "instead of" can be misinterpreted. It might not be… | |||||
.Sh FTS_READ | .Sh FTS_READ | ||||
The | The | ||||
Not Done Inline ActionsThis last part is still a little ambiguous, although I can see where it might be wanted for comparison. The sentence could be ended immediately after .Xr qsort_b 3. Given the clarity improvement to the first part of the sentence, this part should work either way. wblock: This last part is still a little ambiguous, although I can see where it might be wanted for… | |||||
.Fn fts_read | .Fn fts_read | ||||
function returns a pointer to an | function returns a pointer to an | ||||
.Vt FTSENT | .Vt FTSENT | ||||
structure describing a file in | structure describing a file in | ||||
the hierarchy. | the hierarchy. | ||||
Directories (that are readable and do not cause cycles) are visited at | Directories (that are readable and do not cause cycles) are visited at | ||||
least twice, once in pre-order and once in post-order. | least twice, once in pre-order and once in post-order. | ||||
All other files are visited at least once. | All other files are visited at least once. | ||||
▲ Show 20 Lines • Show All 236 Lines • ▼ Show 20 Lines | |||||
.It Bq Er EINVAL | .It Bq Er EINVAL | ||||
The options were invalid, or the list were empty. | The options were invalid, or the list were empty. | ||||
.El | .El | ||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr find 1 , | .Xr find 1 , | ||||
.Xr chdir 2 , | .Xr chdir 2 , | ||||
.Xr stat 2 , | .Xr stat 2 , | ||||
.Xr ftw 3 , | .Xr ftw 3 , | ||||
.Xr qsort 3 | .Xr qsort 3 , | ||||
.Xr qsort_b 3 | |||||
.Sh HISTORY | .Sh HISTORY | ||||
The | The | ||||
.Nm | .Nm | ||||
interface was first introduced in | interface was first introduced in | ||||
.Bx 4.4 . | .Bx 4.4 . | ||||
The | The | ||||
.Fn fts_get_clientptr , | .Fn fts_get_clientptr , | ||||
.Fn fts_get_stream , | .Fn fts_get_stream , | ||||
and | and | ||||
.Fn fts_set_clientptr | .Fn fts_set_clientptr | ||||
functions were introduced in | functions were introduced in | ||||
.Fx 5.0 , | .Fx 5.0 , | ||||
principally to provide for alternative interfaces to the | principally to provide for alternative interfaces to the | ||||
.Nm | .Nm | ||||
functionality using different data structures. | functionality using different data structures. | ||||
The | |||||
.Fn fts_open_b | |||||
function first appeared in Mac OS X. | |||||
This implementation was created by Stacey Son for | |||||
.Fx 11.0 . | |||||
.Sh BUGS | .Sh BUGS | ||||
The | The | ||||
.Fn fts_open | .Fn fts_open | ||||
function will automatically set the | and | ||||
.Fn fts_open_b | |||||
functions will automatically set the | |||||
.Dv FTS_NOCHDIR | .Dv FTS_NOCHDIR | ||||
option if the | option if the | ||||
.Dv FTS_LOGICAL | .Dv FTS_LOGICAL | ||||
option is provided, or if it cannot | option is provided, or if it cannot | ||||
.Xr open 2 | .Xr open 2 | ||||
the current directory. | the current directory. |
s/returns/return/