fopen_s, _wfopen_s

Apre un file. Queste versioni di hanno _wfopenmiglioramenti perfopen la sicurezza, come descritto in Funzionalità di sicurezza in CRT.

Sintassi

errno_t fopen_s(
   FILE** pFile,
   const char *filename,
   const char *mode
);
errno_t _wfopen_s(
   FILE** pFile,
   const wchar_t *filename,
   const wchar_t *mode
);

Parametri

pFile
Puntatore al puntatore al file che riceve il puntatore al file aperto.

filename
Nome del file da aprire.

mode
Tipo di accesso consentito.

Valore restituito

Zero se con esito positivo; un codice di errore in caso di errore. Per altre informazioni su questi codici di errore, vedere errno, _doserrno, _sys_errliste _sys_nerr.

Condizioni di errore

pFile	filename	mode	Valore restituito	Contenuto di pFile
NULL	qualsiasi	qualsiasi	EINVAL	non modificato
qualsiasi	NULL	qualsiasi	EINVAL	non modificato
qualsiasi	qualsiasi	NULL	EINVAL	non modificato

Osservazioni:

Le fopen_s funzioni e _wfopen_s non possono aprire un file per la condivisione. Se è necessario condividere il file, usare _fsopen o _wfsopen con la costante della modalità di condivisione appropriata, ad esempio usare _SH_DENYNO per la condivisione di lettura/scrittura.

La fopen_s funzione apre il file specificato da filename. _wfopen_s è una versione a caratteri wide di fopen_s e gli argomenti da _wfopen_s usare sono stringhe di caratteri wide. _wfopen_s e fopen_s si comportano in modo identico, in caso contrario.

fopen_s accetta percorsi validi nel file system in corrispondenza del punto di esecuzione. Percorsi UNC e percorsi che coinvolgono le unità di rete mappate vengono accettati da fopen_s a condizione che il sistema che esegue il codice abbia accesso alla condivisione o a un'unità di rete mappata al momento dell'esecuzione. Quando si creano i percorsi per fopen_s, non dare per scontato che le unità, i percorsi o le condivisioni di rete saranno disponibili nell'ambiente di esecuzione. È possibile usare barre (/) o barre rovesciata (\) come separatori di directory in un percorso.

Queste funzioni convalidano i relativi parametri. Se pFile, filenameo mode è un puntatore Null, queste funzioni generano un'eccezione di parametro non valida, come descritto in Convalida dei parametri.

Controllare sempre il valore restituito per verificare se la funzione ha avuto esito positivo prima di eseguire altre operazioni sul file. Se si verifica un errore, viene restituito il codice di errore e viene impostata la variabile errno globale. Per altre informazioni, vedereerrno, _doserrno, _sys_errliste _sys_nerr.

Per impostazione predefinita, lo stato globale di questa funzione è limitato all'applicazione. Per modificarlo, vedere Stato globale in CRT.

Supporto Unicode

fopen_s supporta flussi di file di Unicode. Per aprire un file Unicode nuovo o esistente, passare un ccs flag che specifica la codifica desiderata a fopen_s, ad esempio:

fopen_s(&fp, "newfile.txt", "w+, ccs=UNICODE");

I valori consentiti del ccs flag sono UNICODE, UTF-8e UTF-16LE. Se non viene specificato alcun valore per ccs, fopen_s usa la codifica ANSI.

Se il file esiste già e viene aperto per la lettura o l'aggiunta, il byte order mark (BOM), se presente nel file, determina la codifica. La codifica dell'indicatore per l'ordine dei byte ha la precedenza sulla codifica specificata dal flag ccs. La codifica ccs viene usata solo se nessun indicatore per l'ordine dei byte è presente o il file è nuovo.

Nota

Il rilevamento di indicatori per l'ordine dei byte si applica solo ai file aperti in modalità Unicode (ovvero passando il flag ccs).

