Provided by: manpages-pt-dev_20040726-4_all bug

NOME

     fts, fts_open, fts_read, fts_children, fts_set, fts_close -- atravessa
     uma hierarquia de arquivos

SINOPSE

     #include <sys/types.h>
     #include <sys/stat.h>
     #include <fts.h>
     FTS * fts_open(char * const *path_argv, int options, int (*compar)(const
     FTSENT **, const FTSENT **)) FTSENT * fts_read(FTS *ftsp) FTSENT *
     fts_children(FTS *ftsp, int options) int fts_set(FTS *ftsp, FTSENT *f,
     int options) int fts_close(FTS *ftsp)

DESCRI,C~AO

     As funcoes fts sao fornecidas para a travessia de hierarquias de arquivos
     UNIX. Uma visao geral simples e que a funcao fts_open() retorna um
     ''manipulador'' em uma hierarquia de arquivo, que e entao fornecida para
     as outras funcoes fts. A funcao fts_read() retorna um ponteiro para uma
     estrutura que descreve um dos arquivos na hierarquia de arquivos.  A
     funcao fts_children() retorna um ponteiro para uma lista ligada de
     estruturas, cada uma das quais descreve um dos arquivos contidos em um
     diretorio na hierarquia.  Em geral, diretorios sao visitados em dois
     momentos distinguiveis: em pre-ordem (antes que qualquer um dos seus
     descendentes sejam visitados) e em pos-ordem (depois que todos os seus
     descendentes foram visitados).  Arquivos sao visitados uma vez.  E
     possivel caminhar pela hierarquia ''logicamente'' (ignorando ligacoes
     simbolicas) ou fisicamente (visitando ligacoes simbolicas), ordenar o
     caminho da hierarquia ou podar e/ou re-visitar porcoes da hierarquia.

     Duas estruturas sao definidas (inclusive via 'typedef') no arquivo de
     inclusao <fts.h>.  A primeira e FTS, a estrutura que representa a propria
     hierarquia de arquivo. A segunda e FTSENT, a estrutura que representa um
     arquivo em uma hierarquia de arquivos.  Normalmente, uma estrutura FTSENT
     e retornada para qualquer arquivo na hierarquia.  Nesta pagina de manual,
     ''file'' e ``FTSENT structure'' geralmente sao intercambiaveis.  A
     estrutura FTSENT contem pelo menos os seguintes campos, que sao descritos
     em maiores detalhes abaixo:

     typedef struct _ftsent {
             u_short fts_info;               /* flags para a estrutura FTSENT */
             char *fts_accpath;              /* caminho de acesso */
             char *fts_path;                 /* caminho raiz */
             short fts_pathlen;              /* strlen(fts_path) */
             char *fts_name;                 /* nome do arquivo */
             short fts_namelen;              /* strlen(fts_name) */
             short fts_level;                /* profundidade (-1 a N) */
             int fts_errno;                  /* errno do arquivo */
             long fts_number;                /* valor numerico local */
             void *fts_pointer;              /* valor do endereco local */
             struct ftsent *fts_parent;      /* diretorio pai */
             struct ftsent *fts_link;        /* estrutura do proximo arquivo */
             struct ftsent *fts_cycle;       /* estrutura de ciclo */
             struct stat *fts_statp;         /* informacao de stat(2) */
     } FTSENT;

     Estes campos sao definidos como segue:

     fts_info     Uma das seguintes flags que descrevem a estrutura FTSENT
                  retornada, e o arquivo que ela representa.  Com excecao dos
                  diretorios sem erros (FTS_D), todas estas entradas sao
                  terminais, ou seja, elas nao serao re-visitadas, nem
                  qualquer dos seus descendentes serao visitados.

                  FTS_D        Um diretorio sendo visitado em pre-ordem.

                  FTS_DC       Um diretorio que causa um ciclo na arvore.  (O
                               campo fts_cycle da estrutura FTSENT sera
                               preenchida tambem.)

                  FTS_DEFAULT  Qualquer estrutura FTSENT que representa um
                               tipo de arquivo nao descrito explicitamente por
                               um dos outros valores fts_info.

                  FTS_DNR      Um diretorio que nao pode ser lido. Este e um
                               retorno de erro, e o campo fts_errno sera
                               setado para indicar o que causou o erro.

                  FTS_DOT      Um arquivo denominado '.' ou '..' que nao foi
                               especificado como um nome de arquivo para
                               fts_open() (veja FTS_SEEDOT).

                  FTS_DP       Um diretorio sendo visitado em pos-ordem.  Os
                               conteudos da estrutura FTSENT serao imutaveis a
                               partir de quando ele foi retornado em
                               pre-ordem, isto e, com o campo fts_info setado
                               em FTS_D.

                  FTS_ERR      Este e um retorno de erro, e o campo fts_errno
                               sera setado para indicar o que causou o erro.

                  FTS_F        Um arquivo regular.

                  FTS_NS       Um arquivo para o qual nenhuma informacao
                               stat(2) estava disponivel.  O conteudo do campo
                               fts_statp e indefinido.  Este e um retorno de
                               erro, e o campo fts_errno sera setado para
                               indicar o que causou o erro.

                  FTS_NSOK     Um arquivo para o qual nenhuma informacao
                               stat(2) foi requisitada.  O conteudo do campo
                               fts_statp e indefinido.

                  FTS_SL       Uma ligacao simbolica.

                  FTS_SLNONE   Uma ligacao simbolica com um alvo nao-
                               existente.  O conteudo do campo fts_statp
                               referencia a informacao caracteristica do
                               arquivo para a propria ligacao simbolica.

     fts_accpath  Um caminho para acessar o arquivo a partir do diretorio
                  corrente.

     fts_path     O caminho para o arquivo em relacao a raiz da travessia.
                  Este caminho e aquele especificado para fts_open() como um
                  prefixo.

     fts_pathlen  O comprimento da string referenciada por fts_path.

     fts_name     O nome do arquivo.

     fts_namelen  O comprimento da string referenciada por fts_name.

     fts_level    A profundidade da travessia, numerado de -1 a N, onde este
                  arquivo foi encontrado.  A estrutura FTSENT que representa o
                  pai do ponto inicial (ou raiz) da travessia e numerada com
                  -1, e a estrutura FTSENT para a propria raiz e numerada com
                  0.

     fts_errno    Ao retornar de uma estrutura FTSENT das funcoes
                  fts_children() ou fts_read() , com seus campos fts_info
                  setados para FTS_DNR, FTS_ERR ou FTS_NS, o campo fts_errno
                  contem o valor da variavel externa errno especificando a
                  causa do erro. Caso contrario, o conteudo do campo fts_errno
                  e indefinido.

     fts_number   Este campo e fornecido para o uso do programa de aplicacao e
                  nao e modificado pelas funcoes fts. E inicializado com 0.

     fts_pointer  Este campo e fornecido para o uso de programas aplicativos e
                  nao e modificado pelas funcoes fts. Ele e inicializado com
                  NULL.

     fts_parent   Um ponteiro para uma estrutura FTSENT que referencia o
                  arquivo na hierarquia imediatamente acima do arquivo
                  corrente, isto e, o diretorio do qual este arquivo e membro.
                  Uma estrutura-pai para o ponto de entrada inicial tambem e
                  fornecido, porem somente os campos fts_level, fts_number e
                  fts_pointer sao garantidamente inicializados.

     fts_link     Ao retornar da funcao fts_children() , o campo fts_link
                  aponta para a proxima estrutura na lista ligada terminada em
                  NULL dos membros do diretorio. Caso contrario, o conteudo do
                  campo fts_link e indefinido.

     fts_cycle    Se um diretorio produz um ciclo na hierarquia (veja FTS_DC)
                  por causa de uma ligacao solida entre dois diretorios ou por
                  causa de uma ligacao simbolica apontando para um diretorio,
                  o campo fts_cycle da estrutura apontara para a estrutura
                  FTSENT na hierarquia que referencia o mesmo arquivo que a
                  estrutura FTSENT corrente. Caso contrario, o conteudo do
                  campo fts_cycle e indefinido.

     fts_statp    Um ponteiro para informacoes stat(2) para o arquivo.

     Um buffer simples e usado para todos os caminhos de todos os arquivos na
     hierarquia de arquivos.  Portanto, os campos fts_path e fts_accpath sao
     garantidamente terminados em NULLsomente no arquivo retornado mais
     recentemente por fts_read().  Para usar estes campos para referenciar
     qualquer arquivo representado por outras estruturas FTSENT, sera
     necessario que o buffer de caminho seja modificado usando informacoes
     contidas no campo information contained in that fts_pathlen daquela
     estrutura FTSENT. Quaisquer modificacoes deste tipo devem ser desfeitas
     antes que chamadas adicionais a fts_read() sejam tentadas.  O campo
     fts_name e sempre terminado em NULL Ns.

FTS_OPEN

     A funcao fts_open() pega um ponteiro para uma matriz de ponteiros de
     caracteres, que nomeia um ou mais caminhos criando uma hierarquia logica
     de arquivos a ser atravessada.  A matriz precisa ser terminada com um
     ponteiro NULL.

     Ha um grande numero de opcoes, pelo menos uma das quais ( FTS_LOGICAL ou
     FTS_PHYSICAL) precisa ser especificada.  As opcoes sao selecionadas ou
     est~ao selecionando pelos seguintes valores:

     FTS_COMFOLLOW
                   Esta opcao faz com que qualquer ligacao simbolica
                   especificada como um caminho raiz seja seguido
                   imediatamente, ou nao, se FTS_LOGICAL e especificado
                   tambem.

     FTS_LOGICAL   Esta opcao faz com que as rotinas fts retornem estruturas
                   FTSENT para os alvos das ligacoes simbolicas, em vez das
                   proprias ligacoes.  Se esta opcao e setada, as unicas
                   ligacoes simbolicas para que as estruturas FTSENT sejam
                   retornadas para a aplicacao sao aquelas que referenciam
                   arquivos nao existentes.  Tanto FTS_LOGICAL quanto
                   FTS_PHYSICAL precisam ser fornecidos para a funcao
                   fts_open.()

     FTS_NOCHDIR   Como uma otimizacao de performance, as funcoes fts mudam
                   diretorios conforme eles caminham na hierarquia de
                   arquivos.  Isto tem um efeito colateral de que um
                   aplicativo nao pode confiar em ser um diretorio particular
                   qualquer durante a travessia.  A opcao FTS_NOCHDIR desativa
                   esta otimizacao, e as funcoes fts nao mudarao o diretorio
                   corrente.  Note que os aplicativos nao devem, por eles
                   proprios, alterar seus diretorios correntes e tentar
                   acessar arquivos a menos que FTS_NOCHDIR seja especificado
                   e os caminhos de arquivos absolutos foram fornecidos como
                   argumentos para fts_open().

     FTS_NOSTAT    Por padrao, estruturas FTSENT retornadas referenciam
                   informacoes caracteristicas de arquivo ( o campo statp )
                   para cadas arquivo visitado.  Esta opcao relaxa aqueles
                   requisitos como uma otimizacao de performance, permitindo
                   que as funcoes fts setem o campo fts_info para FTS_NSOK e
                   deixem o conteudo do campo statp indefinido.

     FTS_PHYSICAL  Esta rotina faz com que as rotinas fts retornem estruturas
                   FTSENT para as proprias ligacoes simbolicas, em vez dos
                   arquivos-alvo para os quais eles apontam.  Se esta opcao e
                   setada, as estruturas FTSENT para todas as ligacoes
                   simbolicas na hierarquia sao retornadas para o aplicativo.
                   FTS_LOGICAL ou FTS_PHYSICAL deve ser fornecido para a
                   funcao fts_open.()

     FTS_SEEDOT    Por padrao, a menos que sejam especificados como argumentos
                   de caminho para fts_open(), quaisquer arquivos com nome '.'
                   ou '..' encontrados na hierarquia de arquivos sao
                   ignorados.  Esta opcao faz com que as rotinas fts retornem
                   FTSENT para eles.

     FTS_XDEV      Esta opcao evita que fts desca para diretorios que tenham
                   um numero de dispositivo diferente do arquivo da qual o
                   descendente comeca.

     O argumento compar() especifica uma funcao definida pelo usuario que pode
     ser usada para ordenar a travessia da hierarquia.  Ele pega dois
     ponteiros de ponteiros para estruturas FTSENT como a argumentos e deve
     retornar um valor negativo, zero ou um valor positivo para indicar se o
     arquivo referenciado pelo seu primeiro argumento vem antes, em qualquer
     ordem, ou depois do arquivo referenciado pelo seu segundo argumento.  Os
     campos fts_accpath, fts_path e fts_pathlen das estruturas FTSENT nunca
     podem ser usados nesta comparacao.  Se o campo fts_info e setado para
     FTS_NS ou FTS_NSOK, o campo fts_statp nao pode ser usado.  Se o argumento
     compar() e NULL, a ordem de travessia do diretorio esta na ordem listada
     em path_argv para os caminhos da raiz, e na ordem listada no diretorio
     para todos os demais.

FTS_READ

     A funcao fts_read() retorna um ponteiro para uma estrutura FTSENT
     descrevendo um arquivo na hierarquia.  Diretorios (que sao legiveis e nao
     causam ciclos) sao visitados pelos menos duas vezes, uma vez em pre-ordem
     e uma vez em pos-ordem.  Todos os outros arquivos sao visitados pelo
     menos uma vez.  (Ligacoes fixas entre diretorios que nao provocam ciclos,
     ou ligacoes simbolicas para ligacoes simbolicas podem fazer com que
     arquivos sejam visitados mais de uma vez, ou diretorios sejam visitados
     mais de duas vezes.)

     Se todos os membros da hierarquia foram retornados, fts_read() retorna
     NULL e seta a variavel externa errno para 0.  Se ocorre um erro nao
     relacionado a um arquivo na hierarquia, fts_read() retorna NULL e seta
     errno adequadamente.  Se ocorre um erro relacionado a um arquivo
     retornado, e retornado um ponteiro para uma estrutura FTSENT , e errno
     pode ou nao ter sido setado (veja fts_info).

     As estruturas FTSENT retornadas por fts_read() podem ser sobreescritas
     depois de uma chamada a fts_close() no mesmo fluxo de hierarquia de
     arquivo, ou, depois de uma chamada a fts_read() no mesmo fluxo de
     hierarquia de arquivo, a menos que eles representem um arquivo do tipo
     diretorio, em cujo caso eles nao serao sobreescritos ate que seja feita
     uma chamada a fts_read() depois que uma estrutura FTSENT tenha sido
     retornada pela funcao fts_read() em pos-ordem.

FTS_CHILDREN

     A funcao fts_children() retorna um ponteiro para uma estrutura FTSENT
     descrevendo a primeira entrada em uma lista ligada, terminada em NULL,
     dos arquivos no diretorio representado pela estrutura FTSENT mais
     recentemente retornada por fts_read().  A lista e ligada atraves do campo
     fts_link da estrutura FTSENT , e e ordenada pela funcao de comparacao
     especificada pelo usuario, se houver.  Chamadas repetidas a
     fts_children() recriara esta lista ligada.

     Como um caso especial, se fts_read() ainda nao foi chamado para uma
     hierarquia, fts_children() retornara um ponteiro para os arquivos no
     diretorio logico especificado para fts_open(), isto e, os argumentos
     especificados para fts_open().  Caso contrario, se a estrutura FTSENT
     retornada mais recentemente por fts_read() nao e um diretorio sendo
     visitado em pre-ordem, ou o diretorio nao contem nenhum arquivo,
     fts_children() retorna NULL e seta errno para zero.  Se ocorre um erro,
     fts_children() retorna NULL e seta errno adequadamente.

     As estruturas FTSENT retornadas por fts_children() podem ser
     sobreescritas depois de uma chamada a fts_children(), fts_close() ou
     fts_read() no mesmo fluxo de hierarquia de arquivos.

     Option pode ser setado para os seguintes valores:

     FTS_NAMEONLY  Somente os nomes dos arquivos sao necessarios.  Os
                   conteudos de todos os campos na lista ligada de estruturas
                   retornada sao indefinidas com excecao dos campos fts_name e
                   fts_namelen.

FTS_SET

     A funcao fts_set() permite que a aplicacao do usuario determine um
     processamento adicional para o arquivo f do fluxo ftsp.  A funcao
     fts_set() retorna 0 em caso de sucesso, e -1 se ocorre um erro.  Option
     precisa ser setado para um dos seguintes valores:

     FTS_AGAIN     Revisita o arquivo; qualquer tipo de arquivo pode ser
                   revisitado.  A proxima chamada a fts_read() retornara o
                   arquivo referenciado.  Os campos fts_stat e fts_info da
                   estrutura serao reiniciados naquele momento, mas nenhum
                   outro campo sera alterado.  Esta opcao e significativa
                   somente para o arquivo mais recentemente retornado de
                   fts_read().  Uso normal e para visitas a diretorios em pos-
                   ordem, onde faz com que o diretorio seja revisitado (tanto
                   em pre-ordem quanto em pos-ordem) junto com todos os seus
                   descendentes.

     FTS_FOLLOW    O arquivo referenciado precisa ser uma ligacao simbolica.
                   Se o arquivo referenciado e o mais recentemente retornado
                   por fts_read(), a proxima chamada a fts_read() retorna o
                   arquivo com os campos fts_info e fts_statp reinicializados
                   para refletir o alvo das ligacoes simbolicas em vez da
                   propria ligacao simbolica.  Se o arquivo e um daqueles mais
                   recentemente retornados por fts_children(), os campos
                   fts_info e fts_statp da estrutura, quando retornados por
                   fts_read(), refletirao o alvo da ligacao simbolica em vez
                   da propria ligacao simbolica.  Neste caso, se o alvo da
                   ligacao simbolica nao existe, os campos da estrutura
                   retornada nao serao alterados e o campo fts_info sera
                   setado para FTS_SLNONE.

                   Se o alvo da ligacao e um diretorio, e feito um retorno de
                   pre-ordem, seguido pelo retorno de todos os seus
                   descendentes, seguido por um retorno de pos-ordem.

     FTS_SKIP      Nenhum descendente deste arquivo e visitado.  O arquivo
                   pode ser um daqueles mais recentemente retornados por
                   fts_children() ou fts_read().

FTS_CLOSE

     A funcao fts_close() fecha um fluxo de hierarquia de arquivo ftsp e
     recupera o diretorio corrente para o diretorio do qual fts_open() foi
     chamado para abrir ftsp.  A funcao fts_close() retorna 0 em caso de
     sucesso, e -1 se ocorre um erro.

ERROS

     A funcao fts_open() pode falhar e setar errno para qualquer um dos erros
     especificados para as funcoes de biblioteca open(2) e malloc(3).

     A funcao fts_close() pode falhar e setar errno para qualquer um dos erros
     especificados para as funcoes de biblioteca chdir(2) e close(2).

     As funcoes fts_read() e fts_children() podem falhar e setar errno para
     qualquer um dos erros especificados para as funcoes de biblioteca
     chdir(2), malloc(3), opendir(3), readdir(3) e stat(2).

     Alem disso, fts_children(), fts_open() e fts_set() podem falhar e setar
     errno como segue:

     [EINVAL]           As opcoes eram invalidas.

VEJA TAMB'EM

     find(1), chdir(2), stat(2), qsort(3)

PADR~OES

     BSD 4.4. Espera-se que o utilitario fts seja incluido em uma futura
     revisao de

DISPONIBILIDADE

     Estas funcoes estao disponiveis em Linux desde a glibc2 (libc6).  RUBENS
     DE JESUS NOGUEIRA <darkseid99@usa.net> (traducao) XXXXXX XX XXXXX
     XXXXXXXX <xxxxxxxxxx@xxx.xxx> (revisao)