FTS(3)

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

SINÓPSE
#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 percorrer hierarquias de arquivos UNIX. Uma visão geral simples é que a função fts_open() retorna um 'handle' em uma hierarquia de arquivos, o qual é então fornecido para as outras funções fts. A função fts_read() retorna um ponteiro para uma estrutura descrevendo um dos arquivos na hierarquia de arquivos. A função fts_children() retorna um ponteiro para uma lista encadeada de estruturas, cada qual descrevendo um dos arquivos contidos em um diretório da hierarquia. Em geral, diretórios são visitados duas vezes distintas: em pré-ordem (antes que qualquer de seus descendentes seja visitado) e em pós-ordem (depois de que todos os seus descendentes tenham sido visitados). Arquivos são visitados uma vez. É possível percorrer a hierarquia ``logicamente'' (ignorando links simbólicos) ou fisicamente (visitando links simbólicos), ordenar a pesquisa da hierarquia ou ramificação e/ou revisitar porções da hierarquia.

Duas estruturas estão definidas (e submetidas a typedef) no arquivo de inclusão <fts.h>. A primeira é FTS, a estrutura que representa a hierarquia de arquivos em si. A segunda é FTSENT, a estrutura que representa um arquivo na hierarquia de arquivos. Normalmente, uma estrutura FTSENT é retornada para cada arquivo na hierarquia de arquivos. Nesta página de manual, ``arquivo'' e “estrutura FTSENT” são geralmente intercambiáveis. A estrutura FTSENT contém pelo menos os seguintes campos, que são descritos em maior detalhe abaixo:

    typedef struct _ftsent {
    	u_short fts_info;		/* sinalizadores para estrutura FTSENT */
    	char *fts_accpath;		/* caminho para acesso */
    	char *fts_path;			/* caminho raiz */
    	short fts_pathlen;		/* strlen(fts_path) */
    	char *fts_name;			/* nome de arquivo */
    	short fts_namelen;		/* strlen(fts_name) */
    	short fts_level;		/* profundidade (-1 a N) */
    	int fts_errno;			/* errno para arquivo */
    	long fts_number;		/* valor numérico local */
    	void *fts_pointer;		/* valor de endereço local */
    	struct ftsent *fts_parent;	/* diretório pai */
    	struct ftsent *fts_link;	/* próxima estrutura de arquivo */
    	struct ftsent *fts_cycle;	/* estrutura de ciclo */
    	struct stat *fts_statp;		/* informação de stat(2) */
    } FTSENT;

Esses campos são definidos como segue:

fts_info
    Um dos seguintes sinalizadores descrevendo a estrutura FTSENT retornada e o arquivo que ela representa. Com a exceção de diretórios sem erros (FTS_D), todas essas entradas são terminais, isto é, elas não serão revisitadas, assim como nenhum de seus descendentes será.

    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 támbem será preenchido.)

    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. Isso é um retorno de erro, e o campo fts_errno será definido para indicar o que causou o erro.

    FTS_DOT
        Um arquivo de nome ‘’. 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. O conteúdo da estrutura FTSENT estará inalterado em relação a quando ela foi retornada em pré-ordem, isto é, com o campo fts_info definido para FTS_D.

    FTS_ERR
        Isso é retorno de erro e o campo fts_errno será definido para indicar o que causou o erro.

    FTS_F
        Um arquivo normal.

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

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

    FTS_SL
        Um link simbólico.

    FTS_SLNONE
        Um link simbólico com um alvo inexistente. O conteúdo do campo fts_statp referencia as informações características de arquivo do próprio link simbólico.

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

fts_path
    O caminho para o arquivo relativo à raiz da pesquisa. Esse caminho contém o caminho 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 pesquisa, numerada de -1 a N, onde este arquivo foi encontrado. A estrutura FTSENT representando o pai do ponto inicial (ou raiz) da pesquisa é numerada como -1, e a estrutura FTSENT para a raiz em si é numerada como 0.

fts_errno
    Quando do retorno de uma estrutura FTSENT pelas funções fts_children() ou fts_read(), com seu campo fts_info definido 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. Em outro caso, o conteúdo do campo fts_errno é indefinido.

fts_number
    Esse campo é fornecido para o uso da aplicação e não é modificado pelas funções fts. Ele é inicializado para 0.

fts_pointer
    Esse campo é fornecido para o uso da aplicação e não é modificado pelas funções Ele é inicializado para NULO.

fts_parent
    Um ponteiro para a estrutura FTSENT referenciando o arquivo na hierarquia imediatamente acima do arquivo atual, isto é, o diretório do qual este arquivo é um membro. Uma estrutura pai para o ponto de entrada inicial é fornecida também; no entanto, apenas os campos fts_level, fts_number e fts_pointer são garantidamente inicializados.

