Provided by: manpages-pt-dev_20040726-2_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ÇÃO

     As funções fts são fornecidas para a travessia de hierarquias de arquivos
     UNIX. Uma visão geral simples é que a função fts_open() retorna um
     ’’manipulador’’ em uma hierarquia de arquivo, que é então fornecida para
     as outras funções fts. A função fts_read() retorna um ponteiro para uma
     estrutura que descreve um dos arquivos na hierarquia de arquivos.  A
     função fts_children() retorna um ponteiro para uma lista ligada de
     estruturas, cada uma das quais descreve um dos arquivos contidos em um
     diretório na hierarquia.  Em geral, diretórios são visitados em dois
     momentos distinguíveis: em pré-ordem (antes que qualquer um dos seus
     descendentes sejam visitados) e em pós-ordem (depois que todos os seus
     descendentes foram visitados).  Arquivos são visitados uma vez.  É
     possível caminhar pela hierarquia ’’logicamente’’ (ignorando ligações
     simbólicas) ou fisicamente (visitando ligações simbólicas), ordenar o
     caminho da hierarquia ou podar e/ou re-visitar porções da hierarquia.

     Duas estruturas são definidas (inclusive via ’typedef’) no arquivo de
     inclusão 〈fts.h〉.  A primeira é FTS, a estrutura que representa a própria
     hierarquia de arquivo. A segunda é FTSENT, a estrutura que representa um
     arquivo em uma hierarquia de arquivos.  Normalmente, uma estrutura FTSENT
     é retornada para qualquer arquivo na hierarquia.  Nesta página de manual,
     ’’file’’ e “FTSENT structure” geralmente são intercambiáveis.  A
     estrutura FTSENT contém pelo menos os seguintes campos, que são 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 numérico local */
             void *fts_pointer;              /* valor do endereço local */
             struct ftsent *fts_parent;      /* diretório pai */
             struct ftsent *fts_link;        /* estrutura do próximo arquivo */
             struct ftsent *fts_cycle;       /* estrutura de ciclo */
             struct stat *fts_statp;         /* informação de stat(2) */
     } FTSENT;

     Estes campos são definidos como segue:

     fts_info     Uma das seguintes flags que descrevem a estrutura FTSENT
                  retornada, e o arquivo que ela representa.  Com exceção dos
                  diretórios sem erros (FTS_D), todas estas entradas são
                  terminais, ou seja, elas não serão re-visitadas, nem
                  qualquer dos seus descendentes serão visitados.

                  FTS_D        Um diretório sendo visitado em pré-ordem.

                  FTS_DC       Um diretório que causa um ciclo na árvore.  (O
                               campo fts_cycle da estrutura FTSENT será
                               preenchida também.)

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

                  FTS_DNR      Um diretório que não pode ser lido. Este é um
                               retorno de erro, e o campo fts_errno será
                               setado para indicar o que causou o erro.

                  FTS_DOT      Um arquivo denominado ‘.’ ou ‘..’ que não foi
                               especificado como um nome de arquivo para
                               fts_open() (veja FTS_SEEDOT).

                  FTS_DP       Um diretório sendo visitado em pós-ordem.  Os
                               conteúdos da estrutura FTSENT serão imutáveis a
                               partir de quando ele foi retornado em
                               pré-ordem, isto é, com o campo fts_info setado
                               em FTS_D.

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

                  FTS_F        Um arquivo regular.

                  FTS_NS       Um arquivo para o qual nenhuma informação
                               stat(2) estava disponível.  O conteúdo do campo
                               fts_statp é indefinido.  Este é um retorno de
                               erro, e o campo fts_errno será setado para
                               indicar o que causou o erro.

                  FTS_NSOK     Um arquivo para o qual nenhuma informação
                               stat(2) foi requisitada.  O conteúdo do campo
                               fts_statp é indefinido.

                  FTS_SL       Uma ligação simbólica.

                  FTS_SLNONE   Uma ligação simbólica com um alvo não-
                               existente.  O conteúdo do campo fts_statp
                               referencia a informação característica do
                               arquivo para a própria ligação simbólica.

     fts_accpath  Um caminho para acessar o arquivo a partir do diretório
                  corrente.

     fts_path     O caminho para o arquivo em relação à raiz da travessia.
                  Este caminho é 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 é numerada com
                  -1, e a estrutura FTSENT para a própria raiz é numerada com
                  0.

     fts_errno    Ao retornar de uma estrutura FTSENT das funções
                  fts_children() ou fts_read() , com seus campos fts_info
                  setados para FTS_DNR, FTS_ERR ou FTS_NS, o campo fts_errno
                  contém o valor da variável externa errno especificando a
                  causa do erro. Caso contrário, o conteúdo do campo fts_errno
                  é indefinido.

     fts_number   Este campo é fornecido para o uso do programa de aplicação e
                  não é modificado pelas funções fts. É inicializado com 0.

     fts_pointer  Este campo é fornecido para o uso de programas aplicativos e
                  não é modificado pelas funções fts. Ele é inicializado com
                  NULL.

     fts_parent   Um ponteiro para uma estrutura FTSENT que referencia o
                  arquivo na hierarquia imediatamente acima do arquivo
                  corrente, isto é, o diretório do qual este arquivo é membro.
                  Uma estrutura-pai para o ponto de entrada inicial também é
                  fornecido, porém somente os campos fts_level, fts_number e
                  fts_pointer são garantidamente inicializados.

     fts_link     Ao retornar da função fts_children() , o campo fts_link
                  aponta para a próxima estrutura na lista ligada terminada em
                  NULL dos membros do diretório. Caso contrário, o conteúdo do
                  campo fts_link é indefinido.

     fts_cycle    Se um diretório produz um ciclo na hierarquia (veja FTS_DC)
                  por causa de uma ligação sólida entre dois diretórios ou por
                  causa de uma ligação simbólica apontando para um diretório,
                  o campo fts_cycle da estrutura apontará para a estrutura
                  FTSENT na hierarquia que referencia o mesmo arquivo que a
                  estrutura FTSENT corrente. Caso contrário, o conteúdo do
                  campo fts_cycle é indefinido.

     fts_statp    Um ponteiro para informações stat(2) para o arquivo.

     Um buffer simples é usado para todos os caminhos de todos os arquivos na
     hierarquia de arquivos.  Portanto, os campos fts_path e fts_accpath são
     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, será
     necessário que o buffer de caminho seja modificado usando informações
     contidas no campo information contained in that fts_pathlen daquela
     estrutura FTSENT. Quaisquer modificações deste tipo devem ser desfeitas
     antes que chamadas adicionais a fts_read() sejam tentadas.  O campo
     fts_name é sempre terminado em NULL Ns.

