Функция SetFilePointerEx (fileapi.h)

Статья
08/23/2023

Перемещает указатель на указанный файл.

Синтаксис

BOOL SetFilePointerEx(
  [in]            HANDLE         hFile,
  [in]            LARGE_INTEGER  liDistanceToMove,
  [out, optional] PLARGE_INTEGER lpNewFilePointer,
  [in]            DWORD          dwMoveMethod
);

Параметры

[in] hFile

Дескриптор файла. Дескриптор файла должен быть создан с правом доступа GENERIC_READ или GENERIC_WRITE . Дополнительные сведения см. в разделе Безопасность файлов и права доступа.

[in] liDistanceToMove

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

[out, optional] lpNewFilePointer

Указатель на переменную для получения нового указателя на файл. Если этот параметр имеет значение NULL, новый указатель на файл не возвращается.

[in] dwMoveMethod

Начальная точка перемещения указателя файла. Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
FILE_BEGIN 0	Начальная точка равна нулю или началу файла. Если этот флаг указан, параметр liDistanceToMove интерпретируется как значение без знака.
FILE_CURRENT 1	Начальная точка — это текущее значение указателя на файл.
FILE_END 2	Отправной точкой является текущая позиция окончания файла.

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

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Указатель на файл, возвращаемый этой функцией, не используется для перекрывающихся операций чтения и записи. Чтобы указать смещение для перекрывающихся операций, используйте элементы Offset и OffsetHigh структуры OVERLAPPED .

Нельзя использовать функцию SetFilePointerEx с дескриптором для устройства, не являющегося частью, например каналом или устройством связи. Чтобы определить тип файла для hFile, используйте функцию GetFileType .

Будьте внимательны при установке указателя на файл в многопотоковом приложении. Необходимо синхронизировать доступ к общим ресурсам. Например, приложение, потоки которого совместно используют дескриптор файла, обновление указателя на файл и чтение из файла, должно защитить эту последовательность с помощью объекта критического раздела или объекта мьютекса. Дополнительные сведения об этих объектах см. в разделе Объекты критического раздела и объекты мьютексов.

Если дескриптор hFile был открыт с установленным флагом FILE_FLAG_NO_BUFFERING , приложение может переместить указатель на файл только в положение, выровненное по секторам. Позиция, выровненная по секторам, — это позиция, которая является целым числом, кратным размеру сектора тома. Приложение может получить размер сектора тома, вызвав функцию GetDiskFreeSpace . Если приложение вызывает SetFilePointerEx со значениями расстояния до перемещения, что приводит к позиции, которая не выравнивается по секторам, и дескриптор, открытый с FILE_FLAG_NO_BUFFERING, функция завершается сбоем, и GetLastError возвращает ERROR_INVALID_PARAMETER. Дополнительные сведения см. в разделе Буферизация файлов.

Обратите внимание, что установка указателя на файл на позицию за пределами конца файла не является ошибкой. Размер файла не увеличивается до тех пор, пока вы не вызовете функцию SetEndOfFile, WriteFile или WriteFileEx . Операция записи увеличивает размер файла до позиции указателя файла плюс размер записанного буфера, что приводит к нулевой инициализации промежуточных байтов.

Для определения длины файла можно использовать SetFilePointerEx . Для этого используйте FILE_END для dwMoveMethod и найдите нулевое расположение. Возвращаемое смещение файла — это длина файла. Однако эта практика может иметь непредвиденные побочные эффекты, такие как сбой при сохранении текущего указателя файла, чтобы программа вернется в это расположение. Использовать функцию GetFileSizeEx проще и безопаснее.

Вы также можете использовать SetFilePointerEx для запроса текущей позиции указателя файла. Для этого укажите метод перемещения FILE_CURRENT и расстояние, равное нулю.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Да
Прозрачная отработка отказа (TFO) SMB 3.0	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Восстанавливаемая файловая система (ReFS)	Да

Требования


Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	fileapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll