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,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)