FTS_OPEN

     A função fts_open() pega um ponteiro para uma matriz de ponteiros de
     caracteres, que nomeia um ou mais caminhos criando uma hierarquia lógica
     de arquivos a ser atravessada.  A matriz precisa ser terminada com um
     ponteiro NULL.

     Há um grande número de opções, pelo menos uma das quais ( FTS_LOGICAL ou
     FTS_PHYSICAL) precisa ser especificada.  As opções são selecionadas ou
     esto selecionando pelos seguintes valores:

     FTS_COMFOLLOW
                   Esta opção faz com que qualquer ligação simbólica
                   especificada como um caminho raiz seja seguido
                   imediatamente, ou não, se FTS_LOGICAL é especificado
                   também.

     FTS_LOGICAL   Esta opção faz com que as rotinas fts retornem estruturas
                   FTSENT para os alvos das ligações simbólicas, em vez das
                   próprias ligações.  Se esta opção é setada, as únicas
                   ligações simbólicas para que as estruturas FTSENT sejam
                   retornadas para a aplicação são aquelas que referenciam
                   arquivos não existentes.  Tanto FTS_LOGICAL quanto
                   FTS_PHYSICAL precisam ser fornecidos para a função
                   fts_open.()

     FTS_NOCHDIR   Como uma otimização de performance, as funções fts mudam
                   diretórios conforme eles caminham na hierarquia de
                   arquivos.  Isto tem um efeito colateral de que um
                   aplicativo não pode confiar em ser um diretório particular
                   qualquer durante a travessia.  A opção FTS_NOCHDIR desativa
                   esta otimização, e as funções fts não mudarão o diretório
                   corrente.  Note que os aplicativos não devem, por eles
                   próprios, alterar seus diretórios 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 padrão, estruturas FTSENT retornadas referenciam
                   informações características de arquivo ( o campo statp )
                   para cadas arquivo visitado.  Esta opção relaxa aqueles
                   requisitos como uma otimização de performance, permitindo
                   que as funções fts setem o campo fts_info para FTS_NSOK e
                   deixem o conteúdo do campo statp indefinido.

     FTS_PHYSICAL  Esta rotina faz com que as rotinas fts retornem estruturas
                   FTSENT para as próprias ligações simbólicas, em vez dos
                   arquivos-alvo para os quais eles apontam.  Se esta opção é
                   setada, as estruturas FTSENT para todas as ligações
                   simbólicas na hierarquia são retornadas para o aplicativo.
                   FTS_LOGICAL ou FTS_PHYSICAL deve ser fornecido para a
                   função fts_open.()

     FTS_SEEDOT    Por padrão, a menos que sejam especificados como argumentos
                   de caminho para fts_open(), quaisquer arquivos com nome ‘.’
                   ou ‘..’ encontrados na hierarquia de arquivos são
                   ignorados.  Esta opção faz com que as rotinas fts retornem
                   FTSENT para eles.

     FTS_XDEV      Esta opção evita que fts desça para diretórios que tenham
                   um número de dispositivo diferente do arquivo da qual o
                   descendente começa.

     O argumento compar() especifica uma função definida pelo usuário 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 comparação.  Se o campo fts_info é setado para
     FTS_NS ou FTS_NSOK, o campo fts_statp não pode ser usado.  Se o argumento
     compar() é NULL, a ordem de travessia do diretório está na ordem listada
     em path_argv para os caminhos da raiz, e na ordem listada no diretório
     para todos os demais.

