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
NULL
somente 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)