fseek

int fseek( FILE* stream, long offset, int origin );

#define SEEK_SET    /* unspecified */
#define SEEK_CUR    /* unspecified */
#define SEEK_END    /* unspecified */

Устанавливает индикатор позиции в файловом потоке stream в значение, на которое указывает offset.

Если stream открыт в двоичном режиме, новая позиция находится ровно на offset байт от начала файла, если origin равно SEEK_SET, от текущей позиции в файле, если origin равно SEEK_CUR, и от конца файла, если origin равно SEEK_END. Двоичные потоки не обязаны поддерживать SEEK_END, в частности, если выводятся дополнительные нулевые байты.

Если stream открыт в текстовом режиме, единственными поддерживаемыми значениями для offset являются ноль (который работает с любым origin) и значение, возвращённое предыдущим вызовом ftell для потока, связанного с тем же файлом (которое работает только с origin типа SEEK_SET).

Если stream имеет широкую ориентацию, применяются ограничения как для текстовых, так и для двоичных потоков (результат ftell разрешён с SEEK_SET, а нулевое смещение разрешено относительно SEEK_SET и SEEK_CUR, но не SEEK_END).

Помимо изменения индикатора позиции в файле, fseek отменяет действие ungetc и сбрасывает признак конца файла, если он установлен.

В случае ошибки чтения или записи устанавливается индикатор ошибки потока (ferror), а позиция в файле не изменяется.

Параметры

Возвращаемое значение

0 в случае успеха, ненулевое значение в противном случае.

Примечания

После перемещения в позицию, не являющуюся концом файла, в широком потоке следующий вызов любой функции вывода может сделать оставшуюся часть файла неопределённой, например, выведя многобайтовую последовательность другой длины.

Для текстовых потоков допустимы только следующие значения offset: 0 (применимо к любому origin) и значение, возвращённое предыдущим вызовом ftell (применимо только к SEEK_SET).

POSIX допускает перемещение за существующий конец файла. Если после такого перемещения выполнить вывод, любое чтение из промежутка вернёт нулевые байты. Если файловая система поддерживает такую возможность, создаётся разреженный файл.

POSIX также требует, чтобы fseek сначала выполняла fflush, если имеются какие-либо незаписанные данные (однако восстановление состояния сдвига определяется реализацией).

Согласно POSIX, fseek должна возвращать -1 в случае ошибки и устанавливать errno для указания на ошибку.

В Windows для работы с файлами размером более 2 ГиБ можно использовать _fseeki64.

Пример

#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    // Prepare an array of double values.
    #define SIZE 5
    double A[SIZE] = {1.0, 2.0, 3.0, 4.0, 5.0};

    // Write array to a file.
    FILE * fp = fopen("test.bin", "wb");
    fwrite(A, sizeof(double), SIZE, fp);
    fclose (fp);

    // Read the double values into array B.
    double B[SIZE];
    fp = fopen("test.bin", "rb");

    // Set the file position indicator in front of third double value.
    if (fseek(fp, sizeof(double) * 2L, SEEK_SET) != 0)
    {
        fprintf(stderr, "fseek() failed in file %s at line # %d\n",
                __FILE__, __LINE__ - 2);
        fclose(fp);
        return EXIT_FAILURE;
    }

    int ret_code = fread(B, sizeof(double), 1, fp); // reads one double value
    printf("ret_code == %d\n", ret_code);           // prints the number of values read
    printf("B[0] == %.1f\n", B[0]);                 // prints one value

    fclose(fp);
    return EXIT_SUCCESS;
}

ret_code == 1
B[0] == 3.0

Ссылки

• Стандарт C23 (ISO/IEC 9899:2024):
• 7.23.9.2 Функция fseek (стр.: TBD)
• Стандарт C17 (ISO/IEC 9899:2018):
• 7.21.9.2 Функция fseek (стр.: 245)
• Стандарт C11 (ISO/IEC 9899:2011):
• 7.21.9.2 Функция fseek (стр.: 336-337)
• Стандарт C99 (ISO/IEC 9899:1999):
• 7.19.9.2 Функция fseek (стр.: 302-303)
• Стандарт C89/C90 (ISO/IEC 9899:1990):
• 4.9.9.2 Функция fseek

См. также