NOME¶

fgetpos, fseek, fsetpos, ftell, rewind - reposiciona um fluxo

BIBLIOTECA¶

Biblioteca C Padrão (libc, -lc)

SINOPSE¶

#include <stdio.h>

int fseek(FILE *fluxo, long deslocamento, int de_onde);
long ftell(FILE *stream);

void rewind(FILE *fluxo);

int fgetpos(FILE *restrict fluxo, fpos_t *restrict pos);
int fsetpos(FILE *fluxo, const fpos_t *pos);

DESCRIÇÃO¶

A função fseek() define o indicador de posição de arquivo do fluxo apontado por fluxo. A nova posição, medida em bytes, é obtida pelo acréscimo de deslocamento bytes à posição especificada por de_onde. Se de_onde é definido para SEEK_SET, SEEK_CUR ou SEEK_END, o deslocamento é relativo ao início do arquivo, ao indicador de posição atual, ou ao fim de arquivo, respectivamente. Uma chamada bem sucedida à função fseek() limpa o indicador de fim de arquivo para o fluxo e desfaz qualquer efeito da função ungetc(3) no mesmo fluxo.

A função ftell() obtém o valor corrente do indicador de posição de arquivo do fluxo apontado por fluxo.

A função rewind() define o indicador de posição de arquivo do fluxo apontado por fluxo para o início do arquivo. É equivalente a:

exceto pelo fato de que o indicador de erro do fluxo também é limpo (veja clearerr(3)).

As funções fgetpos() e fsetpos() são interfaces alternativas equivalentes a ftell() e fseek() (com de_onde definido para SEEK_SET), definindo e armazenando o valor atual do deslocamento do arquivo do objeto referenciado por pos. Em alguns sistemas não-UNIX, um objeto fpos_t pode ser um objeto complexo e estas rotinas podem ser a única maneira portável de reposicionar um fluxo de texto.

Se o fluxo se referir a um arquivo regular e o deslocamento do fluxo resultante estiver além do tamanho do arquivo, as gravações subsequentes estenderão o arquivo com um furo, até o deslocamento, antes de confirmar qualquer dado. Consulte lseek(2) para obter detalhes sobre a semântica de busca de arquivos.

VALOR DE RETORNO¶

A função rewind() não retorna valor. Em caso de término bem-sucedido, fgetpos(), fseek(), fsetpos() retornam 0, e ftell() retorna o deslocamento atual. Caso contrário, -1 é retornado e errno é definido para indicar o erro.

ERROS¶

EINVAL

O argumento de_onde de fseek() não era SEEK_SET, SEEK_END ou SEEK_CUR. Ou: o deslocamento de arquivo resultando seria negativo.

ESPIPE

O descritor de arquivo subjacente ao fluxo não é pesquisável (por exemplo, ele se refere a um encadeamento, FIFO ou soquete).

As funções fgetpos(), fseek(), fsetpos() e ftell() também podem falhar e definir errno para qualquer um dos erros especificados para as rotinas fflush(3), fstat(2), lseek(2) e malloc(3).

ATRIBUTOS¶

Para uma explicação dos termos usados nesta seção, consulte attributes(7).

PADRÕES¶

C11, POSIX.1-2008.

HISTÓRICO¶

POSIX.1-2001, C89.

VEJA TAMBÉM¶

lseek(2), fseeko(3)

TRADUÇÃO¶

A tradução para português brasileiro desta página man foi criada por Rubens de Jesus Nogueira <darkseid99@usa.net>, André Luiz Fassone <lonely_wolf@ig.com.br> e Rafael Fontenelle <rafaelff@gnome.org>.

Esta tradução é uma documentação livre; leia a Licença Pública Geral GNU Versão 3 ou posterior para as condições de direitos autorais. Nenhuma responsabilidade é aceita.

Se você encontrar algum erro na tradução desta página de manual, envie um e-mail para a lista de discussão de tradutores.