Justin, In a moment, I'll forward my revised version of the page.
In fact, I took on most of the material that you suggested, but revised some of it significantly. But please, for the future, if you want to get do things as follows when writing a major patch: a) Notify me in advance: I maight have some comments about how planned changes should be done. b) Break logically separate parts up, and submit them separately. Big patches covering multiple logical areas are too much work to understand. I'll just make a few specific comments on the patch below. > -.BI "int ftw(const char *" dir ", int (*" fn ")(const" > -.BI "char *" file ", const struct stat *" sb ", int " flag ), > -.BI "int " nopenfd ); > -.sp > -.BI "int nftw(const char *" dir ", int (*" fn ")(const" > -.BI "char *" file ", const struct stat *" sb ", int " flag , > -.BI "struct FTW *" s ), > -.BI "int " nopenfd ", int " flags ); > +\fBtypedef int (*\fIftw_func_t\fP)(const char *\fPfile\fP, const > +struct stat *\fPsb\fP, int \fPflag\fP); > +.sp > +\fBint ftw(const char *\fIdir\fP, ftw_func_t \fPfn\fP, int \fPnopenfd\fP); > +.sp > +\fB#define _XOPEN_SOURCE 500 > +.sp > +\fBtypedef int (*\fInftw_func_t\fP)(const char *\fPfile\fP, const > +struct stat *\fPsb\fP, int \fPflag\fP, struct FTW *\fPs\fP); > +.sp > +\fBint nftw(const char *\fIdir\fP, nftw_func_t \fPfn\fP, int > +\fPnopenfd\fP, int \fPflags\fP); While I appreciate that the type ftw_func_t is defined in the header, and its use makes the declarations look simpler, it is non-standard, so I'm reluctant to use it in the man page. .SH DESCRIPTION > -\fBftw\fP() walks through the directory tree starting from the indicated > -directory \fIdir\fP. For each found entry in the tree, it calls > -\fIfn\fP() with the full pathname of the entry, a pointer to the > -.BR stat (2) > -structure for the entry and an int \fIflag\fP, which value will be one of > -the following: > +\fBftw\fP() walks recursively through the path hierarchy beginning at > +\fIdir\fP, and calls \fIfn\fP() for each directory entry found. > +Directories are handled before the files and subdirectories they > +contain (\*(lqbreadth\-first\*(rq). In truth, it is not "breadth first" but "pre-order". (The name FTW_DEPTH is a misnomer -- really it means "post-order".) > +To avoid exceeding a program's file descriptor limit, \fInopenfd\fP It is not merely the RLIMIT_NOFILE limit that matters here, so best to leave this text more vague... > +.TP > +.B FTW_ACTIONRETVAL Thanks for documenting this. I added a few small pieces. > +.SH "RETURN VALUE" Thanks -- I wrote things up somewhat differently. Cheers, Michael -- Michael Kerrisk maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 Want to help with man page maintenance? Grab the latest tarball at ftp://ftp.win.tue.nl/pub/linux-local/manpages/, read the HOWTOHELP file and grep the source files for 'FIXME'. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