fts_link
    Quando do retorno da função fts_children(), o campo fts_link aponta para a próxima estrutura na lista encadeada terminada em NULL de membros do diretório. Em outro caso, o conteúdo do campo fts_link é indefinido.

fts_cycle
    Se um diretório causa um ciclo na hierarquia (veja FTS_DC), ou por causa de um "hard link" entre dois diretórios, ou um link simbólico 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 atual. Em outro caso, o conteúdo do campo fts_cycle é indefinido.

fts_statp
    Um ponteiro para a informação de stat(2) para o arquivo.

Um único trecho de memória é utilizado para todos os caminhos dos arquivos na hierarquia de arquivos. Portanto, os campos fts_path e fts_accpath são garantidamente terminados em NULL apenas para o arquivo mais recentemente retornado por fts_read(). Utilizar esses campos para referenciar quaisquer arquivos representados por outras estruturas FTSENT requererá que o trecho de memória armazenando o caminho seja modificado usando a informação contida no campo fts_pathlen daquela estrutura FTSENT. Qualquer dessas modificações deve ser desfeita antes que chamadas subseqüentes a fts_read() sejam tentadas. O campo fts_name é sempre terminado em NULL.

FTS_OPEN
A função fts_open() toma um ponteiro para um vetor de ponteiros para caractere nomeando um ou mais caminhos que constituem uma hierarquia lógica de arquivos a ser percorrida. O vetor deve ser terminado por um ponteiro NULO.

Há uma quantidade de opções, das quais pelo menos uma (ou FTS_LOGICAL ou FTS_PHYSICAL) deve ser especificada. As opções são selecionadas pelo ou dos seguintes valores:

DV FTS_COMFOLLOW
    Essa opção faz com que qualquer link simbólico especificado como um caminho raiz seja seguido imediatamente, tanto se FTS_LOGICAL também for ou não especificado.

FTS_LOGICAL
    Essa opção faz com que as rotinas fts retornem estruturas FTSENT para os alvos de links simbólicos em vez de para os links simbólicos em si. Se essa opção for definida, os únicos links simbólicos para os quais estruturas FTSENT são retornadas para a aplicação serão aqueles referenciando arquivos inexistentes. Ou FTS_LOGICAL ou FTS_PHYSICAL devem ser fornecidos para a função fts_open().

FTS_NOCHDIR
    Como uma otimização de performance, as funções fts trocam diretórios enquanto percorrem a hierarquia de arquivos. Isso tem o efeito colateral de que uma aplicação não pode assumir estar em qualquer diretório em particular durante a pesquisa. A opção FTS_NOCHDIR desliga essa otimização e as funções fts não trocarão o diretório corrente. Note que as aplicações não devem elas próprias trocarem seu diretório corrente e tentarem acessar arquivos a menos que FTS_NOCHDIR seja especificado e nomes de caminho absolutos sejam 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 cada arquivo visitado. Essa opção relaxa aquele requisito como uma otimização para performance, permitindo que as funções fts definam o campo fts_info para FTS_NSOK e deixem o conteúdo do campo statp indefinido.

FTS_PHYSICAL
    Essa opção faz com que as rotinas fts retornem estruturas FTSENT para os links simbólicos em si em vez dos arquivos alvo para os quais eles apontam. Se essa opção for definida, estruturas FTSENT para todos os links simbólicos na hierarquia são retornados para a aplicação. Ou FTS_LOGICAL ou FTS_PHYSICAL devem ser fornecidos para a função fts_open().

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

DV FTS_XDEV
    Essa opção impede fts de descer em diretórios que tenham um número de dispositivo diferente daquele do arquivo no qual a busca iniciou.

O argumento compar() especifica uma função definida pelo usuário, a qual pode ser usada para ordenar a pesquisa da hierarquia. Ela toma dois ponteiros para ponteiros para estruturas FTSENT como 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 com respeito a, 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 nessa comparação. Se o campo fts_info estiver definido para FTS_NS ou FTS_NSOK, o campo fts_statp também não pode ser. Se o argumento compar() for NULO, a ordem da pesquisa do diretório está na ordem listada em path_argv para os caminhos raiz e na ordem listada no diretório para tudo o mais.

FTS_READ
A função fts_read() retorna um ponteiro para uma estrutura FTSENT descrevendo um arquivo na hierarquia. Diretórios (que possam ser lidos e não causem ciclos) são visitados pelo menos duas vezes, uma em pré-ordem e uma em pós-ordem. Todos os outros arquivos são visitados pelos menos uma vez. (Ligações do tipo "hard link" entre diretórios que não causam ciclos ou links simbólicos para links simbólicos podem fazer com que arquivos sejam visitados mais de uma vez, ou diretórios mais de duas vezes.)

