Funzione SetFilePointerEx (fileapi.h)

Articolo
03/14/2023

Sposta il puntatore del file del file specificato.

Sintassi

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

Parametri

[in] hFile

Handle per il file. L'handle di file deve essere stato creato con il GENERIC_READ o GENERIC_WRITE diritto di accesso. Per altre informazioni, vedere Sicurezza file e diritti di accesso.

[in] liDistanceToMove

Numero di byte per spostare il puntatore del file. Un valore positivo sposta il puntatore in avanti nel file e un valore negativo sposta il puntatore di file indietro.

[out, optional] lpNewFilePointer

Puntatore a una variabile per ricevere il nuovo puntatore al file. Se questo parametro è NULL, il nuovo puntatore al file non viene restituito.

[in] dwMoveMethod

Punto di partenza per lo spostamento del puntatore del file. Questo parametro può avere uno dei valori seguenti.

Valore	Significato
FILE_BEGIN 0	Il punto iniziale è zero o l'inizio del file. Se questo flag viene specificato, il parametro liDistanceToMove viene interpretato come valore senza segno.
FILE_CURRENT 1	Il punto iniziale è il valore corrente del puntatore al file.
FILE_END 2	Il punto iniziale è la posizione finale del file corrente.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Il puntatore al file restituito da questa funzione non viene usato per operazioni di lettura e scrittura sovrapposte. Per specificare l'offset per le operazioni sovrapposte, usare i membri Offset e OffsetHigh della struttura OVERLAPPED.

Non è possibile usare la funzione SetFilePointerEx con un handle per un dispositivo non visualizzante, ad esempio una pipe o un dispositivo di comunicazione. Per determinare il tipo di file per hFile, usare la funzione GetFileType .

Prestare attenzione quando si imposta il puntatore file in un'applicazione multithreading. È necessario sincronizzare l'accesso alle risorse condivise. Ad esempio, un'applicazione i cui thread condividono un handle di file, aggiorna il puntatore al file e legge dal file deve proteggere questa sequenza usando un oggetto sezione critico o un oggetto mutex. Per altre informazioni su questi oggetti, vedere Oggetti della sezione critica e Oggetti Mutex.

Se l'handle hFile è stato aperto con il set di flag FILE_FLAG_NO_BUFFERING , un'applicazione può spostare il puntatore del file solo alle posizioni allineate al settore. Una posizione allineata al settore è una posizione che rappresenta un numero intero di dimensioni del settore del volume. Un'applicazione può ottenere le dimensioni del settore di un volume chiamando la funzione GetDiskFreeSpace . Se un'applicazione chiama SetFilePointerEx con valori da distanza a spostamento che comportano una posizione non allineata al settore e un handle aperto con FILE_FLAG_NO_BUFFERING, la funzione ha esito negativo e GetLastError restituisce ERROR_INVALID_PARAMETER. Per altre informazioni, vedere Buffering file.

Si noti che non è un errore per impostare il puntatore del file su una posizione oltre la fine del file. Le dimensioni del file non aumentano finché non si chiama la funzione SetEndOfFile, WriteFile o WriteFileEx. Un'operazione di scrittura aumenta le dimensioni del file nella posizione del puntatore del file più le dimensioni del buffer scritto, che comporta l'inizializzazione zero dei byte di intervento.

È possibile usare SetFilePointerEx per determinare la lunghezza di un file. A tale scopo, usare FILE_END per dwMoveMethod e cercare la posizione zero. L'offset del file restituito è la lunghezza del file. Tuttavia, questa pratica può avere effetti collaterali imprevisti, ad esempio l'errore di salvare il puntatore del file corrente in modo che il programma possa tornare a tale posizione. È invece più semplice e sicuro usare la funzione GetFileSizeEx .

È anche possibile usare SetFilePointerEx per eseguire query sulla posizione del puntatore al file corrente. A tale scopo, specificare un metodo di spostamento di FILE_CURRENT e una distanza pari a zero.

In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.

Tecnologia	Supportato
Protocollo SMB (Server Message Block) 3.0	Sì
Failover trasparente SMB 3.0 (TFO)	Sì
SMB 3.0 con condivisioni file con scalabilità orizzontale (SO)	Sì
File system del volume condiviso del cluster (CsvFS)	Sì
File system resiliente (ReFS)	Sì

Requisiti


Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	fileapi.h (includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll