Función SetFilePointerEx (fileapi.h)

Artículo
01/30/2024

Mueve el puntero de archivo del archivo especificado.

Sintaxis

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

Parámetros

[in] hFile

Identificador del archivo. El identificador de archivo debe haberse creado con el derecho de acceso GENERIC_READ o GENERIC_WRITE . Para obtener más información, vea Seguridad de archivos y derechos de acceso.

[in] liDistanceToMove

Número de bytes que se van a mover el puntero de archivo. Un valor positivo mueve el puntero hacia delante en el archivo y un valor negativo mueve el puntero de archivo hacia atrás.

[out, optional] lpNewFilePointer

Puntero a una variable para recibir el nuevo puntero de archivo. Si este parámetro es NULL, no se devuelve el nuevo puntero de archivo.

[in] dwMoveMethod

Punto de partida para el movimiento del puntero de archivo. Este parámetro puede ser uno de los valores siguientes.

Valor	Significado
FILE_BEGIN 0	El punto inicial es cero o el principio del archivo. Si se especifica esta marca, el parámetro liDistanceToMove se interpreta como un valor sin signo.
FILE_CURRENT 1	El punto inicial es el valor actual del puntero de archivo.
FILE_END 2	El punto de partida es la posición actual del final del archivo.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

El puntero de archivo devuelto por esta función no se usa para las operaciones de lectura y escritura superpuestas. Para especificar el desplazamiento para las operaciones superpuestas, use los miembros Offset y OffsetHigh de la estructura SUPERPUESTA .

No se puede usar la función SetFilePointerEx con un identificador para un dispositivo que no esté abierto, como una canalización o un dispositivo de comunicaciones. Para determinar el tipo de archivo para hFile, use la función GetFileType .

Tenga cuidado al establecer el puntero de archivo en una aplicación multiproceso. Debe sincronizar el acceso a los recursos compartidos. Por ejemplo, una aplicación cuyos subprocesos comparten un identificador de archivo, actualiza el puntero de archivo y lee desde el archivo debe proteger esta secuencia mediante un objeto de sección crítico o un objeto de exclusión mutua. Para obtener más información sobre estos objetos, vea Objetos de sección crítica y Objetos de exclusión mutua.

Si el identificador hFile se abrió con el conjunto de marcas de FILE_FLAG_NO_BUFFERING , una aplicación solo puede mover el puntero de archivo a posiciones alineadas con sectores. Una posición alineada con el sector es una posición que es un número entero múltiplo del tamaño del sector del volumen. Una aplicación puede obtener el tamaño del sector de un volumen llamando a la función GetDiskFreeSpace . Si una aplicación llama a SetFilePointerEx con valores de distancia a movimiento que dan como resultado una posición que no está alineada con el sector y un identificador que se abrió con FILE_FLAG_NO_BUFFERING, se produce un error en la función y GetLastError devuelve ERROR_INVALID_PARAMETER. Para obtener más información, consulte Almacenamiento en búfer de archivos.

Tenga en cuenta que no es un error establecer el puntero de archivo en una posición más allá del final del archivo. El tamaño del archivo no aumenta hasta que se llama a la función SetEndOfFile, WriteFile o WriteFileEx . Una operación de escritura aumenta el tamaño del archivo a la posición del puntero de archivo más el tamaño del búfer escrito, lo que da lugar a que los bytes intermedios se inicialicen a cero.

Puede usar SetFilePointerEx para determinar la longitud de un archivo. Para ello, use FILE_END para dwMoveMethod y busque la ubicación cero. El desplazamiento del archivo devuelto es la longitud del archivo. Sin embargo, esta práctica puede tener efectos secundarios no deseados, como el error al guardar el puntero de archivo actual para que el programa pueda volver a esa ubicación. Es más sencillo y seguro usar la función GetFileSizeEx en su lugar.

También puede usar SetFilePointerEx para consultar la posición del puntero de archivo actual. Para ello, especifique un método de movimiento de FILE_CURRENT y una distancia de cero.

En Windows 8 y Windows Server 2012, esta función es compatible con las tecnologías siguientes.

Tecnología	Compatible
Protocolo Bloque de mensajes del servidor (SMB) 3.0	Sí
Conmutación por error transparente (TFO) de SMB 3.0	Sí
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)	Sí
Sistema de archivos de Volumen compartido de clúster (CsvFS)	Sí
Sistema de archivos resistente a errores (ReFS)	Sí

Requisitos


Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	fileapi.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll