.\" $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 .Fd #include .Fd #include .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 DESCRIÇÃO As funções .Nm fts são fornecidas para a travessia de hierarquias de arquivos .Tn UNIX. Uma visão geral simples é que a função .Fn fts_open retorna um ''manipulador'' em uma hierarquia de arquivo, que é então fornecida para as outras funções .Nm fts. A função .Fn fts_read retorna um ponteiro para uma estrutura que descreve um dos arquivos na hierarquia de arquivos. A função .Fn 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. .Pp Duas estruturas são definidas (inclusive via 'typedef') no arquivo de inclusão .Aq Pa fts.h . A primeira é .Fa FTS , a estrutura que representa a própria 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 página de manual, ''file'' e .Dq Fa FTSENT No structure geralmente são intercambiáveis. A estrutura .Fa FTSENT contém pelo menos os seguintes campos, que são 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 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; .Ed .Pp Estes campos são 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 exceção dos diretórios sem erros .Pq Dv 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. .Bl -tag -width FTS_DEFAULT .It Dv FTS_D Um diretório sendo visitado em pré-ordem. .It Dv FTS_DC Um diretório que causa um ciclo na árvore. (O campo .Fa fts_cycle da estrutura .Fa FTSENT será preenchida também.) .It Dv FTS_DEFAULT Qualquer estrutura .Fa FTSENT que representa um tipo de arquivo não descrito explicitamente por um dos outros valores .Fa fts_info. .It Dv FTS_DNR Um diretório que não 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 não foi especificado como um nome de arquivo para .Fn fts_open (veja .Dv FTS_SEEDOT ) . .It Dv FTS_DP Um diretório sendo visitado em pós-ordem. Os conteúdos da estrutura .Fa FTSENT serão imutáveis 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 informação .Xr stat 2 estava disponível. O conteúdo 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 informação .Xr stat 2 foi requisitada. O conteúdo do campo .Fa fts_statp é indefinido. .It Dv FTS_SL Uma ligação simbólica. .It Dv FTS_SLNONE Uma ligação simbólica com um alvo não-existente. O conteúdo do campo .Fa fts_statp referencia a informação característica do arquivo para a própria ligação simbólica. .El .It Fa fts_accpath Um caminho para acessar o arquivo a partir do diretório corrente. .It Fa fts_path O caminho para o arquivo em relação à 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 própria raiz é numerada com 0. .It Fa fts_errno Ao retornar de uma estrutura .Fa FTSENT das funções .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 contém o valor da variável externa .Va errno especificando a causa do erro. Caso contrário, o conteúdo do campo .Fa fts_errno é indefinido. .It Fa fts_number Este campo é fornecido para o uso do programa de aplicação e não é modificado pelas funções .Nm fts. É inicializado com 0. .It Fa fts_pointer Este campo é fornecido para o uso de programas aplicativos e não é modificado pelas funções .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 diretório do qual este arquivo é membro. Uma estrutura-pai para o ponto de entrada inicial também é fornecido, porém somente os campos .Fa fts_level , .Fa fts_number e .Fa fts_pointer são garantidamente inicializados. .It Fa fts_link Ao retornar da função .Fn fts_children , o campo .Fa 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 .Fa fts_link é indefinido. .It Fa fts_cycle Se um diretório produz um ciclo na hierarquia (veja .Dv 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 .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 contrário, o conteúdo do campo .Fa fts_cycle é indefinido. .It Fa fts_statp Um ponteiro para informações .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 são 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á necessário que o buffer de caminho seja modificado usando informações contidas no campo information contained in that .Fa fts_pathlen daquela estrutura .Fa FTSENT. Quaisquer modificações 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 função .Fn 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 .Dv NULL. .Pp Há um grande número de opções, pelo menos uma das quais ( .Dv FTS_LOGICAL ou .Dv FTS_PHYSICAL ) precisa ser especificada. As opções são selecionadas .Em ou estão selecionando pelos seguintes valores: .Bl -tag -width "FTS_PHYSICAL" .It Dv 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 .Dv FTS_LOGICAL é especificado também. .It Dv FTS_LOGICAL Esta opção faz com que as rotinas .Nm fts retornem estruturas .Fa 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 .Fa FTSENT sejam retornadas para a aplicação são aquelas que referenciam arquivos não existentes. Tanto .Dv FTS_LOGICAL quanto .Dv FTS_PHYSICAL .Em precisam ser fornecidos para a função .Fn fts_open. .It Dv FTS_NOCHDIR Como uma otimização de performance, as funções .Nm 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 .Dv FTS_NOCHDIR desativa esta otimização, e as funções .Nm 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 .Dv FTS_NOCHDIR seja especificado e os caminhos de arquivos absolutos foram fornecidos como argumentos para .Fn fts_open . .It Dv FTS_NOSTAT Por padrão, estruturas .Fa FTSENT retornadas referenciam informações características de arquivo ( o campo .Fa statp ) para cadas arquivo visitado. Esta opção relaxa aqueles requisitos como uma otimização de performance, permitindo que as funções .Nm fts setem o campo .Fa fts_info para .Dv FTS_NSOK e deixem o conteúdo do campo .Fa statp indefinido. .It Dv FTS_PHYSICAL Esta rotina faz com que as rotinas .Nm fts retornem estruturas .Fa 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 .Fa FTSENT para todas as ligações simbólicas na hierarquia são retornadas para o aplicativo. .Dv FTS_LOGICAL ou .Dv FTS_PHYSICAL .Em deve ser fornecido para a função .Fn fts_open. .It Dv FTS_SEEDOT Por padrão, 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 são ignorados. Esta opção faz com que as rotinas .Nm fts retornem .Fa FTSENT para eles. .It Dv FTS_XDEV Esta opção evita que .Nm fts desça para diretórios que tenham um número de dispositivo diferente do arquivo da qual o descendente começa. .El .Pp O argumento .Fn 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 .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 comparação. Se o campo .Fa fts_info é setado para .Dv FTS_NS ou .Dv FTS_NSOK , o campo .Fa fts_statp não pode ser usado. Se o argumento .Fn compar é .Dv NULL , a ordem de travessia do diretório está na ordem listada em .Fa path_argv para os caminhos da raiz, e na ordem listada no diretório para todos os demais. .Sh FTS_READ A função .Fn fts_read retorna um ponteiro para uma estrutura .Fa 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.) .Pp Se todos os membros da hierarquia foram retornados, .Fn fts_read retorna .Dv NULL e seta a variável externa .Va errno para 0. Se ocorre um erro não 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 não 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 diretório, em cujo caso eles não serão sobreescritos até que seja feita uma chamada a .Fn fts_read depois que uma estrutura .Fa FTSENT tenha sido retornada pela função .Fn fts_read em pós-ordem. .Sh FTS_CHILDREN A função .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 diretório representado pela estrutura .Fa FTSENT mais recentemente retornada por .Fn fts_read . A lista é ligada através do campo .Fa fts_link da estrutura .Fa FTSENT , e é ordenada pela função de comparação especificada pelo usuário, se houver. Chamadas repetidas a .Fn fts_children recriará esta lista ligada. .Pp Como um caso especial, se .Fn fts_read ainda não foi chamado para uma hierarquia, .Fn fts_children retornará um ponteiro para os arquivos no diretório lógico especificado para .Fn fts_open , isto é, os argumentos especificados para .Fn fts_open . Caso contrário, se a estrutura .Fa FTSENT retornada mais recentemente por .Fn fts_read não é um diretório sendo visitado em pré-ordem, ou o diretório não contém 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 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 .Fa fts_name e .Fa fts_namelen. .El .Sh FTS_SET A função .Fn fts_set permite que a aplicação do usuário determine um processamento adicional para o arquivo .Fa f do fluxo .Fa ftsp . A função .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 próxima chamada a .Fn fts_read retornará o arquivo referenciado. Os campos .Fa fts_stat e .Fa 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 .Fn 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. .It Dv FTS_FOLLOW O arquivo referenciado precisa ser uma ligação simbólica. Se o arquivo referenciado é o mais recentemente retornado por .Fn fts_read , a próxima chamada a .Fn fts_read retorna o arquivo com os campos .Fa fts_info e .Fa 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 .Fn fts_children , os campos .Fa fts_info e .Fa fts_statp da estrutura, quando retornados por .Fn 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 .Fa fts_info será setado para .Dv FTS_SLNONE . .Pp 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. .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 função .Fn fts_close fecha um fluxo de hierarquia de arquivo .Fa ftsp e recupera o diretório corrente para o diretório do qual .Fn fts_open foi chamado para abrir .Fa ftsp . A função .Fn fts_close retorna 0 em caso de sucesso, e \-1 se ocorre um erro. .Sh ERROS A função .Fn fts_open pode falhar e setar .Va errno para qualquer um dos erros especificados para as funções de biblioteca .Xr open 2 e .Xr malloc 3 . .Pp A função .Fn fts_close pode falhar e setar .Va errno para qualquer um dos erros especificados para as funções de biblioteca .Xr chdir 2 e .Xr close 2 . .Pp As funções .Fn fts_read e .Fn fts_children podem falhar e setar .Va errno para qualquer um dos erros especificados para as funções de biblioteca .Xr chdir 2 , .Xr malloc 3 , .Xr opendir 3 , .Xr readdir 3 e .Xr stat 2 . .Pp Além 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 opções eram inválidas. .El .Sh VEJA TAMBÉM .Xr find 1 , .Xr chdir 2 , .Xr stat 2 , .Xr qsort 3 .Sh PADRÕES BSD 4.4. Espera-se que o utilitário .Nm fts seja incluído em uma futura revisão de .St -p1003.1-88. .Sh DISPONIBILIDADE Estas funções estão disponíveis em Linux desde a glibc2 (libc6). .SH TRADUÇÃO PARA A LÍNGUA PORTUGUESA \&\fR\&\f(CWRUBENS DE JESUS NOGUEIRA (tradução)\fR \&\fR\&\f(CWXXXXXX XX XXXXX XXXXXXXX (revisão)\fR