2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 1993 Michael Haardt (michael@moria.de)
|
2006-05-24 05:15:12 +00:00
|
|
|
.\" and copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
|
|
|
|
.\" and copyright (c) 2006 Justin Pryzby <justinpryzby@users.sf.net>
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" and copyright (c) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
.\" This is free documentation; you can redistribute it and/or
|
|
|
|
.\" modify it under the terms of the GNU General Public License as
|
|
|
|
.\" published by the Free Software Foundation; either version 2 of
|
|
|
|
.\" the License, or (at your option) any later version.
|
|
|
|
.\"
|
|
|
|
.\" The GNU General Public License's references to "object code"
|
|
|
|
.\" and "executables" are to be interpreted as the output of any
|
|
|
|
.\" document formatting or typesetting system, including
|
|
|
|
.\" intermediate and printed output.
|
|
|
|
.\"
|
|
|
|
.\" This manual is distributed in the hope that it will be useful,
|
|
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
|
.\" GNU General Public License for more details.
|
|
|
|
.\"
|
|
|
|
.\" You should have received a copy of the GNU General Public
|
|
|
|
.\" License along with this manual; if not, write to the Free
|
|
|
|
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
|
|
|
|
.\" USA.
|
|
|
|
.\"
|
|
|
|
.\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu)
|
2006-05-24 05:15:12 +00:00
|
|
|
.\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net>
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" document FTW_ACTIONRETVAL; include .SH "RETURN VALUE";
|
2006-05-24 05:15:12 +00:00
|
|
|
.\" 2006-05-24, Justin Pryzby <justinpryzby@users.sf.net> and
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" Michael Kerrisk <mtk.manpages@gmail.com>
|
2006-05-24 05:15:12 +00:00
|
|
|
.\" reorganized and rewrote much of the page
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" 2006-05-24, Michael Kerrisk <mtk.manpages@gmail.com>
|
2006-05-24 05:15:12 +00:00
|
|
|
.\" Added an example program.
|
_exit.2, brk.2, capget.2, chdir.2, chmod.2, chown.2, chroot.2, getdtablesize.2, gethostname.2, getpagesize.2, getsid.2, killpg.2, mknod.2, mknodat.2, poll.2, posix_fadvise.2, pread.2, readlink.2, setpgid.2, setreuid.2, sigaltstack.2, stat.2, symlink.2, sync.2, truncate.2, vfork.2, wait.2, wait4.2, a64l.3, abs.3, acos.3, acosh.3, asin.3, asinh.3, atan.3, atan2.3, atoi.3, cbrt.3, ceil.3, copysign.3, cosh.3, dirfd.3, div.3, ecvt.3, erf.3, erfc.3, exp.3, exp2.3, fabs.3, fdim.3, ffs.3, floor.3, fma.3, fmax.3, fmin.3, fmod.3, fpclassify.3, frexp.3, ftw.3, fwide.3, gcvt.3, getcwd.3, getdate.3, getgrent.3, gethostid.3, getpass.3, getpwent.3, getsubopt.3, getw.3, hypot.3, ilogb.3, index.3, isalpha.3, isgreater.3, iswblank.3, j0.3, ldexp.3, lockf.3, log.3, log10.3, log1p.3, logb.3, lrint.3, lround.3, mkstemp.3, mktemp.3, modf.3, mq_receive.3, mq_send.3, nan.3, nextafter.3, posix_fallocate.3, posix_memalign.3, printf.3, qecvt.3, random.3, realpath.3, remainder.3, remquo.3, rint.3, round.3, scalb.3, scalbln.3, scanf.3, siginterrupt.3, signbit.3, sigset.3, sinh.3, sqrt.3, strcasecmp.3, strcat.3, strchr.3, strcmp.3, strcoll.3, strcpy.3, strfry.3, strpbrk.3, strsep.3, strspn.3, strstr.3, strtod.3, strtok.3, strtol.3, strtoul.3, strxfrm.3, tanh.3, tgamma.3, trunc.3, ttyslot.3, ualarm.3, usleep.3, wprintf.3, armscii-8.7, cp1251.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-3.7, iso_8859-5.7, iso_8859-6.7, iso_8859-8.7, koi8-u.7: tstamp
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-09-19 17:19:13 +00:00
|
|
|
.TH FTW 3 2010-09-20 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
ftw, nftw \- file tree walk
|
|
|
|
.SH SYNOPSIS
|
2006-05-24 05:15:12 +00:00
|
|
|
.nf
|
2004-11-03 13:51:07 +00:00
|
|
|
.B #include <ftw.h>
|
|
|
|
.sp
|
2007-04-12 22:42:49 +00:00
|
|
|
.BI "int ftw(const char *" dirpath ,
|
2007-09-23 17:26:21 +00:00
|
|
|
.BI " int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
|
2006-05-24 05:15:12 +00:00
|
|
|
.BI " int " typeflag ),
|
2006-05-25 06:24:07 +00:00
|
|
|
.BI " int " nopenfd );
|
2004-11-03 13:51:07 +00:00
|
|
|
.sp
|
getresuid.2, mremap.2, poll.2, remap_file_pages.2, setresuid.2, splice.2, sync_file_range.2, syscall.2, tee.2, vmsplice.2, INFINITY.3, aio_init.3, asprintf.3, assert_perror.3, basename.3, bsd_signal.3, canonicalize_file_name.3, clog10.3, crypt.3, dl_iterate_phdr.3, dlopen.3, encrypt.3, exp10.3, fcloseall.3, fenv.3, fopencookie.3, ftw.3, getaddrinfo_a.3, getloadavg.3, getutent.3, grantpt.3, hsearch.3, lseek64.3, memmem.3, mempcpy.3, pow10.3, program_invocation_name.3, ptsname.3, putgrent.3, sched_getcpu.3, sincos.3, strchr.3, strfry.3, strnlen.3, strptime.3, strstr.3, strverscmp.3, swab.3, sysv_signal.3, tsearch.3, unlockpt.3, wcwidth.3: Add reference to feature_test_macros(7)
Some pages simply list feature test macro requirements in
the form:
#define #GNU_SOURCE
#include <someheader.h>
For these pages, add a "See feature_test_macros(7)" comment
on the "#define" line.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-10-31 04:31:47 +00:00
|
|
|
.BR "#define _XOPEN_SOURCE 500" " /* See feature_test_macros(7) */"
|
2006-05-24 05:15:12 +00:00
|
|
|
.B #include <ftw.h>
|
|
|
|
.sp
|
2007-04-12 22:42:49 +00:00
|
|
|
.BI "int nftw(const char *" dirpath ,
|
|
|
|
.BI " int (*" fn ") (const char *" fpath ", const struct stat *" sb ,
|
2006-05-24 05:15:12 +00:00
|
|
|
.BI " int " typeflag ", struct FTW *" ftwbuf ),
|
2006-05-25 06:24:07 +00:00
|
|
|
.BI " int " nopenfd ", int " flags );
|
2006-05-24 05:15:12 +00:00
|
|
|
.fi
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
2007-05-12 09:06:04 +00:00
|
|
|
.BR ftw ()
|
|
|
|
walks through the directory tree that is
|
2006-05-24 05:15:12 +00:00
|
|
|
located under the directory \fIdirpath\fP,
|
|
|
|
and calls \fIfn\fP() once for each entry in the tree.
|
2007-04-12 22:42:49 +00:00
|
|
|
By default, directories are handled before the files and
|
2010-01-16 17:41:29 +00:00
|
|
|
subdirectories they contain (preorder traversal).
|
2006-05-24 05:15:12 +00:00
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
To avoid using up all of the calling process's file descriptors,
|
|
|
|
\fInopenfd\fP specifies the maximum number of directories that
|
2007-05-12 09:06:04 +00:00
|
|
|
.BR ftw ()
|
|
|
|
will hold open simultaneously.
|
2006-05-24 05:15:12 +00:00
|
|
|
When
|
2007-05-12 09:06:04 +00:00
|
|
|
the search depth exceeds this,
|
|
|
|
.BR ftw ()
|
|
|
|
will become slower because
|
|
|
|
directories have to be closed and reopened.
|
|
|
|
.BR ftw ()
|
|
|
|
uses at most
|
2006-05-24 05:15:12 +00:00
|
|
|
one file descriptor for each level in the directory tree.
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
For each entry found in the tree,
|
2006-05-24 05:15:12 +00:00
|
|
|
.BR ftw ()
|
|
|
|
calls
|
|
|
|
\fIfn\fP() with three arguments:
|
|
|
|
.IR fpath ,
|
|
|
|
.IR sb ,
|
|
|
|
and
|
|
|
|
.IR typeflag .
|
2007-09-20 16:26:31 +00:00
|
|
|
.I fpath
|
2010-05-24 14:33:23 +00:00
|
|
|
is the pathname of the entry,
|
|
|
|
and is expressed either as a pathname relative to the calling process's
|
|
|
|
current working directory at the time of the call to
|
|
|
|
.BR ftw (),
|
|
|
|
if
|
|
|
|
.IR dirpath
|
|
|
|
was expressed as a relative pathname,
|
|
|
|
or as an absolute pathname, if
|
|
|
|
.I dirpath
|
|
|
|
was expressed as an absolute pathname.
|
2007-09-20 16:26:31 +00:00
|
|
|
.I sb
|
2006-05-24 05:15:12 +00:00
|
|
|
is a pointer to the
|
2007-09-20 16:26:31 +00:00
|
|
|
.I stat
|
2007-04-12 22:42:49 +00:00
|
|
|
structure returned by a call to
|
|
|
|
.BR stat (2)
|
|
|
|
for
|
2006-05-24 05:15:12 +00:00
|
|
|
.IR fpath .
|
2007-09-20 16:26:31 +00:00
|
|
|
.I typeflag
|
2006-05-24 05:15:12 +00:00
|
|
|
is an integer that has one of the following values:
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B FTW_F
|
2006-05-24 05:15:12 +00:00
|
|
|
.I fpath
|
2008-03-19 11:56:53 +00:00
|
|
|
is a regular file.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B FTW_D
|
2006-05-24 05:15:12 +00:00
|
|
|
.I fpath
|
|
|
|
is a directory.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B FTW_DNR
|
2006-05-24 05:15:12 +00:00
|
|
|
.I fpath
|
|
|
|
is a directory which can't be read.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B FTW_NS
|
2007-04-12 22:42:49 +00:00
|
|
|
The
|
|
|
|
.BR stat (2)
|
|
|
|
call failed on
|
2006-05-24 05:15:12 +00:00
|
|
|
.IR fpath ,
|
|
|
|
which is not a symbolic link.
|
2006-05-24 09:19:03 +00:00
|
|
|
.sp
|
2007-04-12 22:42:49 +00:00
|
|
|
If
|
2006-05-24 05:15:12 +00:00
|
|
|
.I fpath
|
2007-04-12 22:42:49 +00:00
|
|
|
is a symbolic link and
|
2006-05-24 05:15:12 +00:00
|
|
|
.BR stat (2)
|
2006-08-04 12:39:17 +00:00
|
|
|
failed, POSIX.1-2001 states
|
2006-05-24 05:15:12 +00:00
|
|
|
that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP (see below)
|
|
|
|
is passed in
|
|
|
|
.IR typeflag .
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
intro.1, time.1, adjtimex.2, capget.2, eventfd.2, fcntl.2, getrlimit.2, getsockopt.2, gettimeofday.2, intro.2, ioctl_list.2, ioperm.2, mlock.2, pivot_root.2, poll.2, prctl.2, ptrace.2, sched_setscheduler.2, select_tut.2, semget.2, sigaltstack.2, signalfd.2, sysctl.2, timer_settime.2, timerfd_create.2, wait.2, CPU_SET.3, argz_add.3, assert_perror.3, atexit.3, backtrace.3, bcmp.3, clearenv.3, ctime.3, dl_iterate_phdr.3, dlopen.3, ecvt.3, errno.3, error.3, ether_aton.3, exit.3, fenv.3, ferror.3, finite.3, flockfile.3, fnmatch.3, fpathconf.3, fpclassify.3, ftime.3, ftok.3, ftw.3, fwide.3, getaddrinfo.3, gethostbyname.3, getlogin.3, getnameinfo.3, getnetent.3, getopt.3, getprotoent.3, getrpcent.3, getservent.3, glob.3, hsearch.3, inet.3, isalpha.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, longjmp.3, lsearch.3, malloc.3, matherr.3, mblen.3, mbsinit.3, mbtowc.3, on_exit.3, printf.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_attr_setdetachstate.3, pthread_attr_setguardsize.3, pthread_attr_setinheritsched.3, pthread_attr_setschedparam.3, pthread_attr_setschedpolicy.3, pthread_attr_setscope.3, pthread_attr_setstack.3, pthread_attr_setstackaddr.3, pthread_attr_setstacksize.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_equal.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_setaffinity_np.3, pthread_setcancelstate.3, pthread_setconcurrency.3, pthread_setschedparam.3, pthread_setschedprio.3, ptsname.3, putenv.3, putgrent.3, raise.3, rcmd.3, regex.3, rexec.3, rpc.3, rpmatch.3, rtnetlink.3, scandir.3, sem_init.3, setaliasent.3, setbuf.3, setenv.3, setjmp.3, signbit.3, stdio_ext.3, strtod.3, strtol.3, strtoul.3, system.3, termios.3, timeradd.3, tzset.3, ualarm.3, wctomb.3, xdr.3, st.4, tty_ioctl.4, core.5, elf.5, proc.5, bootparam.7, capabilities.7, icmp.7, ip.7, ipv6.7, math_error.7, mdoc.samples.7, mq_overview.7, pthreads.7, raw.7, regex.7, socket.7, tcp.7, tzselect.8: Global fix: s/non-zero/nonzero/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:40:55 +00:00
|
|
|
To stop the tree walk, \fIfn\fP() returns a nonzero value; this
|
2007-05-12 09:06:04 +00:00
|
|
|
value will become the return value of
|
|
|
|
.BR ftw ().
|
2006-05-24 05:15:12 +00:00
|
|
|
As long as \fIfn\fP() returns 0,
|
2007-05-12 09:06:04 +00:00
|
|
|
.BR ftw ()
|
|
|
|
will continue either until it has traversed the entire tree,
|
2007-04-12 22:42:49 +00:00
|
|
|
in which case it will return zero,
|
2006-05-24 09:19:03 +00:00
|
|
|
or until it encounters an error (such as a
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR malloc (3)
|
|
|
|
failure), in which case it will return \-1.
|
|
|
|
.PP
|
2007-05-12 09:06:04 +00:00
|
|
|
Because
|
|
|
|
.BR ftw ()
|
|
|
|
uses dynamic data structures, the only safe way to
|
intro.1, time.1, adjtimex.2, capget.2, eventfd.2, fcntl.2, getrlimit.2, getsockopt.2, gettimeofday.2, intro.2, ioctl_list.2, ioperm.2, mlock.2, pivot_root.2, poll.2, prctl.2, ptrace.2, sched_setscheduler.2, select_tut.2, semget.2, sigaltstack.2, signalfd.2, sysctl.2, timer_settime.2, timerfd_create.2, wait.2, CPU_SET.3, argz_add.3, assert_perror.3, atexit.3, backtrace.3, bcmp.3, clearenv.3, ctime.3, dl_iterate_phdr.3, dlopen.3, ecvt.3, errno.3, error.3, ether_aton.3, exit.3, fenv.3, ferror.3, finite.3, flockfile.3, fnmatch.3, fpathconf.3, fpclassify.3, ftime.3, ftok.3, ftw.3, fwide.3, getaddrinfo.3, gethostbyname.3, getlogin.3, getnameinfo.3, getnetent.3, getopt.3, getprotoent.3, getrpcent.3, getservent.3, glob.3, hsearch.3, inet.3, isalpha.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, longjmp.3, lsearch.3, malloc.3, matherr.3, mblen.3, mbsinit.3, mbtowc.3, on_exit.3, printf.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_attr_setdetachstate.3, pthread_attr_setguardsize.3, pthread_attr_setinheritsched.3, pthread_attr_setschedparam.3, pthread_attr_setschedpolicy.3, pthread_attr_setscope.3, pthread_attr_setstack.3, pthread_attr_setstackaddr.3, pthread_attr_setstacksize.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_equal.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_setaffinity_np.3, pthread_setcancelstate.3, pthread_setconcurrency.3, pthread_setschedparam.3, pthread_setschedprio.3, ptsname.3, putenv.3, putgrent.3, raise.3, rcmd.3, regex.3, rexec.3, rpc.3, rpmatch.3, rtnetlink.3, scandir.3, sem_init.3, setaliasent.3, setbuf.3, setenv.3, setjmp.3, signbit.3, stdio_ext.3, strtod.3, strtol.3, strtoul.3, system.3, termios.3, timeradd.3, tzset.3, ualarm.3, wctomb.3, xdr.3, st.4, tty_ioctl.4, core.5, elf.5, proc.5, bootparam.7, capabilities.7, icmp.7, ip.7, ipv6.7, math_error.7, mdoc.samples.7, mq_overview.7, pthreads.7, raw.7, regex.7, socket.7, tcp.7, tzselect.8: Global fix: s/non-zero/nonzero/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:40:55 +00:00
|
|
|
exit out of a tree walk is to return a nonzero value from \fIfn\fP().
|
2006-05-24 05:15:12 +00:00
|
|
|
To allow a signal to terminate the walk without causing a memory leak,
|
|
|
|
have the handler set a global flag that is checked by \fIfn\fP().
|
2007-05-12 09:06:04 +00:00
|
|
|
\fIDon't\fP use
|
|
|
|
.BR longjmp (3)
|
|
|
|
unless the program is going to terminate.
|
2006-05-24 05:15:12 +00:00
|
|
|
.SS nftw()
|
2007-05-12 09:06:04 +00:00
|
|
|
The function
|
|
|
|
.BR nftw ()
|
|
|
|
is the same as
|
|
|
|
.BR ftw (),
|
2006-05-24 05:15:12 +00:00
|
|
|
except that it has one additional argument, \fIflags\fP,
|
|
|
|
and calls \fIfn\fP() with one more argument, \fIftwbuf\fP.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
This \fIflags\fP argument is formed by ORing zero or more of the
|
2006-05-24 05:15:12 +00:00
|
|
|
following flags:
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2006-05-24 05:15:12 +00:00
|
|
|
.BR FTW_ACTIONRETVAL " (since glibc 2.3.3)"
|
|
|
|
If this glibc-specific flag is set, then
|
|
|
|
.BR nftw ()
|
2006-05-24 09:19:03 +00:00
|
|
|
handles the return value from
|
2006-05-24 05:15:12 +00:00
|
|
|
.IR fn ()
|
|
|
|
differently.
|
|
|
|
.IR fn ()
|
|
|
|
should return one of the following values:
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.B FTW_CONTINUE
|
2007-05-12 09:06:04 +00:00
|
|
|
Instructs
|
|
|
|
.BR nftw ()
|
|
|
|
to continue normally.
|
2006-05-24 05:15:12 +00:00
|
|
|
.TP
|
2006-05-24 06:09:24 +00:00
|
|
|
.B FTW_SKIP_SIBLINGS
|
|
|
|
If \fIfn\fP() returns this value, then
|
|
|
|
siblings of the current entry will be skipped,
|
|
|
|
and processing continues in the parent.
|
|
|
|
.\" If \fBFTW_DEPTH\fP
|
|
|
|
.\" is set, the entry's parent directory is processed next (with
|
|
|
|
.\" \fIflag\fP set to \fBFTW_DP\fP).
|
2006-05-24 05:15:12 +00:00
|
|
|
.TP
|
|
|
|
.B FTW_SKIP_SUBTREE
|
2007-04-12 22:42:49 +00:00
|
|
|
If \fIfn\fP() is called with an entry that is a directory
|
2006-05-24 05:15:12 +00:00
|
|
|
(\fItypeflag\fP is \fBFTW_D\fP), this return
|
|
|
|
value will prevent objects within that directory from being passed as
|
|
|
|
arguments to \fIfn\fP().
|
|
|
|
.BR nftw ()
|
|
|
|
continues processing with the next sibling of the directory.
|
|
|
|
.TP
|
2006-05-24 06:09:24 +00:00
|
|
|
.B FTW_STOP
|
2007-05-12 09:06:04 +00:00
|
|
|
Causes
|
|
|
|
.BR nftw ()
|
|
|
|
to return immediately with the return value
|
2006-05-24 06:09:24 +00:00
|
|
|
\fBFTW_STOP\fP.
|
2006-05-24 05:15:12 +00:00
|
|
|
.PP
|
2007-04-12 22:42:49 +00:00
|
|
|
Other return values could be associated with new actions in the future;
|
2006-05-24 05:15:12 +00:00
|
|
|
\fIfn\fP() should not return values other than those listed above.
|
|
|
|
|
2007-06-22 17:42:06 +00:00
|
|
|
The feature test macro
|
|
|
|
.B _GNU_SOURCE
|
2010-09-10 04:33:31 +00:00
|
|
|
must be defined
|
|
|
|
(before including
|
|
|
|
.I any
|
|
|
|
header files)
|
|
|
|
in order to
|
2006-05-24 05:15:12 +00:00
|
|
|
obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI<ftw.h>\fP.
|
|
|
|
.RE
|
2006-05-24 21:04:43 +00:00
|
|
|
.TP
|
|
|
|
.B FTW_CHDIR
|
|
|
|
If set, do a
|
|
|
|
.BR chdir (2)
|
|
|
|
to each directory before handling its contents.
|
|
|
|
This is useful if the program needs to perform some action
|
|
|
|
in the directory in which \fIfpath\fP resides.
|
|
|
|
.TP
|
|
|
|
.B FTW_DEPTH
|
|
|
|
If set, do a post-order traversal, that is, call \fIfn\fP() for
|
|
|
|
the directory itself \fIafter\fP handling the contents of the directory
|
|
|
|
and its subdirectories.
|
|
|
|
(By default, each directory is handled \fIbefore\fP its contents.)
|
|
|
|
.TP
|
|
|
|
.B FTW_MOUNT
|
2007-04-12 22:42:49 +00:00
|
|
|
If set, stay within the same file system
|
2006-05-26 21:46:17 +00:00
|
|
|
(i.e., do not cross mount points).
|
2006-05-24 21:04:43 +00:00
|
|
|
.TP
|
|
|
|
.B FTW_PHYS
|
|
|
|
If set, do not follow symbolic links.
|
|
|
|
(This is what you want.)
|
|
|
|
If not set, symbolic links are followed, but no file is reported twice.
|
|
|
|
.sp
|
2007-04-12 22:42:49 +00:00
|
|
|
If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set,
|
2006-05-24 21:04:43 +00:00
|
|
|
then the function
|
|
|
|
.IR fn ()
|
|
|
|
is never called for a directory that would be a descendant of itself.
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
2006-05-24 05:15:12 +00:00
|
|
|
For each entry in the directory tree,
|
|
|
|
.BR nftw ()
|
2007-04-12 22:42:49 +00:00
|
|
|
calls
|
2004-11-03 13:51:07 +00:00
|
|
|
.IR fn ()
|
2006-05-24 05:15:12 +00:00
|
|
|
with four arguments.
|
|
|
|
.I fpath
|
2007-04-12 22:42:49 +00:00
|
|
|
and
|
2006-05-24 05:15:12 +00:00
|
|
|
.I sb
|
2007-04-12 22:42:49 +00:00
|
|
|
are as for
|
2006-05-24 05:15:12 +00:00
|
|
|
.BR ftw ().
|
|
|
|
.I typeflag
|
|
|
|
may receive any of the same values as with
|
|
|
|
.BR ftw (),
|
|
|
|
or any of the following values:
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B FTW_DP
|
2006-05-24 05:15:12 +00:00
|
|
|
.I fpath
|
2007-04-12 22:42:49 +00:00
|
|
|
is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP.
|
2006-05-24 05:15:12 +00:00
|
|
|
All of the files
|
|
|
|
and subdirectories within \fIfpath\fP have been processed.
|
|
|
|
.TP
|
|
|
|
.B FTW_SL
|
|
|
|
.I fpath
|
|
|
|
is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP.
|
2007-07-02 03:04:27 +00:00
|
|
|
.\" To obtain the definition of this constant from
|
|
|
|
.\" .IR <ftw.h> ,
|
|
|
|
.\" either
|
|
|
|
.\" .B _BSD_SOURCE
|
|
|
|
.\" must be defined, or
|
|
|
|
.\" .BR _XOPEN_SOURCE
|
|
|
|
.\" must be defined with a value of 500 or more.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B FTW_SLN
|
2006-05-24 05:15:12 +00:00
|
|
|
.I fpath
|
|
|
|
is a symbolic link pointing to a nonexistent file.
|
2006-05-24 09:19:03 +00:00
|
|
|
(This occurs only if \fBFTW_PHYS\fP is not set.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
2006-05-24 05:15:12 +00:00
|
|
|
The fourth argument that
|
|
|
|
.BR nftw ()
|
2007-04-12 22:42:49 +00:00
|
|
|
supplies when calling
|
2006-05-24 05:15:12 +00:00
|
|
|
\fIfn\fP()
|
2006-05-24 09:19:03 +00:00
|
|
|
is a structure of type \fIFTW\fP:
|
2007-12-19 06:57:44 +00:00
|
|
|
.in +4n
|
2006-05-24 05:15:12 +00:00
|
|
|
.nf
|
|
|
|
|
|
|
|
struct FTW {
|
|
|
|
int base;
|
|
|
|
int level;
|
|
|
|
};
|
|
|
|
|
|
|
|
.fi
|
2007-12-19 05:53:30 +00:00
|
|
|
.in
|
2006-05-24 05:15:12 +00:00
|
|
|
.I base
|
2007-04-12 22:42:49 +00:00
|
|
|
is the offset of the filename (i.e., basename component)
|
|
|
|
in the pathname given in
|
2006-05-24 05:15:12 +00:00
|
|
|
.IR fpath .
|
2007-09-20 16:26:31 +00:00
|
|
|
.I level
|
2007-04-12 22:42:49 +00:00
|
|
|
is the depth of
|
2006-05-24 05:15:12 +00:00
|
|
|
.I fpath
|
|
|
|
in the directory tree, relative to the root of the tree
|
|
|
|
.RI ( dirpath ,
|
|
|
|
which has depth 0).
|
|
|
|
.SH "RETURN VALUE"
|
|
|
|
These functions return 0 on success, and \-1 if an error occurs.
|
|
|
|
|
intro.1, time.1, adjtimex.2, capget.2, eventfd.2, fcntl.2, getrlimit.2, getsockopt.2, gettimeofday.2, intro.2, ioctl_list.2, ioperm.2, mlock.2, pivot_root.2, poll.2, prctl.2, ptrace.2, sched_setscheduler.2, select_tut.2, semget.2, sigaltstack.2, signalfd.2, sysctl.2, timer_settime.2, timerfd_create.2, wait.2, CPU_SET.3, argz_add.3, assert_perror.3, atexit.3, backtrace.3, bcmp.3, clearenv.3, ctime.3, dl_iterate_phdr.3, dlopen.3, ecvt.3, errno.3, error.3, ether_aton.3, exit.3, fenv.3, ferror.3, finite.3, flockfile.3, fnmatch.3, fpathconf.3, fpclassify.3, ftime.3, ftok.3, ftw.3, fwide.3, getaddrinfo.3, gethostbyname.3, getlogin.3, getnameinfo.3, getnetent.3, getopt.3, getprotoent.3, getrpcent.3, getservent.3, glob.3, hsearch.3, inet.3, isalpha.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, longjmp.3, lsearch.3, malloc.3, matherr.3, mblen.3, mbsinit.3, mbtowc.3, on_exit.3, printf.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_attr_setdetachstate.3, pthread_attr_setguardsize.3, pthread_attr_setinheritsched.3, pthread_attr_setschedparam.3, pthread_attr_setschedpolicy.3, pthread_attr_setscope.3, pthread_attr_setstack.3, pthread_attr_setstackaddr.3, pthread_attr_setstacksize.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_equal.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_setaffinity_np.3, pthread_setcancelstate.3, pthread_setconcurrency.3, pthread_setschedparam.3, pthread_setschedprio.3, ptsname.3, putenv.3, putgrent.3, raise.3, rcmd.3, regex.3, rexec.3, rpc.3, rpmatch.3, rtnetlink.3, scandir.3, sem_init.3, setaliasent.3, setbuf.3, setenv.3, setjmp.3, signbit.3, stdio_ext.3, strtod.3, strtol.3, strtoul.3, system.3, termios.3, timeradd.3, tzset.3, ualarm.3, wctomb.3, xdr.3, st.4, tty_ioctl.4, core.5, elf.5, proc.5, bootparam.7, capabilities.7, icmp.7, ip.7, ipv6.7, math_error.7, mdoc.samples.7, mq_overview.7, pthreads.7, raw.7, regex.7, socket.7, tcp.7, tzselect.8: Global fix: s/non-zero/nonzero/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:40:55 +00:00
|
|
|
If \fIfn\fP() returns nonzero,
|
2006-05-24 05:15:12 +00:00
|
|
|
then the tree walk is terminated and the value returned by \fIfn\fP()
|
2007-05-12 09:06:04 +00:00
|
|
|
is returned as the result of
|
|
|
|
.BR ftw ()
|
|
|
|
or
|
|
|
|
.BR nftw ().
|
2006-05-24 05:15:12 +00:00
|
|
|
|
2007-05-12 09:06:04 +00:00
|
|
|
If
|
|
|
|
.BR nftw ()
|
|
|
|
is called with the \fBFTW_ACTIONRETVAL\fP flag,
|
intro.1, time.1, adjtimex.2, capget.2, eventfd.2, fcntl.2, getrlimit.2, getsockopt.2, gettimeofday.2, intro.2, ioctl_list.2, ioperm.2, mlock.2, pivot_root.2, poll.2, prctl.2, ptrace.2, sched_setscheduler.2, select_tut.2, semget.2, sigaltstack.2, signalfd.2, sysctl.2, timer_settime.2, timerfd_create.2, wait.2, CPU_SET.3, argz_add.3, assert_perror.3, atexit.3, backtrace.3, bcmp.3, clearenv.3, ctime.3, dl_iterate_phdr.3, dlopen.3, ecvt.3, errno.3, error.3, ether_aton.3, exit.3, fenv.3, ferror.3, finite.3, flockfile.3, fnmatch.3, fpathconf.3, fpclassify.3, ftime.3, ftok.3, ftw.3, fwide.3, getaddrinfo.3, gethostbyname.3, getlogin.3, getnameinfo.3, getnetent.3, getopt.3, getprotoent.3, getrpcent.3, getservent.3, glob.3, hsearch.3, inet.3, isalpha.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, longjmp.3, lsearch.3, malloc.3, matherr.3, mblen.3, mbsinit.3, mbtowc.3, on_exit.3, printf.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_attr_setdetachstate.3, pthread_attr_setguardsize.3, pthread_attr_setinheritsched.3, pthread_attr_setschedparam.3, pthread_attr_setschedpolicy.3, pthread_attr_setscope.3, pthread_attr_setstack.3, pthread_attr_setstackaddr.3, pthread_attr_setstacksize.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_equal.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_setaffinity_np.3, pthread_setcancelstate.3, pthread_setconcurrency.3, pthread_setschedparam.3, pthread_setschedprio.3, ptsname.3, putenv.3, putgrent.3, raise.3, rcmd.3, regex.3, rexec.3, rpc.3, rpmatch.3, rtnetlink.3, scandir.3, sem_init.3, setaliasent.3, setbuf.3, setenv.3, setjmp.3, signbit.3, stdio_ext.3, strtod.3, strtol.3, strtoul.3, system.3, termios.3, timeradd.3, tzset.3, ualarm.3, wctomb.3, xdr.3, st.4, tty_ioctl.4, core.5, elf.5, proc.5, bootparam.7, capabilities.7, icmp.7, ip.7, ipv6.7, math_error.7, mdoc.samples.7, mq_overview.7, pthreads.7, raw.7, regex.7, socket.7, tcp.7, tzselect.8: Global fix: s/non-zero/nonzero/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:40:55 +00:00
|
|
|
then the only nonzero value that should be used by \fIfn\fP()
|
2007-04-12 22:42:49 +00:00
|
|
|
to terminate the tree walk is \fBFTW_STOP\fP,
|
2007-05-12 09:06:04 +00:00
|
|
|
and that value is returned as the result of
|
|
|
|
.BR nftw ().
|
2007-05-19 04:30:20 +00:00
|
|
|
.SH "CONFORMING TO"
|
|
|
|
POSIX.1-2001, SVr4, SUSv1.
|
2008-08-06 12:09:11 +00:00
|
|
|
POSIX.1-2008 marks
|
|
|
|
.BR ftw ()
|
|
|
|
as obsolete.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NOTES
|
2010-06-10 01:43:28 +00:00
|
|
|
POSIX.1-2001 note that the results are unspecified if
|
|
|
|
.I fn
|
|
|
|
does not preserve the current working directory.
|
|
|
|
.PP
|
2004-11-03 13:51:07 +00:00
|
|
|
The function
|
2005-11-02 11:34:24 +00:00
|
|
|
.BR nftw ()
|
2006-05-25 06:24:07 +00:00
|
|
|
and the use of \fBFTW_SL\fP with
|
2005-11-02 11:34:24 +00:00
|
|
|
.BR ftw ()
|
2006-08-03 13:57:30 +00:00
|
|
|
were introduced in SUSv1.
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
|
|
|
On some systems
|
2005-11-02 11:34:24 +00:00
|
|
|
.BR ftw ()
|
2006-05-25 06:24:07 +00:00
|
|
|
will never use \fBFTW_SL\fP, on other systems \fBFTW_SL\fP occurs only
|
2004-11-03 13:51:07 +00:00
|
|
|
for symbolic links that do not point to an existing file,
|
|
|
|
and again on other systems
|
2005-11-02 11:34:24 +00:00
|
|
|
.BR ftw ()
|
2007-04-12 22:42:49 +00:00
|
|
|
will use \fBFTW_SL\fP for each symbolic link.
|
|
|
|
For predictable control, use
|
2005-11-02 11:34:24 +00:00
|
|
|
.BR nftw ().
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
|
|
|
Under Linux, libc4 and libc5 and glibc 2.0.6 will
|
2007-12-22 22:44:55 +00:00
|
|
|
use \fBFTW_F\fP for all objects (files, symbolic links, FIFOs, etc.)
|
2004-11-03 13:51:07 +00:00
|
|
|
that can be stat'ed but are not a directory.
|
2006-05-24 05:15:12 +00:00
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
The function
|
2005-11-02 11:34:24 +00:00
|
|
|
.BR nftw ()
|
2004-11-03 13:51:07 +00:00
|
|
|
is available since glibc 2.1.
|
2006-05-24 05:15:12 +00:00
|
|
|
|
2007-12-25 21:28:09 +00:00
|
|
|
\fBFTW_ACTIONRETVAL\fP is glibc-specific.
|
2006-05-24 05:15:12 +00:00
|
|
|
.SH EXAMPLE
|
2006-05-24 09:19:03 +00:00
|
|
|
The following program traverses the directory tree under the path named
|
|
|
|
in its first command-line argument, or under the current directory
|
2006-05-24 05:15:12 +00:00
|
|
|
if no argument is supplied.
|
|
|
|
It displays various information about each file.
|
2008-03-19 08:37:35 +00:00
|
|
|
The second command-line argument can be used to specify characters that
|
2007-04-12 22:42:49 +00:00
|
|
|
control the value assigned to the \fIflags\fP
|
2007-05-12 09:06:04 +00:00
|
|
|
argument when calling
|
|
|
|
.BR nftw ().
|
2006-05-24 05:15:12 +00:00
|
|
|
.nf
|
|
|
|
|
|
|
|
#define _XOPEN_SOURCE 500
|
|
|
|
#include <ftw.h>
|
|
|
|
#include <stdio.h>
|
|
|
|
#include <stdlib.h>
|
|
|
|
#include <string.h>
|
2007-07-26 17:03:33 +00:00
|
|
|
#include <stdint.h>
|
2006-05-24 05:15:12 +00:00
|
|
|
|
|
|
|
static int
|
2007-04-12 22:42:49 +00:00
|
|
|
display_info(const char *fpath, const struct stat *sb,
|
2006-05-24 05:15:12 +00:00
|
|
|
int tflag, struct FTW *ftwbuf)
|
|
|
|
{
|
2007-07-26 17:03:33 +00:00
|
|
|
printf("%\-3s %2d %7jd %\-40s %d %s\\n",
|
2006-05-24 05:19:08 +00:00
|
|
|
(tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" :
|
|
|
|
(tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ? "f" :
|
2007-07-19 20:29:21 +00:00
|
|
|
(tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" :
|
2006-05-24 05:15:12 +00:00
|
|
|
(tflag == FTW_SLN) ? "sln" : "???",
|
2007-07-26 17:03:33 +00:00
|
|
|
ftwbuf\->level, (intmax_t) sb\->st_size,
|
2007-06-20 21:39:45 +00:00
|
|
|
fpath, ftwbuf\->base, fpath + ftwbuf\->base);
|
2006-05-24 05:15:12 +00:00
|
|
|
return 0; /* To tell nftw() to continue */
|
|
|
|
}
|
|
|
|
|
|
|
|
int
|
|
|
|
main(int argc, char *argv[])
|
|
|
|
{
|
|
|
|
int flags = 0;
|
|
|
|
|
2008-06-09 15:49:35 +00:00
|
|
|
if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL)
|
2006-05-24 05:15:12 +00:00
|
|
|
flags |= FTW_DEPTH;
|
2008-06-09 15:49:35 +00:00
|
|
|
if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL)
|
2006-05-24 05:15:12 +00:00
|
|
|
flags |= FTW_PHYS;
|
|
|
|
|
2007-12-07 19:32:51 +00:00
|
|
|
if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags)
|
|
|
|
== \-1) {
|
|
|
|
perror("nftw");
|
2007-07-26 17:03:33 +00:00
|
|
|
exit(EXIT_FAILURE);
|
|
|
|
}
|
2006-05-24 05:15:12 +00:00
|
|
|
exit(EXIT_SUCCESS);
|
|
|
|
}
|
|
|
|
.fi
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
2006-05-22 23:06:10 +00:00
|
|
|
.BR stat (2),
|
2006-05-24 21:04:43 +00:00
|
|
|
.BR fts (3),
|
getresuid.2, intro.2, mremap.2, open.2, poll.2, posix_fadvise.2, pread.2, remap_file_pages.2, setresuid.2, signal.2, splice.2, sync_file_range.2, tee.2, vmsplice.2, INFINITY.3, asprintf.3, assert_perror.3, basename.3, bsd_signal.3, canonicalize_file_name.3, clog10.3, crypt.3, dl_iterate_phdr.3, dlopen.3, dprintf.3, encrypt.3, exp10.3, fcloseall.3, fenv.3, ffs.3, fmemopen.3, fopencookie.3, ftw.3, getdate.3, getline.3, getloadavg.3, getopt.3, getsubopt.3, getutent.3, grantpt.3, hsearch.3, intro.3, lseek64.3, memmem.3, mempcpy.3, mq_receive.3, mq_send.3, posix_fallocate.3, pow10.3, program_invocation_name.3, ptsname.3, putgrent.3, readdir.3, sigset.3, sincos.3, stpcpy.3, stpncpy.3, strchr.3, strfry.3, strnlen.3, strptime.3, strsignal.3, strstr.3, strverscmp.3, swab.3, sysv_signal.3, tsearch.3, unlocked_stdio.3, unlockpt.3, wcpcpy.3, wcpncpy.3, wcsdup.3, wcwidth.3: SEE ALSO: Remove redundant reference to feature_test_macros(7)
Reported-by: Florian Lehmann <flo.lehmann@googlemail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-10-31 05:05:22 +00:00
|
|
|
.BR readdir (3)
|