Se todos os membros da hierarquia tiverem sido retornados, fts_read() retorna NULL e define a variável externa errno para 0. Se um erro não relacionado com um arquivo na hierarquia ocorrer, fts_read() retorna NULL e define errno apropriadamente. Se um erro relacionado com um arquivo retornado ocorrer, um ponteiro para uma estrutura FTSENT é retornado e errno pode ou não ter sido definido (veja fts_info).

As estruturas FTSENT retornadas por fts_read() podem ser sobrescritas após uma chamada a fts_close() sobre o mesmo fluxo de hierarquia de arquivos, ou após uma chamada a fts_read() sobre o mesmo fluxo de hierarquia de arquivos, a menos que elas representem um arquivo de tipo diretório, caso em que elas não serão sobrescritas até após uma chamada a fts_read() depois da estrutura FTSENT ter 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 encadeada terminada em NULL dos arquivos no diretório representado pela estrutura FTSENT mais recentemente rtornada por fts_read(). A lista é encadeada através do campo fts_link da estrutura FTSENT e é ordenada pela função de comparação especificada pelo usuário, se houver. Repetidas chamadas a fts_children() recriarão essa lista encadeada.

Como um caso especial, se fts_read() não tiver sido chamada ainda 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(). Em outro caso, se a estrutura FTSENT mais recentemente retornada por fts_read() não for um diretório sendo visitado em pré-ordem, ou o diretório não contiver quaisquer arquivos, fts_children() retorna NULO e define errno para zero. Se um erro ocorrer, fts_children() retorna NULO e define errno apropriadamente.

As estruturas FTSENT retornadas por fts_children() podem ser sobrescritas após uma chamada a fts_children(), fts_close() ou fts_read() sobre o mesmo fluxo de hierarquia de arquivos.

Option pode ser definida para os seguintes valores:

FTS_NAMEONLY
    Apenas os nomes dos arquivos são necessários. O conteúdo de todos os campos nas listas encadeadas de estruturas retornadas são indefinidos, com exceção dos campos fts_name e fts_namelen

FTS_SET
A função fts_set() permite que a aplição do usuário determine um processamento subseqüente para o arquivo f do fluxo ftsp. A função fts_set() retorna 0 para sucesso, e -1 se um erro ocorrer. Option deve ser definida para um dos seguintes valores:

FTS_AGAIN
    Revisite 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 reinicializados naquele momento, mas nenhum outro campo será alterado. Essa opção tem sentido apenas para o arquivo mais recentemente retornado por fts_read(). O uso normal é para visitas a diretório em pós-ordem, onde ela faz com que o diretório seja revisitado (em ambos pré e pós-ordem) assim como seus descendentes.

FTS_FOLLOW
    O arquivo referenciado deve ser um link simbólico. Se o arquivo referenciado for 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 do link simbólico em vez do link simbólico em si. Se o arquivo for um daqueles mais recentemente retornados por fts_children(), os campos fts_info e fts_statp da estrutura, quando retornados por fts_read(), irão refletir o alvo do link simbólico em vez do link simbólico em si. Em ambos os casos, se o alvo do link simbólico não existir, os campos da estrutura retornada estarão inalterados e o campo fts_info estará definido para FTS_SLNONE.

    Se o alvo do link for um diretório, o retorno de pré-ordem, seguido pelo retorno de todos os seus descendentes, seguido por um retorno de pós-ordem, é feito.

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

FTS_CLOSE
A função fts_close() fecha um fluxo de hierarquia de arquivos ftsp e restaura o diretório corrente para o diretório do qual fts_open() foi chamada para abrir ftsp. A função fts_close() retorna 0 para sucesso e -1 se um erro ocorrer.

ERROS
A função fts_open() pode falhar e definir errno para algum dos erros especificados para as funções de bilioteca open(2) e malloc(3).

A função fts_close() pode falhar e definir errno para algum dos erros especificados para as funções de bilioteca chdir(2) e close(2).

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

Adicionalmente, fts_children(), fts_open() e fts_set() podem falhar e definir errno como segue:

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

VEJA TAMBÉM
find(1), chdir(2), stat(2), qsort(3.)

DE ACORDO COM
BSD 4.4. Espera-se que o utilitário fts seja incluído em uma futura revisão p1003.1-88.

DISPONIBILIDADE
Estas funções estão disponíveis no Linux desde a glibc2.

TRADUZIDO POR LDP-BR em 16/06/2001.

  Tradução:
Marcelo M. de Abreu <mmabreu@terra.com.br>

  Revisão.:
André Luiz Fassone <lonely_wolf@ig.com.br>