.\"	$NetBSD: fts.3,v 1.13.2.1 1997/11/14 02:09:32 mrg Exp $
.\"
.\" Copyright (c) 1989, 1991, 1993, 1994
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)fts.3	8.5 (Berkeley) 4/16/94
.\"
.Dd 16 de abril de 1994
.Dt FTS 3
.Os
.Sh NOME
.Nm fts ,
.Nm fts_open ,
.Nm fts_read ,
.Nm fts_children ,
.Nm fts_set ,
.Nm fts_close 
.Nd atravessa uma hierarquia de arquivos
.Sh SINOPSE
.Fd #include <sys/types.h>
.Fd #include <sys/stat.h>
.Fd #include <fts.h>
.Ft FTS *
.Fn fts_open "char * const *path_argv" "int options" "int (*compar)(const FTSENT **, const FTSENT **)"
.Ft FTSENT *
.Fn fts_read "FTS *ftsp"
.Ft FTSENT *
.Fn fts_children "FTS *ftsp" "int options"
.Ft int
.Fn fts_set "FTS *ftsp" "FTSENT *f" "int options"
.Ft int
.Fn fts_close "FTS *ftsp"
.Sh DESCRIO
As funes
.Nm fts
so fornecidas para a travessia de hierarquias de arquivos
.Tn UNIX.
Uma viso geral simples  que a funo
.Fn fts_open
retorna um ''manipulador'' em uma hierarquia de arquivo, que  ento fornecida para 
as outras funes
.Nm fts.
A funo
.Fn fts_read
retorna um ponteiro para uma estrutura que descreve um dos arquivos na hierarquia 
de arquivos.
A funo
.Fn fts_children
retorna um ponteiro para uma lista ligada de estruturas, cada uma das quais descreve
um dos arquivos contidos em um diretrio na hierarquia.
Em geral, diretrios so visitados em dois momentos distinguveis: em pr-ordem
(antes que qualquer um dos seus descendentes sejam visitados) e em ps-ordem (depois 
que todos os seus descendentes foram visitados).
Arquivos so visitados uma vez.
 possvel caminhar pela hierarquia ''logicamente'' (ignorando ligaes simblicas)
ou fisicamente (visitando ligaes simblicas), ordenar o caminho da hierarquia ou
podar e/ou re-visitar pores da hierarquia.
.Pp
Duas estruturas so definidas (inclusive via 'typedef') no arquivo de incluso
.Aq Pa fts.h .
A primeira  
.Fa FTS ,
a estrutura que representa a prpria hierarquia de arquivo. A segunda 
.Fa FTSENT ,
a estrutura que representa um arquivo em uma hierarquia de arquivos. 
Normalmente, uma estrutura
.Fa FTSENT
 retornada para qualquer arquivo na hierarquia.
Nesta pgina de manual, ''file'' e
.Dq Fa FTSENT No structure
geralmente so intercambiveis.
A estrutura
.Fa FTSENT
contm pelo menos os seguintes campos, que so descritos em maiores detalhes abaixo:
.Bd -literal
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 numrico local */
	void *fts_pointer;		/* valor do endereo local */
	struct ftsent *fts_parent;	/* diretrio pai */
	struct ftsent *fts_link;	/* estrutura do prximo arquivo */
	struct ftsent *fts_cycle;	/* estrutura de ciclo */
	struct stat *fts_statp;		/* informao de stat(2) */
} FTSENT;
.Ed
.Pp
Estes campos so definidos como segue:
.Bl -tag -width "fts_namelen"
.It Fa fts_info
Uma das seguintes flags que descrevem a estrutura
.Fa FTSENT
retornada, e o arquivo que ela representa.
Com exceo dos diretrios sem erros
.Pq Dv FTS_D ,
todas estas entradas so terminais, ou seja, elas no sero re-visitadas, nem
qualquer dos seus descendentes sero visitados.
.Bl  -tag -width FTS_DEFAULT
.It Dv FTS_D
Um diretrio sendo visitado em pr-ordem.
.It Dv FTS_DC
Um diretrio que causa um ciclo na rvore.
(O campo
.Fa fts_cycle
da estrutura
.Fa FTSENT
ser preenchida tambm.)
.It Dv FTS_DEFAULT
Qualquer estrutura
.Fa FTSENT
que representa um tipo de arquivo no descrito explicitamente por um dos outros
valores
.Fa fts_info.
.It Dv FTS_DNR
Um diretrio que no pode ser lido. Este  um retorno de erro, e o campo
.Fa fts_errno
ser setado para indicar o que causou o erro.
.It Dv FTS_DOT
Um arquivo denominado
.Ql \&.
ou
.Ql ..
que no foi especificado como um nome de arquivo para 
.Fn fts_open
(veja
.Dv FTS_SEEDOT ) .
.It Dv FTS_DP
Um diretrio sendo visitado em ps-ordem.
Os contedos da estrutura
.Fa FTSENT
sero imutveis a partir de quando ele foi retornado em pr-ordem, isto , 
com o campo
.Fa fts_info
setado em
.Dv FTS_D .
.It Dv FTS_ERR
Este  um retorno de erro, e o campo
.Fa fts_errno
ser setado para indicar o que causou o erro.
.It Dv FTS_F
Um arquivo regular.
.It Dv FTS_NS
Um arquivo para o qual nenhuma informao
.Xr stat 2
estava disponvel.
O contedo do campo
.Fa fts_statp
 indefinido.
