Changeset View
Changeset View
Standalone View
Standalone View
lib/libc/gen/ftw.3
Show All 14 Lines | |||||
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | ||||
.\" | .\" | ||||
.\" Sponsored in part by the Defense Advanced Research Projects | .\" Sponsored in part by the Defense Advanced Research Projects | ||||
.\" Agency (DARPA) and Air Force Research Laboratory, Air Force | .\" Agency (DARPA) and Air Force Research Laboratory, Air Force | ||||
.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. | .\" Materiel Command, USAF, under agreement number F39502-99-1-0512. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd July 5, 2004 | .Dd March 3, 2020 | ||||
.Dt FTW 3 | .Dt FTW 3 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm ftw , nftw | .Nm ftw , nftw | ||||
.Nd traverse (walk) a file tree | .Nd traverse (walk) a file tree | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.In ftw.h | .In ftw.h | ||||
.Ft int | .Ft int | ||||
▲ Show 20 Lines • Show All 120 Lines • ▼ Show 20 Lines | |||||
.Fa fn | .Fa fn | ||||
returns a non-zero value, | returns a non-zero value, | ||||
.Fn ftw | .Fn ftw | ||||
and | and | ||||
.Fn nftw | .Fn nftw | ||||
will stop processing the tree and return the value from | will stop processing the tree and return the value from | ||||
.Fa fn . | .Fa fn . | ||||
Both functions return \-1 if an error is detected. | Both functions return \-1 if an error is detected. | ||||
.Sh EXAMPLES | |||||
Following there is an example that shows how | |||||
.Nm nftw | |||||
jilles: Given that POSIX.1-2008tc2 says that ftw() is obsolete and applications should use nftw()… | |||||
Done Inline ActionsGreat idea! Thanks! 0mp: Great idea! Thanks! | |||||
can be used. | |||||
Done Inline Actionscan be used. jilles: can be used. | |||||
Done Inline ActionsDone! 0mp: Done! | |||||
It traverses the file tree starting at the directory pointed | |||||
by the only program argument and shows the complete path and a brief | |||||
indicator about the file type. | |||||
.Bd -literal -offset 2n | |||||
#include <ftw.h> | |||||
#include <stdio.h> | |||||
#include <sysexits.h> | |||||
int | |||||
nftw_callback(const char *path, const struct stat *sb, int typeflag, struct FTW *ftw) | |||||
{ | |||||
char type; | |||||
switch(typeflag) { | |||||
case FTW_F: | |||||
type = 'F'; | |||||
break; | |||||
case FTW_D: | |||||
type = 'D'; | |||||
break; | |||||
case FTW_DNR: | |||||
type = '-'; | |||||
break; | |||||
case FTW_DP: | |||||
type = 'd'; | |||||
break; | |||||
Done Inline ActionsNot having a default in this switch feels somewhat uncomfortable, especially because POSIX says FTW_SL is a valid value here. jilles: Not having a default in this switch feels somewhat uncomfortable, especially because POSIX says… | |||||
Done Inline ActionsI've included all the types now into the switch. 0mp: I've included all the types now into the switch. | |||||
Not Done Inline ActionsEspecially for example code it would be better to have defined behaviour for all values of typeflag. Consider that people might copy and paste. jilles: Especially for example code it would be better to have defined behaviour for all values of… | |||||
Done Inline Actions@jilles, Hmmm, the example now has a case statement for every possible value of typeflag. I think I don't understand your comment. Am I missing something? 0mp: @jilles, Hmmm, the example now has a case statement for every possible value of `typeflag`. I… | |||||
Not Done Inline ActionsParanoia in case the code is edited to remove cases or to add a flag (that does not exist yet) requesting a new typeflag value. Initializing type or adding a default would avoid that. jilles: Paranoia in case the code is edited to remove cases or to add a flag (that does not exist yet)… | |||||
case FTW_NS: | |||||
type = 'X'; | |||||
break; | |||||
case FTW_SL: | |||||
type = 'S'; | |||||
break; | |||||
case FTW_SLN: | |||||
type = 's'; | |||||
break; | |||||
default: | |||||
type = '?'; | |||||
break; | |||||
} | |||||
printf("[%c] %s\\n", type, path); | |||||
return (0); | |||||
} | |||||
int | |||||
main(int argc, char **argv) | |||||
{ | |||||
if (argc != 2) { | |||||
printf("Usage %s <directory>\\n", argv[0]); | |||||
return (EX_USAGE); | |||||
} else | |||||
return (nftw(argv[1], nftw_callback, /* UNUSED */ 1, 0)); | |||||
} | |||||
.Ed | |||||
.Sh ERRORS | .Sh ERRORS | ||||
The | The | ||||
.Fn ftw | .Fn ftw | ||||
and | and | ||||
.Fn nftw | .Fn nftw | ||||
functions may fail and set | functions may fail and set | ||||
.Va errno | .Va errno | ||||
for any of the errors specified for the library functions | for any of the errors specified for the library functions | ||||
▲ Show 20 Lines • Show All 51 Lines • Show Last 20 Lines |
Given that POSIX.1-2008tc2 says that ftw() is obsolete and applications should use nftw() instead, it seems better to have the example use nftw() instead.