Provided by: manpages-pt-dev_20040726-4_all 
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 estão 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)