FTS_READ

     A função fts_read() retorna um ponteiro para uma estrutura FTSENT
     descrevendo um arquivo na hierarquia.  Diretórios (que são legíveis e não
     causam ciclos) são visitados pelos menos duas vezes, uma vez em pré-ordem
     e uma vez em pós-ordem.  Todos os outros arquivos são visitados pelo
     menos uma vez.  (Ligações fixas entre diretórios que não provocam ciclos,
     ou ligações simbólicas para ligações simbólicas podem fazer com que
     arquivos sejam visitados mais de uma vez, ou diretórios sejam visitados
     mais de duas vezes.)

     Se todos os membros da hierarquia foram retornados, fts_read() retorna
     NULL e seta a variável externa errno para 0.  Se ocorre um erro não
     relacionado a um arquivo na hierarquia, fts_read() retorna NULL e seta
     errno adequadamente.  Se ocorre um erro relacionado a um arquivo
     retornado, é retornado um ponteiro para uma estrutura FTSENT , e errno
     pode ou não 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
     diretório, em cujo caso eles não serão sobreescritos até que seja feita
     uma chamada a fts_read() depois que uma estrutura FTSENT tenha sido
     retornada pela função fts_read() em pós-ordem.

FTS_CHILDREN

     A função fts_children() retorna um ponteiro para uma estrutura FTSENT
     descrevendo a primeira entrada em uma lista ligada, terminada em NULL,
     dos arquivos no diretório representado pela estrutura FTSENT mais
     recentemente retornada por fts_read().  A lista é ligada através do campo
     fts_link da estrutura FTSENT , e é ordenada pela função de comparação
     especificada pelo usuário, se houver.  Chamadas repetidas a
     fts_children() recriará esta lista ligada.

     Como um caso especial, se fts_read() ainda não foi chamado para uma
     hierarquia, fts_children() retornará um ponteiro para os arquivos no
     diretório lógico especificado para fts_open(), isto é, os argumentos
     especificados para fts_open().  Caso contrário, se a estrutura FTSENT
     retornada mais recentemente por fts_read() não é um diretório sendo
     visitado em pré-ordem, ou o diretório não contém 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 são necessários.  Os
                   conteúdos de todos os campos na lista ligada de estruturas
                   retornada são indefinidas com exceção dos campos fts_name e
                   fts_namelen.

FTS_SET

     A função fts_set() permite que a aplicação do usuário determine um
     processamento adicional para o arquivo f do fluxo ftsp.  A função
     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 próxima chamada a fts_read() retornará o
                   arquivo referenciado.  Os campos fts_stat e fts_info da
                   estrutura serão reiniciados naquele momento, mas nenhum
                   outro campo será alterado.  Esta opção é significativa
                   somente para o arquivo mais recentemente retornado de
                   fts_read().  Uso normal é para visitas a diretórios em pós-
                   ordem, onde faz com que o diretório seja revisitado (tanto
                   em pré-ordem quanto em pós-ordem) junto com todos os seus
                   descendentes.

     FTS_FOLLOW    O arquivo referenciado precisa ser uma ligação simbólica.
                   Se o arquivo referenciado é o mais recentemente retornado
                   por fts_read(), a próxima chamada a fts_read() retorna o
                   arquivo com os campos fts_info e fts_statp reinicializados
                   para refletir o alvo das ligações simbólicas em vez da
                   própria ligação simbólica.  Se o arquivo é um daqueles mais
                   recentemente retornados por fts_children(), os campos
                   fts_info e fts_statp da estrutura, quando retornados por
                   fts_read(), refletirão o alvo da ligação simbólica em vez
                   da própria ligação simbólica.  Neste caso, se o alvo da
                   ligação simbólica não existe, os campos da estrutura
                   retornada não serão alterados e o campo fts_info será
                   setado para FTS_SLNONE.

                   Se o alvo da ligação é um diretório, é feito um retorno de
                   pré-ordem, seguido pelo retorno de todos os seus
                   descendentes, seguido por um retorno de pós-ordem.

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

FTS_CLOSE

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

ERROS

     A função fts_open() pode falhar e setar errno para qualquer um dos erros
     especificados para as funções de biblioteca open(2) e malloc(3).

     A função fts_close() pode falhar e setar errno para qualquer um dos erros
     especificados para as funções de biblioteca chdir(2) e close(2).

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

     Além disso, fts_children(), fts_open() e fts_set() podem falhar e setar
     errno como segue:

     [EINVAL]           As opções eram inválidas.

VEJA TAMBÉM

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

PADRÕES

     BSD 4.4. Espera-se que o utilitário fts seja incluído em uma futura
     revisão de

DISPONIBILIDADE

     Estas funções estão disponíveis em Linux desde a glibc2 (libc6).  RUBENS
     DE JESUS NOGUEIRA <darkseid99@usa.net> (tradução) XXXXXX XX XXXXX
     XXXXXXXX <xxxxxxxxxx@xxx.xxx> (revisão)