NOME

       ftw, nftw - caminha pela árvore de arquivos

SINOPSE

       #include <ftw.h>

       int  ftw  (const  char *dir, int (*fn)(const char *file, const struct stat *sb, int flag),
       int depth);

       int nftw (const char *dir, int (*fn)(const char *file, const struct stat  *sb,  int  flag,
       struct FTW *s), int depth, int flags);

DESCRIÇÃO

       ftw()  caminha  através  da árvore de diretório, começando do diretório dir indicado. Para
       cada entrada encontrada na árvore, ela chama fn() com o caminho de diretório  completo  da
       entrada, um ponteiro para a estrutura stat(2) da entrada, e um int, cujo valor será um dos
       seguintes:

       FTW_F  O item é um arquivo normal

       FTW_D  O item é um diretório

       FTW_DNR
              O item é um diretório que não pode ser lido

       FTW_SL O item é uma ligação simbólica

       FTW_NS

       Se o item é uma ligação simbólica e 'stat' falhou, XPG4v2 afirma que ele é  indefinido  se
       FTW_NS ou FTW_SL é usado.

       ftw()  chama recursivamente a si mesmo para atravessar diretórios encontrados, manipulando
       um diretório antes do seus arquivos ou subdiretórios.  Para  evitar  o  uso  de  todos  os
       descritores  de  arquivos  do  programa, o depth especifica o número de diretórios abertos
       simultaneamente.  Quando a profundidade é excedida, ftw() se tornará mais lenta porque  os
       diretórios  têm que ser fechados e reabertos. ftw() usa no máximo um descritor de arquivos
       para cada nível na hierarquia de arquivos.

       Para parar a caminhada na árvore, fn() retorna um valor diferente de zero; este  valor  se
       tornará  o  valor  de  retorno  de  ftw().  Caso contrário, ftw() 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 malloc(3) ), em cujo caso retornará -1.

       Como  ftw()  usa  estruturas  de  dados  dinâmicas,  a única maneira segura de sair de uma
       caminhada na árvore é retornar um valor diferente de zero.  Para  manipular  interrupções,
       por  exemplo,  indica  que a interrupção ocorreu e retorna um valor diferente de zero —não
       use longjmp(3) a menos que o programa vá terminar.

       A função nftw() faz precisamente a mesma coisa que ftw(), exceto pelo fato de que ela  tem
       um  argumento  adicional,  flags (e chama a função fornecida com mais um argumento).  Este
       argumento flags é uma operação OU de zero ou mais das seguintes flags:

       FTW_CHDIR
              Se setado, faz um chdir() para cada diretório antes de manipular seu conteúdo.

       FTW_DEPTH
              Se setado, faz uma busca primeiro por profundidade, ou seja, chama a função para  o
              próprio  diretório  somente  depois  de  manipular os conteúdos do diretório e seus
              subdiretórios.

       FTW_MOUNT
              Se setado, fica dentro do mesmo sistema de arquivos.

       FTW_PHYS
              Se setado, não segue ligações simbólicas.  (Isto  é  o  que  você  quer.)   Se  não
              setado,  as  ligações  simbólicas  são seguidas, mas nenhum arquivo é relatado duas
              vezes.

       Se FTW_PHYS não é setado, mas FTW_DEPTH é setado, então a função fn() nunca é chamada para
       um diretório que seria um descendente dele mesmo.

       A função fn() é chamada com quatro argumentos: o caminho de diretório 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

       FTW_DP O item é um diretório e todos os seus  descendentes  já  foram  manipulados.  (Isto
              ocorre somente com FTW_DEPTH setado.)

       FTW_SLN
              O  item  é  uma  ligação  simbólica apontando para um arquivo não existente.  (Isto
              ocorre somente com FTW_PHYS não setado.)

       A estrutura FTW apontada pelo quarto argumento para fn() tem pelo menos os campos base,  o
       offset  do nome de arquivo do item no caminho de diretório dado como primeiro argumento de
       fn(), e level, a profundidade do item em relação ao ponto inicial  (que  tem  profundidade
       0).

NOTAS

       A  função  nftw()  e  o  uso de FTW_SL com ftw() foram introduzidos em XPG4v2.  Sob Linux,
       libc4, libc5 e glibc  2.0.6  usarão  FTW_F  para  todos  os  objetos  (arquivos,  ligações
       simbólicas,  fifos,  etc)  que  podem  ser  receber  um  'stat' mas não são diretórios.  A
       primeira glibc 2.1 suporta FTW_SL e nftw().

CONFORME

       AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4v2.

VEJA TAMBÉM

       stat(2)

TRADUÇÃO PARA A LÍNGUA PORTUGUESA

       RUBENS  DE  JESUS  NOGUEIRA  <darkseid99@usa.net>  (tradução)  XXXXXX  XX  XXXXX  XXXXXXXX
       <xxxxxxxxxx@xxx.xxx> (revisão)