La tabella seguente riepiloga le modalità per i vari ccs valori di flag assegnati a fopen_s e per le macchine virtuali nel file.

Codifiche usate in base al ccs flag e alla distinta base

Flag diccs	Nessun indicatore ordine byte (o file nuovo)	Indicatore ordine byte (BOM): UTF-8	Indicatore ordine byte (BOM): UTF-16
UNICODE	UTF-8	UTF-8	UTF-16LE
UTF-8	UTF-8	UTF-8	UTF-16LE
UTF-16LE	UTF-16LE	UTF-8	UTF-16LE

I file aperti per la scrittura in modalità Unicode dispongono di un indicatore per l'ordine dei byte scritto automaticamente in tali file.

Se mode è "a, ccs=UNICODE", "a, ccs=UTF-8"o "a, ccs=UTF-16LE", fopen_s tenta prima di tutto di aprire il file con accesso in lettura e scrittura. Se ha esito positivo, la funzione legge l'indicatore per l'ordine dei byte per determinare la codifica del file. In caso contrario, la funzione usa la codifica predefinita per il file. In entrambi i casi, fopen_s riapre il file con accesso in sola scrittura. Questo comportamento si applica solo alla modalità, non a+a a .

La stringa di caratteri mode specifica il tipo di accesso richiesto per il file, come illustrato di seguito.

mode	Accesso
"r"	Viene aperto per la lettura. Se il file non esiste o non è stato trovato, la fopen_s chiamata non riesce.
"w"	Apre un file vuoto per la scrittura. Se il file specificato esiste, il contenuto viene eliminato in modo permanente.
"a"	Viene aperto per la scrittura alla fine del file (aggiunta) senza rimuovere il marcatore di fine file (EOF) prima che nuovi dati vengano scritti sul file. Creare il file se non esiste.
"r+"	Viene aperto per la lettura e la scrittura. Il file deve esistere.
"w+"	Apre un file vuoto per la lettura e la scrittura. Se il file esiste, il contenuto viene eliminato in modo permanente.
"a+"	Viene aperto per la lettura e l'aggiunta. L'operazione di aggiunta comporta la rimozione del marcatore di EOF prima che nuovi dati vengano scritti sul file. L'indicatore EOF non viene ripristinato al termine della scrittura. Creare il file se non esiste.

Quando un file viene aperto con il tipo di accesso "a" o "a+", tutte le operazioni di scrittura vengono eseguite alla fine del file. Il puntatore del file può essere riposizionato usando fseek o rewind, ma viene sempre spostato di nuovo alla fine del file prima che venga eseguita un'operazione di scrittura in modo che i dati esistenti non possano essere sovrascritti.

La "a" modalità non rimuove il marcatore EOF prima dell'aggiunta al file. Dopo l'accodamento, il comando MS-DOS TYPE visualizza solo i dati fino al marcatore EOF originale e non i dati aggiunti al file. La modalità "a+" rimuove il marcatore EOF prima di aggiungere il file. Dopo l'aggiunta, il comando MS-DOS TYPE mostra tutti i dati nel file. La "a+" modalità è necessaria per l'aggiunta a un file di flusso terminato con l'indicatoreCTRL+ Z EOF.

Quando si specifica il tipo di accesso , "w+"o "a+" , sono consentite sia la "r+"lettura che la scrittura. (Si dice che il file sia aperto per "update".) Tuttavia, quando si passa dalla lettura alla scrittura, l'operazione di input deve venire attraverso un marcatore EOF. Se non è presente alcun marcatore EOF, è necessario usare una chiamata di intervento a una funzione di posizionamento dei file. Le funzioni di posizionamento di file sono fsetpos, fseek e rewind. Quando si passa dalla scrittura alla lettura, è necessario usare una nuova chiamata a fflush o a una funzione di posizionamento di file.

A partire da C11, è possibile accodare "x" o "w""w+" per causare un errore della funzione se il file esiste, anziché sovrascriverlo.

Oltre ai valori precedenti, è possibile includere i caratteri seguenti in mode per specificare la modalità di conversione per i caratteri di nuova riga:

mode Modificatore	Modalità di traduzione
t	Aprire in modalità testo (convertita). Le combinazioni di avanzamento riga ritorno a capo (CR-LF) vengono convertite in feed a riga singola (LF) in caratteri di input e LF vengono convertite in combinazioni CR-LF nell'output. CTRL+Z viene interpretato come carattere di fine file all'input.
b	Apri in modalità binaria (non tradotta); le traduzioni che coinvolgono caratteri ritorno a capo e avanzamento riga vengono eliminate.

In modalità CTRL+testo (tradotto), Z viene interpretato come carattere di fine file all'input. Per i file aperti per la lettura/scrittura con "a+", fopen_s verifica la presenza di una+CTRL Z alla fine del file e la rimuove, se possibile. Viene rimosso perché l'uso fseek e ftell lo spostamento all'interno di un file che termina con una CTRL+Z, può causare fseek un comportamento non corretto vicino alla fine del file.

Inoltre, in modalità testo, le combinazioni ritorno a capo/avanzamento riga (CRLF) vengono convertite in caratteri LF (Single Line Feed) all'input e I caratteri LF vengono convertiti in combinazioni CRLF nell'output. Quando una funzione Unicode di I/O flusso viene eseguita in modalità testo (impostazione predefinita), si presuppone che il flusso di origine o di destinazione sia una sequenza di caratteri multibyte. Le funzioni di input del flusso Unicode converte i caratteri multibyte in caratteri wide (come se fosse una chiamata alla mbtowc funzione). Per qualche motivo, le funzioni Unicode di output flusso convertono i caratteri "wide" in caratteri multibyte, come se fosse una chiamata alla funzione wctomb .

Se t o b non viene specificato in mode, la modalità di conversione predefinita viene definita dalla variabile _fmodeglobale . Se t o b è il prefisso dell'argomento, la funzione ha esito negativo e restituisce NULL.

Per altre informazioni sull'uso di modalità testo e binaria in I/O di flusso Unicode e multibyte, vedere I/O di file in modalità testo e binario e I/O del flusso Unicode in modalità testo e binario.

mode Modificatore	Comportamento
c	Abilitare il flag commit per filename associato, in modo da scrivere il contenuto del buffer di file direttamente su disco se viene chiamato fflush o _flushall .
n	Reimpostare il flag di commit per l'oggetto associato filename a "no-commit". Questo flag è il valore predefinito. Esegue anche l'override del flag di commit globale se si collega il programma a COMMODE.OBJ. Il flag di commit globale predefinito è "no-commit", a meno che non si collega esplicitamente il programma con COMMODE.OBJ (vedere Opzioni di collegamento).
N	Specifica che il file non viene ereditato dai processi figlio.
S	Specifica che la memorizzazione nella cache è ottimizzata, ma non limitata, per l'accesso sequenziale dal disco.
R	Specifica che la memorizzazione nella cache è ottimizzata, ma non limitata, per l'accesso casuale dal disco.
T	Specifica un file che non viene scritto su disco a meno che non sia richiesto un utilizzo elevato di memoria.
D	Specifica un file temporaneo eliminato quando viene chiuso l'ultimo puntatore al file.
ccs=UNICODE	Specifica UNICODE come set di caratteri codificati da utilizzare per questo file. Lasciare non specificato se si vuole la codifica ANSI.
ccs=UTF-8	Specifica UTF-8 come set di caratteri codificati da usare per questo file. Lasciare non specificato se si vuole la codifica ANSI.
ccs=UTF-16LE	Specifica UTF-16LE come set di caratteri codificati da usare per questo file. Lasciare non specificato se si vuole la codifica ANSI.

I caratteri validi per la mode stringa usata in e _fdopen corrispondono agli oflag argomenti usati in fopen_s_open e _sopen, come indicato di seguito.

Caratteri nella stringa mode	Valore oflag equivalente per _open/_sopen
a	_O_WRONLY | _O_APPEND (in genere _O_WRONLY | _O_CREAT | _O_APPEND)
a+	_O_RDWR | _O_APPEND (in genere _O_RDWR | _O_APPEND | _O_CREAT)
R	_O_RDONLY
r+	_O_RDWR
w	_O_WRONLY (in genere _O_WRONLY | _O_CREAT | _O_TRUNC)
w+	_O_RDWR (in genere **_O_RDWR | _O_CREAT | _O_TRUNC)
b	_O_BINARY
t	_O_TEXT (tradotto)
c	None
n	None
D	_O_TEMPORARY
R	_O_RANDOM
S	_O_SEQUENTIAL
T	_O_SHORTLIVED
ccs=UNICODE	_O_WTEXT
ccs=UTF-8	_O_UTF8
ccs=UTF-16LE	_O_UTF16

Le copzioni , Rn, St, Te Dmode sono estensioni Microsoft per fopen_s e _wfopen_s non devono essere usate quando si vuole la portabilità ANSI.

Se usi rb la modalità, i file Win32 mappati alla memoria potrebbero anche essere un'opzione se non devi convertire il codice, prevedi di leggere gran parte del file o non ti interessa le prestazioni di rete.

Informazioni su T e D:

• T evita di scrivere il file su disco, purché non sia necessaria una pressione di memoria. Per altre informazioni, vedere FILE_ATTRIBUTE_TEMPORARY in Costanti attributo file e anche questo post di blog È solo temporaneo.
• D specifica un file normale scritto su disco. La differenza è che viene eliminata automaticamente quando viene chiusa. È possibile combinare TD per ottenere entrambe le semantiche.

Requisiti

Funzione	Intestazione obbligatoria	Intestazione C++
fopen_s	<stdio.h>	<cstdio>
_wfopen_s	<stdio.h> oppure <wchar.h>	<cstdio>

Per altre informazioni sulla conformità degli standard e sulle convenzioni di denominazione nella libreria di runtime C, vedere Compatibilità.

Mapping di routine di testo generico

<tchar.h> Routine	_UNICODE e _MBCS non definito	_MBCS Definito	_UNICODE Definito
_tfopen_s	fopen_s	fopen_s	_wfopen_s

Librerie

Tutte le versioni delle librerie di runtime C.

Esempio

// crt_fopen_s.c
// This program opens two files. It uses
// fclose to close the first file and
// _fcloseall to close all remaining files.

#include <stdio.h>

FILE *stream, *stream2;

int main( void )
{
   errno_t err;

   // Open for read (will fail if file "crt_fopen_s.c" doesn't exist)
   err  = fopen_s( &stream, "crt_fopen_s.c", "r" );
   if( err == 0 )
   {
      printf( "The file 'crt_fopen_s.c' was opened\n" );
   }
   else
   {
      printf( "The file 'crt_fopen_s.c' was not opened\n" );
   }

   // Open for write
   err = fopen_s( &stream2, "data2", "w+, ccs=UTF-8" );
   if( err == 0 )
   {
      printf( "The file 'data2' was opened\n" );
   }
   else
   {
      printf( "The file 'data2' was not opened\n" );
   }

   // Close stream if it isn't NULL
   if( stream )
   {
      err = fclose( stream );
      if ( err == 0 )
      {
         printf( "The file 'crt_fopen_s.c' was closed\n" );
      }
      else
      {
         printf( "The file 'crt_fopen_s.c' was not closed\n" );
      }
   }

   // All other files are closed:
   int numclosed = _fcloseall( );
   printf( "Number of files closed by _fcloseall: %u\n", numclosed );
}

The file 'crt_fopen_s.c' was opened
The file 'data2' was opened
Number of files closed by _fcloseall: 1

Vedi anche

I/O di flusso
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode