fopen_s, _wfopen_s

Articolo
03/26/2013

Apre un file.Queste versioni di fopen, _wfopen presentano miglioramenti della sicurezza, come descritto in Funzionalità di sicurezza in CRT.

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

[out] pFile
Un puntatore al puntatore del file che riceverà il puntatore al file aperto.
[in] filename
Nome file.
[in] mode
Tipo di accesso consentito.

Valore restituito

Zero se ha esito positivo; un codice di errore in caso di errore.Vedere errno, _doserrno, _sys_errlist e _sys_nerr per ulteriori informazioni su questi codici di errore.

Condizioni di errore

pFile	filename	mode	Valore restituito	ContenutodipFile
NULL	any	any	EINVAL	invariato
any	NULL	any	EINVAL	invariato
any	any	NULL	EINVAL	invariato

Note

I file aperti da fopen_s e da _wfopen_s non sono ripartibili.Se è necessario che un file sia ripartibile, utilizzare _fsopen, _wfsopen con la modalità di condivisione costante- appropriata, ad esempio _SH_DENYNO per condividere lettura /scrittura.

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

fopen_s accetta i percorsi validi nel file system in corrispondenza dell'esecuzione; I percorsi UNC i percorsi in cui vengono utilizzate unità di rete mappate sono accettati da fopen_s finché il sistema che esegue il codice ha accesso alla condivisione o un'unità di rete mappata ai tempi di esecuzione.Quando si creano i percorsi per fopen_s, rendere i presupposti sulla disponibilità delle unità, percorsi, o condivisioni di rete nell'ambiente di esecuzione.È possibile utilizzare le barre (//) o le barre rovesciate (\) come separatori della directory in un percorso.

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

Verificare sempre il valore restituito per verificare se la funzione viene completata prima di eseguire nuove operazioni su file.Se si verifica un errore, il codice di errore restituito e la variabile globale errno viene impostata.Per ulteriori informazioni, vedere errno, _doserrno, _sys_errlist e _sys_nerr.

Supporto Unicode

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

fopen_s(&fp, "newfile.txt", "rw, ccs=encoding");

I valori consentiti di encoding sono UNICODE, UTF-8e UTF-16LE.Se in non viene specificato alcun valore per encoding, fopen_s utilizza la codifica ANSI.

Se il file esiste già e verrà visualizzato per indicare o aggiungere, l'indicatore dell'ordine dei byte (BOM), se presente nel file, determina la codifica.La codifica di BOM ha la precedenza sulla codifica specificata dal flag di ccs.La codifica di ccs viene utilizzata solo se nessun BOM presente o se il file è un nuovo file.

[!NOTA]

Il BOM- rilevamento si applica solo ai file aperti in modalità Unicode; ovvero passando il flag di ccs.

Nella tabella seguente vengono riepilogate le modalità per vari flag di ccs forniti a fopen_s e per gli indicatori dell'ordine dei byte nel file.

Codifiche utilizzate basate su flag di ccs e su BOM

Flag di ccs	Nessun BOM (o nuovo file)	BOM: UTF-8	BOM: UTF-16
UNICODE	UTF-16LE	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 hanno un BOM scritto loro automaticamente.

Se mode è "a, ccs=<encoding>", fopen_s innanzitutto tenta di aprire il file sia con accesso in lettura che l'accesso in scrittura.Se eseguita correttamente, la funzione legge il BOM per determinare la codifica del file; se non riuscita, la funzione utilizza la codifica predefinita per il file.In entrambi i casi, fopen_s riaprire il file con accesso di sola scrittura.(Si applica a a la modalità solo, non a+).

Mapping di routine a Testo generico

TCHAR.H routine	_UNICODE & _MBCS non definiti	_MBCS definito	_UNICODE definito
_tfopen_s	fopen_s	fopen_s	_wfopen_s

Una stringa di caratteri mode specifica il tipo di accesso che richiesta di file, come segue.

"r"
Verrà aperto per leggere.Se il file non esiste o non è definito, la chiamata di fopen_s non riesce.
"w"
Apre un file vuoto per scrivere.Se il file esiste, il contenuto viene eliminato.
"a"
Verrà aperto per la scrittura alla fine del file aggiungere () senza rimuovere il marcatore di EOF prima di scrivere i dati nuovi al file.Crea il file se non esiste.
"r+"
Viene aperto per la lettura e scrittura.(Il file deve esistere.)
"w+"
Apre un file vuoto per la lettura e scrittura.Se il file esiste, il contenuto viene eliminato.
"a+"
Verrà aperto per la lettura e aggiungere.L'operazione di spooling comporta la rimozione del marcatore di EOF prima che i nuovi dati vengono scritti nel file e il marcatore di EOF venga ripristinato dopo la scrittura è completa.Crea il file se non esiste.

Quando un file viene aperto utilizzando il tipo di accesso di "a+" o di "a", tutte le operazioni di scrittura si verificano alla fine del file.Il puntatore del file può essere riposizionato utilizzando fseek o rewind, ma viene spostato sempre alla fine del file prima che qualsiasi operazione di scrittura si effettui non consentire sovrascrivere i dati esistenti.

La modalità di "a" non rimuove il marcatore di EOF prima di aggiungere al file.Dopo avere aggiunto si sono verificati, i dati di comando mostra il TIPO1 MS-DOS solo fino al marcatore di EOF originale e non i dati associati al file.La modalità di "a+" rimuove il marcatore di EOF prima di aggiungere al file.Dopo avere aggiunto, il comando di TIPO1 MS-DOS mostra tutti i dati nel file.La modalità di "a+" è necessario per aggiungere a un file del flusso che viene terminato mediante il marcatore di CTRL+Z EOF.

Quando "r+","w+", o il tipo di accesso di "a+" è specificato, la lettura e la scrittura sono consentite.(Il file viene aperto per "l'aggiornamento"). Tuttavia, quando si passa da lettura alla scrittura, l'operazione di input deve verificarsi un marcatore di EOF.Se non esiste alcun EOF, è necessario utilizzare una corrispondente chiamata a una funzione di posizionamento dei file.Le funzioni di posizionamento dei file sono fsetpos, fseeke rewind.Quando si passa da scrittura alla lettura, è necessario utilizzare una chiamata corrispondente a fflush o a una funzione di posizionamento dei file.

Oltre ai valori in precedenza, i caratteri seguenti possono essere inclusi in mode per specificare la modalità di conversione dei caratteri di nuova riga:

t
Aprire la modalità di testo (tradotto).In questa modalità, CTRL+Z viene interpretato come carattere di fine file di input.In aprire file per la lettura/scrittura con "a+", i controlli di fopen_s per un CTRL+Z alla fine del file e la rimozione, se possibile.Questa operazione viene eseguita perché utilizzando fseek e ftell per spostarsi all'interno di un file che termina con un CTRL+Z, può provocare fseek a comporta in modo errato alla fine del file.

Inoltre, in modalità testo, le combinazioni di ritorno a capo-avanzamento shopping vengono convertite in singoli avanzamenti riga in input e caratteri di avanzamento riga vengono tradotti alle combinazioni di ritorno a capo-avanzamento shopping in output.Quando una funzione Unicode stream-I/O viene eseguito in modalità testo (impostazione predefinita), l'origine o flusso di destinazione sia una sequenza di caratteri multibyte.Pertanto, le funzioni di flusso- input Unicode convertono i caratteri multibyte ai caratteri di tipo " wide " (ad esempio se da una chiamata alla funzione di mbtowc ).Per lo stesso motivo, le funzioni flusso- restituite Unicode convertono i caratteri di tipo " wide " per caratteri multibyte (ad esempio se da una chiamata alla funzione di wctomb ).

b
Aprire in modalità (non tradotta binaria); le conversioni che includono il ritorno a capo e caratteri di avanzamento riga eliminati.

Se t o b non è modefornito in, la modalità di traduzione predefinita definita la variabile globale _fmode.Se t o b è provvisto all'argomento, la funzione ha esito negativo e restituisce NULL.

Per ulteriori informazioni sull'utilizzo delle modalità del binario e del testo in formato Unicode e in multibyte stream-I/O, vedere La modalità binario e testo consente l'i/o e Flusso I/O Unicode in modalità binario e del testo.

c
Abilitare il flag di commit per filename collegata in modo da scrivere il contenuto del buffer di file direttamente su disco se fflush o _flushall viene chiamato.
n
Reimpostare il flag di commit per filename collegato "NO primary commit." Impostazione predefinita.Esegue l'override del flag globale di commit se si collega il programma con COMMODE.OBJ.L'impostazione predefinita del flag globale del commit è "privi di" a meno che in modo esplicito accede il programma con COMMODE.OBJ (vedere) Opzioni di collegamento.
N
Specifica che il file non è 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 come temporaneo.Se possibile, non viene scaricata su disco.
D
Specifica un file come temporaneo.Quando viene eliminato l'ultimo puntatore del file viene chiuso.
ccs=ENCODING
Specificare il set di caratteri codificati per utilizzare (UTF-8, UTF-16LE e UNICODE) per il file.Lasciare questo non specificato se si desidera che la codifica ANSI.

I caratteri validi per la stringa di mode utilizzata in fopen_s e in _fdopen corrispondono agli argomenti di oflag utilizzati in _open e in _sopen, come segue.

Caratteri della stringa in modalità	Valore equivalente di oflag 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
c	Nessuno
n	Nessuno
S	_O_SEQUENTIAL
R	_O_RANDOM
T	_O_SHORTLIVED
D	_O_TEMPORARY
ccs=UNICODE	_O_WTEXT
ccs=UTF-8	_O_UTF8
ccs=UTF-16LE	_O_UTF16

Se si utilizza la modalità di rb, non sarà necessario trasferire il codice e si desidera leggere da file e/o non è necessario per le prestazioni di rete, i file mappati memoria Win32 può essere un'opzione.

Requisiti

Funzione	Intestazione obbligatoria
fopen_s	<stdio.h>
_wfopen_s	<stdio.h> o <wchar.h>

Per ulteriori informazioni sulla compatibilità, vedere Compatibilità nell'introduzione.

Librerie

Tutte le versioni delle Librerie di runtime C.

c, ne le opzioni di tmode sono estensioni Microsoft per fopen_s e _fdopen e non devono essere utilizzati in cui la portabilità ANSI viene desiderata.

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" does not 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+" );
   if( err == 0 )
   {
      printf( "The file 'data2' was opened\n" );
   }
   else
   {
      printf( "The file 'data2' was not opened\n" );
   }

   // Close stream if it is not 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 );
}