Este  um retorno de erro, e o campo
.Fa fts_errno
ser setado para indicar o que causou o erro.
.It Dv FTS_NSOK
Um arquivo para o qual nenhuma informao
.Xr stat 2
foi requisitada.
O contedo do campo
.Fa fts_statp
 indefinido.
.It Dv FTS_SL
Uma ligao simblica.
.It Dv FTS_SLNONE
Uma ligao simblica com um alvo no-existente.
O contedo do campo
.Fa fts_statp
referencia a informao caracterstica do arquivo para a prpria
ligao simblica.
.El
.It Fa fts_accpath
Um caminho para acessar o arquivo a partir do diretrio corrente.
.It Fa fts_path
O caminho para o arquivo em relao  raiz da travessia.
Este caminho  aquele especificado para 
.Fn fts_open
como um prefixo.
.It Fa fts_pathlen
O comprimento da string referenciada por
.Fa fts_path .
.It Fa fts_name
O nome do arquivo.
.It Fa fts_namelen
O comprimento da string referenciada por
.Fa fts_name .
.It Fa fts_level
A profundidade da travessia, numerado de \-1 a N, onde este arquivo
foi encontrado.
A estrutura
.Fa FTSENT
que representa o pai do ponto inicial (ou raiz) da travessia  numerada
com \-1, e a estrutura
.Fa FTSENT
para a prpria raiz  numerada com 0.
.It Fa fts_errno
Ao retornar de uma estrutura
.Fa FTSENT
das funes
.Fn fts_children
ou
.Fn fts_read
, com seus campos
.Fa fts_info
setados para  
.Dv FTS_DNR ,
.Dv FTS_ERR
ou
.Dv FTS_NS ,
o campo
.Fa fts_errno
contm o valor da varivel externa
.Va errno
especificando a causa do erro. Caso contrrio, o contedo do campo
.Fa fts_errno
 indefinido.
.It Fa fts_number
Este campo  fornecido para o uso do programa de aplicao e no 
modificado pelas funes
.Nm fts.
 inicializado com 0.
.It Fa fts_pointer
Este campo  fornecido para o uso de programas aplicativos e no 
modificado pelas funes
.Nm fts.
Ele  inicializado com
.Dv NULL .
.It Fa fts_parent
Um ponteiro para uma estrutura
.Fa FTSENT
que referencia o arquivo na hierarquia imediatamente acima do arquivo corrente,
isto , o diretrio do qual este arquivo  membro.
Uma estrutura-pai para o ponto de entrada inicial tambm  fornecido,
porm somente os campos
.Fa fts_level ,
.Fa fts_number
e
.Fa fts_pointer
so garantidamente inicializados.
.It Fa fts_link
Ao retornar da funo
.Fn fts_children
, o campo
.Fa fts_link
aponta para a prxima estrutura na lista ligada terminada em NULL dos membros
do diretrio. Caso contrrio, o contedo do campo
.Fa fts_link
 indefinido.
.It Fa fts_cycle
Se um diretrio produz um ciclo na hierarquia (veja
.Dv FTS_DC ) 
por causa de uma ligao slida entre dois diretrios ou por causa de uma
ligao simblica apontando para um diretrio, o campo
.Fa fts_cycle
da estrutura apontar para a estrutura
.Fa FTSENT
na hierarquia que referencia o mesmo arquivo que a estrutura
.Fa FTSENT
corrente. Caso contrrio, o contedo do campo
.Fa fts_cycle
 indefinido.
.It Fa fts_statp
Um ponteiro para informaes
.Xr stat 2
para o arquivo.
.El
.Pp
Um buffer simples  usado para todos os caminhos de todos os arquivos na
hierarquia de arquivos.
Portanto, os campos
.Fa fts_path
e
.Fa fts_accpath
so garantidamente terminados em 
.Dv NULL Ns 
.Em somente
no arquivo retornado mais recentemente por
.Fn fts_read .
Para usar estes campos para referenciar qualquer arquivo representado por outras estruturas
.Fa FTSENT,
ser necessrio que o buffer de caminho seja modificado usando informaes contidas no campo
information contained in that
.Fa fts_pathlen
daquela estrutura
.Fa FTSENT.
Quaisquer modificaes deste tipo devem ser desfeitas antes que chamadas adicionais a 
.Fn fts_read
sejam tentadas.
O campo
.Fa fts_name
 sempre terminado em
.Dv NULL Ns.
.Sh FTS_OPEN
A funo
.Fn fts_open
pega um ponteiro para uma matriz de ponteiros de caracteres, que nomeia um ou mais caminhos
criando uma hierarquia lgica de arquivos a ser atravessada.
A matriz precisa ser terminada com um ponteiro
.Dv NULL.
.Pp
H um grande nmero de opes, pelo menos uma das quais (
.Dv FTS_LOGICAL
ou
.Dv FTS_PHYSICAL )
precisa ser especificada.
As opes so selecionadas
.Em ou esto selecionando
pelos seguintes valores:
.Bl -tag -width "FTS_PHYSICAL"
.It Dv FTS_COMFOLLOW
Esta opo faz com que qualquer ligao simblica especificada como um caminho raiz seja 
seguido imediatamente, ou no, se
.Dv FTS_LOGICAL
 especificado tambm.
.It Dv FTS_LOGICAL
Esta opo faz com que as rotinas
.Nm fts
retornem estruturas
.Fa FTSENT
para os alvos das ligaes simblicas, em vez das prprias ligaes.
Se esta opo  setada, as nicas ligaes simblicas para que as estruturas
.Fa FTSENT
sejam retornadas para a aplicao so aquelas que referenciam arquivos no existentes.
Tanto
.Dv FTS_LOGICAL
quanto
.Dv FTS_PHYSICAL
.Em precisam
ser fornecidos para a funo
.Fn fts_open.
.It Dv FTS_NOCHDIR
Como uma otimizao de performance, as funes
.Nm fts
mudam diretrios conforme eles caminham na hierarquia de arquivos.
Isto tem um efeito colateral de que um aplicativo no pode confiar em ser
um diretrio particular qualquer durante a travessia.
A opo
.Dv FTS_NOCHDIR
desativa esta otimizao, e as funes
.Nm fts
no mudaro o diretrio corrente.
Note que os aplicativos no devem, por eles prprios, alterar seus diretrios
correntes e tentar acessar arquivos a menos que 
.Dv FTS_NOCHDIR
seja especificado e os caminhos de arquivos absolutos foram 
fornecidos como argumentos para
.Fn fts_open .
.It Dv FTS_NOSTAT
Por padro, estruturas
.Fa FTSENT
retornadas referenciam informaes caractersticas de arquivo ( o campo
.Fa statp
) para cadas arquivo visitado.
Esta opo relaxa aqueles requisitos como uma otimizao de performance,
permitindo que as funes
.Nm fts
setem o campo
.Fa fts_info
para 
.Dv FTS_NSOK
e deixem o contedo do campo
.Fa statp
indefinido.
.It Dv FTS_PHYSICAL
Esta rotina faz com que as rotinas
.Nm fts
retornem estruturas
.Fa FTSENT
para as prprias ligaes simblicas, em vez dos arquivos-alvo para os quais
eles apontam.
Se esta opo  setada, as estruturas
.Fa FTSENT
para todas as ligaes simblicas na hierarquia so retornadas para o 
aplicativo.
.Dv FTS_LOGICAL
ou
.Dv FTS_PHYSICAL
.Em deve
ser fornecido para a funo
.Fn fts_open.
.It Dv FTS_SEEDOT
Por padro, a menos que sejam especificados como argumentos de caminho para 
.Fn fts_open ,
quaisquer arquivos com nome
.Ql \&.
ou
.Ql ..
encontrados na hierarquia de arquivos so ignorados.
Esta opo faz com que as rotinas
.Nm fts
retornem
.Fa FTSENT
para eles.
.It Dv FTS_XDEV
Esta opo evita que 
.Nm fts
desa para diretrios que tenham um nmero de dispositivo diferente do arquivo
da qual o descendente comea.
.El
.Pp
O argumento
.Fn compar
especifica uma funo definida pelo usurio que pode ser usada para ordenar a
travessia da hierarquia.
Ele pega dois ponteiros de ponteiros para estruturas
.Fa 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
.Fa fts_accpath ,
.Fa fts_path
e
.Fa fts_pathlen
das estruturas
.Fa FTSENT
.Em nunca
podem ser usados nesta comparao.
Se o campo 
.Fa fts_info
 setado para 
