r2 - 06 Mar 2006 - IgorSutton

NAME
SINOPSE
DESCRIÇÃO
CONSTRUTOR
MÉTODOS
NOTA
VEJA TAMBÉM
BUGS
HISTORY
TRADUÇÃO

NAME

IO::Handle - fornece métodos de objeto para manipulação de I/O handles

SINOPSE

    use IO::Handle;

    $io = new IO::Handle;

    if ($io->fdopen(fileno(STDIN),"r")) {

        print $io->getline;

        $io->close;

    $io = new IO::Handle;

    if ($io->fdopen(fileno(STDOUT),"w")) {

        $io->print("Some text\n");

    # setvbuf não está disponível por padrão no Perl 5.8.0 e posterior

    use IO::Handle '_IOLBF';

    $io->setvbuf($buffer_var, _IOLBF, 1024);

    undef $io;       # fecha o arquivo automaticamente caso este esteja aberto

    autoflush STDOUT 1;

voltar para o topo

DESCRIÇÃO

A classe IO::Handle é a classe base para todas as outras classes de manipulação de IO. Não é intencionado que objetos de IO::Handle devam ser criados diretamente, por este motivo IO::Handle é herdado por diversas outras classes pertencentes à hierarquia de classes de IO. Se você está lendo esta documentação, procurando por um substituto para o pacote FileHandle, então sugerimos que você leia a documentação de IO::File também.

voltar para o topo

CONSTRUTOR

new (): Cria um novo objeto IO::Handle.
new_from_fd ( FD, MODE ): Cria um novo IO::Handle, exatamente como new faz. Este método necessita dois parâmetros, que são passados para o método fdopen. Em caso de uma falha de fdopen, o objeto é destruído. Caso contrário, o objeto é retornado para a rotina que o chamou.

voltar para o topo

MÉTODOS

Veja the perlfunc manpage para uma descrição completa de cada um dos métodos suportados pelo IO::Handle, que são apenas interfaces para as funções de Perl correspondentes:

    $io->close

    $io->eof

    $io->fileno

    $io->format_write( [FORMAT_NAME] )

    $io->getc

    $io->read ( BUF, LEN, [OFFSET] )

    $io->print ( ARGS )

    $io->printf ( FMT, [ARGS] )

    $io->stat

    $io->sysread ( BUF, LEN, [OFFSET] )

    $io->syswrite ( BUF, [LEN, [OFFSET]] )

    $io->truncate ( LEN )

Veja the perlvar manpage para descrição completa de cada um dos seguintes métodos de IO::Handle. Todos eles retornarão o valor do atributo e podem ter um argumento único que atribuirá o valor da variável. Caso nenhum argumento seja passado, o valor da variável é mantido (exceto para $io->autoflush que é ativado por padrão).

    $io->autoflush ( [BOOL] )                         $|

    $io->format_page_number( [NUM] )                  $%

    $io->format_lines_per_page( [NUM] )               $=

    $io->format_lines_left( [NUM] )                   $-

    $io->format_name( [STR] )                         $~

    $io->format_top_name( [STR] )                     $^

    $io->input_line_number( [NUM])                    $.

Os seguintes métodos não são suportados em objetos instanciados.

    IO::Handle->format_line_break_characters( [STR] ) $:

    IO::Handle->format_formfeed( [STR])               $^L

    IO::Handle->output_field_separator( [STR] )       $,

    IO::Handle->output_record_separator( [STR] )      $\

    IO::Handle->input_record_separator( [STR] )       $/

Para operações normais de I/O, você irá precisar destes métodos:

$io->fdopen ( FD, MODE ): O método fdopen é similar ao método open, exceto pelo seu primeiro parâmetro não ser um nome de arquivo mas sim um nome de um filehandle, um objeto do tipo IO::Handle ou um número de um descritor de arquivo.
$io->opened: Retorna verdadeiro caso o objeto seja um descritor de arquivos válido, caso contrário retorna falso.
$io->getline: Este método funciona como <$io> descrito em I/O Operators in the perlop manpage, exceto pelo fato de ser mais legível e pode ser utilizado em um contexto de listas, e devolverá apenas uma linha.
$io->getlines: Este método funciona como <$io> quando utilizado em contexto de lista, para ler todas as linhas restantes de um arquivo, exceto pelo fato de ser mais legível. Ele irá também chamar croak() se for acidentalmente executado em um contexto escalar.
$io->ungetc ( ORD ): Adiciona um caracter com o valor ordinal passado como argumento de volta ao input stream do filehandle. Apenas um caracter por handle é garantido. (N.T.: Tentar melhorar o contexto desta frase.)
$io->write ( BUF, LEN [, OFFSET ] ): O método write funciona como a função write encontrada no C, que é o oposto de read. A interface para a função write do Perl é chamada format_write.
$io->error: Retorna um valor verdadeiro se o handle obteve algum erro desde que foi aberto ou desde a última chamada à clreaerr, ou caso o handle for inválido. Ele apenas retorna false para um handle válido sem nenhum erro.
$io->clearerr: Limpa o indicador de erros do handle. Retorna -1 se o handle é inválido, caso contrário 0.
$io->sync: O método sync sincroniza o conteúdo de um arquivo que está em memória com aquele que está em uma mídia física. sync não opera no nível da API de perlio, porém opera no descritor de arquivo (similar a sysread, sysseek e systell). Isto significa que todo dado que estiver no nível da API de perlio não irá ser sincronizada. Para sincronizar estes dados que estão bufferizados no nível da API do perlio, você precisa utilizar o método flush. sync não é implementado em todas as plataformas. Ele retorn 0 em caso de sucesso, undef em caso de erros e handle inválido. Veja the fsync(3c) manpage.
$io->flush: flush faz com que o Perl despeje todos os dados bufferizados no nível da API do perlio. Todo dado não lido do buffer será descartado, e qualquer dado que não tenha sido escrito será escrito no descritor de arquivos correspondente. Retorna 0 em caso de sucesso, undef em caso de erro.
$io->printflush ( ARGS ): Ativa autoflush, imprime ARGS e então restaura o status do autoflush do objeto IO::Handle. Retorna o valor repassado por print.
$io->blocking ( [ BOOL ] ): Caso seja chamado com um argumento, o método blocking irá ativar o IO não bloqueante se BOOL for falso, e desativá-lo caso BOOL seja verdadeiro.; blocking irá retornar o valor da configuração anterior, ou da configuração atual caso BOOL não seja informado.; Caso um erro ocorra, blocking retornará undef e $! será atribuido.

Caso as funções C setbuf() e/ou setvbuf() estejam disponíveis, então os métodos IO::Handle::setbuf e IO::Handle::setvbuf configurarão a política para o IO::Handle. A sequência de chamadas para as funções Perl são as mesmas do que as C -- incluíndo as constantes _IOFBF, _IOLBF, e _IONBF para setvbuf() -- exceto que os parâmetros do buffer especificam uma variável scalar para usar como buffer. Você deve apenas modificar antes de qualquer operação de I/O, ou imediatamente após executar um flush. ATENÇÃO: A função IO::Handle::setvbuf() não está disponível por padrão no Perl 5.8.0 e atuais porque setvbuf() necessita da biblioteca stdio, enquanto Perl prefere o novo subsistema perlio. ATENÇÃO: Uma variável utilizada com buffer pelo setbuf ou setvbuf não devem ser modificadas de qualquer maneira até que IO::Handle esteja fechado ou setbuf ou setvbuf sejam chamados novamente, ou uma corrupção de memoria poderá acontecer! Lembre-se que a ordem de destruição global é indefinida, então mesmo que sua variável de buffer permaneça no escopo até a finalização do programa, ela pode ser indefinida antes do IO::Handle ser fechado. Note que você precisa importar as constantes _IOFBF, _IOLBF e _IONBF explicitamente. Como C, setbuf não retorna nada. setvbuf retorna 0, em caso de sucesso e undef em caso de falha. Finalmente, há um método especial para trabalhar em tainted mode (-T) e scripts que utilizam setuid/gid:

$io->untaint: Marca o objeto como limpo, e os dados lidos a partir dele serão considerados também limpos. Note que esta é uma ação de confiança que deve ser tomada, e consideração apropriada da fonte dos dados e uma potencial vulnerabilidade deve ser lembrada. Retorna 0 em caso de sucesso, -1 se a marcação falhar (por exemplo, um handle inválido).

voltar para o topo

NOTA

Um objeto do tipo IO::Handle é uma referência para uma referência de símbolo ou GLOB (veja o pacote Symbol). Alguns módulos que extendem IO::Handle podem manter variáveis relacionadas ao objetos na tabela hash do GLOB. Como uma tentativa para prevenir que os módulos interfiram entre si, proponho que estes módulos devem prefixar suas variáveis com seus próprios nomes separados por _. Por exemplo, o módulo IO::Socket mantém uma variável timeout como 'io_socket_timeout'.

voltar para o topo

VEJA TAMBÉM

the perlfunc manpage, I/O Operators in the perlop manpage, the IO::File manpage

voltar para o topo

BUGS

Devido à compatibilidade com versões anteriores, todos os filehandles assemelham-se a objetos da classe IO::Handle ou classes derivadas desta, porém não são. Isto significa que você não pode derivar sua classe de IO::Handle e herdar os métodos.

voltar para o topo