table of contents
FTS(3) | Library Functions Manual | FTS(3) |
NOME¶
fts
, fts_open
,
fts_read
, fts_children
,
fts_set
, fts_close
—
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çõesfts
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 parafts_open
() (vejaFTS_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
() oufts_read
() , com seus campos fts_info setados paraFTS_DNR
,FTS_ERR
ouFTS_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 comNULL
. - 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çãofts_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. TantoFTS_LOGICAL
quantoFTS_PHYSICAL
precisam ser fornecidos para a funçãofts_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çãoFTS_NOCHDIR
desativa esta otimização, e as funçõesfts
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 queFTS_NOCHDIR
seja especificado e os caminhos de arquivos absolutos foram fornecidos como argumentos parafts_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 paraFTS_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
ouFTS_PHYSICAL
deve ser fornecido para a funçãofts_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 rotinasfts
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çãofts_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çãofts_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çãofts_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 defts_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 afts_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 porfts_children
(), os campos fts_info e fts_statp da estrutura, quando retornados porfts_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 paraFTS_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
() oufts_read
().
FTS_CLOSE¶
A funçãofts_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çãofts_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áriofts
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)16 de abril de 1994 | Linux 4.19.0-10-amd64 |