.Dv FTS_NS
ou
.Dv FTS_NSOK ,
o campo
.Fa fts_statp
no pode ser usado.
Se o argumento
.Fn compar

.Dv NULL ,
a ordem de travessia do diretrio est na ordem listada em
.Fa path_argv
para os caminhos da raiz, e na ordem listada no diretrio para
todos os demais.
.Sh FTS_READ
A funo
.Fn fts_read
retorna um ponteiro para uma estrutura
.Fa FTSENT
descrevendo um arquivo na hierarquia.
Diretrios (que so legveis e no causam ciclos) so visitados pelos menos
duas vezes, uma vez em pr-ordem e uma vez em ps-ordem.
Todos os outros arquivos so visitados pelo menos uma vez.
(Ligaes fixas entre diretrios que no provocam ciclos, ou ligaes simblicas
para ligaes simblicas podem fazer com que arquivos sejam visitados mais de uma
vez, ou diretrios sejam visitados mais de duas vezes.)
.Pp
Se todos os membros da hierarquia foram retornados,
.Fn fts_read
retorna
.Dv NULL
e seta a varivel externa
.Va errno
para 0.
Se ocorre um erro no relacionado a um arquivo na hierarquia,
.Fn fts_read
retorna
.Dv NULL
e seta
.Va errno
adequadamente.
Se ocorre um erro relacionado a um arquivo retornado,  retornado um ponteiro para uma estrutura
.Fa FTSENT
, e
.Va errno
pode ou no ter sido setado (veja
.Fa fts_info ) .
.Pp
As estruturas
.Fa FTSENT
retornadas por
.Fn fts_read
podem ser sobreescritas depois de uma chamada a 
.Fn fts_close
no mesmo fluxo de hierarquia de arquivo, ou, depois de uma chamada a 
.Fn fts_read
no mesmo fluxo de hierarquia de arquivo, a menos que eles representem um arquivo do tipo
diretrio, em cujo caso eles no sero sobreescritos at que seja feita uma chamada a
.Fn fts_read
depois que uma estrutura
.Fa FTSENT
tenha sido retornada pela funo
.Fn fts_read
em ps-ordem.
.Sh FTS_CHILDREN
A funo
.Fn fts_children
retorna um ponteiro para uma estrutura
.Fa FTSENT
descrevendo a primeira entrada em uma lista ligada, terminada em NULL, dos arquivos
no diretrio representado pela estrutura
.Fa FTSENT
mais recentemente retornada por
.Fn fts_read .
A lista  ligada atravs do campo
.Fa fts_link
da estrutura
.Fa FTSENT
, e  ordenada pela funo de comparao especificada pelo usurio, se houver.
Chamadas repetidas a 
.Fn fts_children
recriar esta lista ligada.
.Pp
Como um caso especial, se
.Fn fts_read
ainda no foi chamado para uma hierarquia,
.Fn fts_children
retornar um ponteiro para os arquivos no diretrio lgico especificado para
.Fn fts_open ,
isto , os argumentos especificados para 
.Fn fts_open .
Caso contrrio, se a estrutura
.Fa FTSENT
retornada mais recentemente por
.Fn fts_read
no  um diretrio sendo visitado em pr-ordem,
ou o diretrio no contm nenhum arquivo,
.Fn fts_children
retorna
.Dv NULL
e seta
.Va errno
para zero.
Se ocorre um erro,
.Fn fts_children
retorna
.Dv NULL
e seta
.Va errno
adequadamente.
.Pp
As estruturas
.Fa FTSENT
retornadas por
.Fn fts_children
podem ser sobreescritas depois de uma chamada a
.Fn fts_children ,
.Fn fts_close
ou
.Fn fts_read
no mesmo fluxo de hierarquia de arquivos.
.Pp
.Em Option
pode ser setado para os seguintes valores:
.Bl -tag -width FTS_NAMEONLY
.It Dv FTS_NAMEONLY
Somente os nomes dos arquivos so necessrios.
Os contedos de todos os campos na lista ligada de estruturas retornada
so indefinidas com exceo dos campos
.Fa fts_name
e
.Fa fts_namelen.
.El
.Sh FTS_SET
A funo
.Fn fts_set
permite que a aplicao do usurio determine um processamento adicional para o 
arquivo
.Fa f
do fluxo
.Fa ftsp .
A funo
.Fn fts_set
retorna 0 em caso de sucesso, e \-1 se ocorre um erro.
.Em Option
precisa ser setado para um dos seguintes valores:
.Bl -tag -width FTS_PHYSICAL
.It Dv FTS_AGAIN
Revisita o arquivo; qualquer tipo de arquivo pode ser revisitado.
A prxima chamada a
.Fn fts_read
retornar o arquivo referenciado.
Os campos
.Fa fts_stat
e
.Fa fts_info
da estrutura sero reiniciados naquele momento,
mas nenhum outro campo ser alterado.
Esta opo  significativa somente para o arquivo mais recentemente
retornado de
.Fn fts_read .
Uso normal  para visitas a diretrios em ps-ordem, onde faz com que o diretrio
seja revisitado (tanto em pr-ordem quanto em ps-ordem) junto com todos os seus
descendentes.
.It Dv FTS_FOLLOW
O arquivo referenciado precisa ser uma ligao simblica.
Se o arquivo referenciado  o mais recentemente retornado por
.Fn fts_read ,
a prxima chamada a 
.Fn fts_read
retorna o arquivo com os campos
.Fa fts_info
e
.Fa fts_statp
reinicializados para refletir o alvo das ligaes simblicas em vez da prpria
ligao simblica.
Se o arquivo  um daqueles mais recentemente retornados por
.Fn fts_children ,
os campos
.Fa fts_info
e
.Fa fts_statp
da estrutura, quando retornados por
.Fn fts_read ,
refletiro o alvo da ligao simblica em vez da prpria ligao simblica.
Neste caso, se o alvo da ligao simblica no existe, os campos da estrutura
retornada no sero alterados e o campo
.Fa fts_info
ser setado para 
.Dv FTS_SLNONE .
.Pp
Se o alvo da ligao  um diretrio,  feito um retorno de pr-ordem, seguido pelo retorno
de todos os seus descendentes, seguido por um retorno de ps-ordem.
.It Dv FTS_SKIP
Nenhum descendente deste arquivo  visitado.
O arquivo pode ser um daqueles mais recentemente retornados por
.Fn fts_children
ou
.Fn fts_read .
.El
.Sh FTS_CLOSE
A funo
.Fn fts_close
fecha um fluxo de hierarquia de arquivo
.Fa ftsp
e recupera o diretrio corrente para o diretrio do qual
.Fn fts_open
foi chamado para abrir
.Fa ftsp .
A funo
.Fn fts_close
retorna 0 em caso de sucesso, e \-1 se ocorre um erro.
.Sh ERROS
A funo
.Fn fts_open
pode falhar e setar
.Va errno
para qualquer um dos erros especificados para as funes de biblioteca
.Xr open 2
e
.Xr malloc 3 .
.Pp
A funo
.Fn fts_close
pode falhar e setar
.Va errno
para qualquer um dos erros especificados para as funes de biblioteca
.Xr chdir 2
e
.Xr close 2 .
.Pp
As funes 
.Fn fts_read
e
.Fn fts_children
podem falhar e setar
.Va errno
para qualquer um dos erros especificados para as funes de biblioteca
.Xr chdir 2 ,
.Xr malloc 3 ,
.Xr opendir 3 ,
.Xr readdir 3
e
.Xr stat 2 .
.Pp
Alm disso,
.Fn fts_children ,
.Fn fts_open
e
.Fn fts_set
podem falhar e setar
.Va errno
como segue:
.Bl -tag -width Er
.It Bq Er EINVAL
As opes eram invlidas.
.El
.Sh VEJA TAMBM
.Xr find 1 ,
.Xr chdir 2 ,
.Xr stat 2 ,
.Xr qsort 3
.Sh PADRES
BSD 4.4. Espera-se que o utilitrio
.Nm fts
seja includo em uma futura reviso de 
.St -p1003.1-88.
.Sh DISPONIBILIDADE
Estas funes esto disponveis em Linux desde a glibc2 (libc6).
.SH TRADUO PARA A LNGUA PORTUGUESA
\&\fR\&\f(CWRUBENS DE JESUS NOGUEIRA <darkseid99@usa.net> (traduo)\fR
\&\fR\&\f(CWXXXXXX XX XXXXX XXXXXXXX <xxxxxxxxxx@xxx.xxx> (reviso)\fR