.\" Copyright (c) 1993 Michael Haardt (michael@moria.de)
.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
.\" Fri Jun 25 00:34:07 CEST 1999
.\"
.\" 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)
.TH FTW 3 "25 de junho de 1999" "Linux" "Manual do Programador Linux"
.SH NOME
ftw, nftw \- caminha pela rvore de arquivos
.SH SINOPSE
.B #include <ftw.h>
.sp
.BI "int ftw (const char *" dir ", int (*" fn ")(const"
.BI "char *" file ", const struct stat *" sb ", int " flag ),
.BI "int " depth );
.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 " depth ", int " flags );
.SH DESCRIO
\fBftw\fP() caminha atravs da rvore de diretrio, comeando do diretrio
\fIdir\fP indicado. Para cada entrada encontrada na rvore, ela chama
\fIfn\fP() com o caminho de diretrio completo da entrada, um ponteiro para a estrutura
.BR stat (2)
da entrada, e um int, cujo valor ser um dos seguintes:
.TP
.B FTW_F
O item  um arquivo normal
.TP
.B FTW_D
O item  um diretrio
.TP
.B FTW_DNR
O item  um diretrio que no pode ser lido
.TP
.B FTW_SL
O item  uma ligao simblica
.TP
.B FTW_NS
'stat' falhou no item que no  uma ligao simblica
.LP
Se o item  uma ligao simblica e 'stat' falhou, XPG4v2 afirma que ele  indefinido se
FTW_NS ou FTW_SL  usado.
.PP
\fBftw\fP() chama recursivamente a si mesmo para atravessar diretrios encontrados, manipulando
um diretrio antes do seus arquivos ou subdiretrios. Para evitar o uso de todos os descritores 
de arquivos do programa, o \fIdepth\fP especifica o nmero de diretrios abertos simultaneamente.
Quando a profundidade  excedida, \fBftw\fP() se tornar mais lenta porque os diretrios tm que
ser fechados e reabertos. \fBftw\fP() usa no mximo um descritor de arquivos para cada nvel na 
hierarquia de arquivos.
.PP
Para parar a caminhada na rvore, \fIfn\fP() retorna um valor diferente de zero; este valor se
tornar o valor de retorno de \fBftw\fP(). Caso contrrio, \fBftw\fP() continuar at que tenha
atravessado a rvore inteira, em cujo caso retornar zero, ou at que ele encontre um erro 
diferente de EACCES (tal como uma falha de
.BR malloc (3)
), em cujo caso retornar \-1.
.PP
Como \fBftw()\fP usa estruturas de dados dinmicas, a nica maneira segura de sair de uma caminhada
na rvore  retornar um valor diferente de zero. Para manipular interrupes, por exemplo, indica que
a interrupo ocorreu e retorna um valor diferente de zero \(emno use
.BR longjmp (3)
a menos que o programa v terminar.

A funo \fBnftw\fP() faz precisamente a mesma coisa que \fBftw\fP(), exceto pelo fato de que 
ela tem um argumento adicional, \fIflags\fP (e chama a funo fornecida com mais um argumento).
Este argumento \fIflags\fP  uma operao OU de zero ou mais das seguintes flags:
.TP
.B FTW_CHDIR
Se setado, faz um
.IR chdir ()
para cada diretrio antes de manipular seu contedo.
.TP
.B FTW_DEPTH
Se setado, faz uma busca primeiro por profundidade, ou seja, chama a funo para o prprio diretrio
somente depois de manipular os contedos do diretrio e seus subdiretrios.
.TP
.B FTW_MOUNT
Se setado, fica dentro do mesmo sistema de arquivos.
.TP
.B FTW_PHYS
Se setado, no segue ligaes simblicas.
(Isto  o que voc quer.)
Se no setado, as ligaes simblicas so seguidas, mas nenhum arquivo  relatado duas vezes.
.LP
Se FTW_PHYS no  setado, mas FTW_DEPTH  setado, ento a funo
.IR fn ()
nunca  chamada para um diretrio que seria um descendente dele mesmo.
.LP
A funo
.IR fn ()
 chamada com quatro argumentos: o caminho de diretrio da entrada relatada, um ponteiro para uma
estrutura 'stat' desta entrada, um inteiro descrevendo seu tipo, e um ponteiro para uma estrutura
FTW. O tipo ser um dos seguintes: FTW_F, FTW_D, FTW_DNR, FTW_SL, FTW_NS ( com o significado acima;
FTW_SL ocorre somente com FTW_PHYS setado) ou
.TP
.B FTW_DP
O item  um diretrio e todos os seus descendentes j foram manipulados. (Isto ocorre
somente com FTW_DEPTH setado.)
.TP
.B FTW_SLN
O item  uma ligao simblica apontando para um arquivo no existente.
(Isto ocorre somente com FTW_PHYS no setado.)
.LP
A estrutura FTW apontada pelo quarto argumento para
.IR fn ()
tem pelo menos os campos
.IR base ,
o offset do nome de arquivo do item no caminho de diretrio dado como primeiro argumento de
.IR fn (),
e
.IR level ,
a profundidade do item em relao ao ponto inicial
(que tem profundidade 0).
.SH NOTAS
A funo
.IR nftw ()
e o uso de FTW_SL com
.IR ftw ()
foram introduzidos em XPG4v2.
Sob Linux, libc4, libc5 e glibc 2.0.6 usaro
FTW_F para todos os objetos (arquivos, ligaes simblicas, fifos, etc)
que podem ser receber um 'stat' mas no so diretrios.
A primeira glibc 2.1 suporta FTW_SL e
.IR nftw ().
.SH "CONFORME"
AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4v2.
.SH "VEJA TAMBM"
.BR stat (2)

.SH TRADUO PARA A LNGUA PORTUGUESA
\&\fR\&\f(CWRUBENS DE JESUS NOGUEIRA <darkseid99@usa.net> (traduo)\fR
\&\fR\&\f(CWXXXXXX XX XXXXX XXXXXXXX <xxxxxxxxxx@xxx.xxx> (reviso)\fR