fopen, _wfopen

Apre un file. Sono disponibili versioni più sicure di queste funzioni che eseguono più convalida dei parametri e restituiscono codici di errore; vedere fopen_s, _wfopen_s.

Sintassi

FILE *fopen(
   const char *filename,
   const char *mode
);
FILE *_wfopen(
   const wchar_t *filename,
   const wchar_t *mode
);

Parametri

filename
Nome del file.

mode
Tipo di accesso abilitato.

Valore restituito

Ognuna di queste funzioni restituisce un puntatore al file aperto. Un valore di puntatore Null indica un errore. Se filename o mode è o una NULL stringa vuota, queste funzioni attivano il gestore di parametri non validi, descritto in Convalida dei parametri. Se l'esecuzione può continuare, queste funzioni restituiscono NULL e impostano errno su EINVAL.

Per altre informazioni, vedereerrno, _doserrno, _sys_errliste _sys_nerr.

Osservazioni:

La fopen funzione apre il file specificato da filename. Per impostazione predefinita, una stringa stretta filename viene interpretata usando la tabella codici ANSI (CP_ACP). Nelle applicazioni desktop di Windows, può essere modificato nella tabella codici OEM (CP_OEMCP) usando la SetFileApisToOEM funzione . È possibile usare la AreFileApisANSI funzione per determinare se filename viene interpretato usando l'ANSI o la tabella codici OEM predefinita del sistema. _wfopen è una versione a caratteri wide di fopen. Gli _wfopen argomenti sono stringhe di caratteri wide. In caso contrario, _wfopen e fopen si comportano in modo identico. L'uso _wfopen di non influisce sul set di caratteri codificato usato nel flusso di file.

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

Controllare sempre il valore restituito per verificare se il puntatore è NULL prima di eseguire altre operazioni sul file. Se si verifica un errore, la variabile globale viene impostata errno e può essere usata per ottenere informazioni specifiche sull'errore. 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 supporta flussi di file di Unicode. Per aprire un file Unicode, passare un flag ccs=encoding che specifica la codifica voluta a fopen, come segue.

FILE *fp = fopen("newfile.txt", "rt+, ccs=UTF-8");

I valori consentiti per la ccs codifica sono UNICODE, UTF-8e UTF-16LE.

Quando un file viene aperto in modalità Unicode, le funzioni di input traducono i dati letti dal file in dati UTF-16 archiviati come tipo wchar_t. Le funzioni che scrivono in un file aperto in modalità Unicode prevedono buffer contenenti dati UTF-16 archiviati come tipo wchar_t. Se il file viene codificato come UTF-8, i dati UTF-16 vengono convertiti in UTF-8 quando vengono scritti. Il contenuto con codifica UTF-8 del file viene convertito in UTF-16 quando viene letto. Un tentativo di lettura o scrittura di un numero dispari di byte in modalità Unicode causerà un errore di convalida del parametro . Per leggere o scrivere dati archiviati nel programma come UTF-8, usare una modalità file di testo o binaria al posto della modalità Unicode. L'utente è responsabile di qualsiasi traduzione di codifica necessaria.

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

Nota

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

Nella tabella seguente vengono riepilogate le modalità usate per vari flag ccs forniti a fopen e agli indicatori per l'ordine dei byte nel file.

Codifiche usate in base al flag ccs 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-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 dispongono di un indicatore ordine byte scritto automaticamente in tali file.

Se mode è a, ccs=encoding per un encoding valore, fopen tenta prima di tutto di aprire il file usando sia l'accesso in lettura che in scrittura. Se l'azione ha esito positivo, la funzione legge la distinta base per determinare la codifica per il file. Se ha esito negativo, la funzione usa la codifica predefinita per il file. In entrambi i casi, fopen riapre il file usando l'accesso in sola scrittura. Questo comportamento si applica solo alla "a" modalità, non alla "a+" modalità.

Mapping di routine di testo generico

TCHAR.H Routine	_UNICODE e _MBCS non definito	_MBCS Definito	_UNICODE Definito
_tfopen	fopen	fopen	_wfopen

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

mode	Accesso
"r"	Viene aperto per la lettura. Se il file non esiste o non è stato trovato, la fopen 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 usando il tipo di accesso "a" o il tipo di accesso "a+" , tutte le operazioni di scrittura si verificano 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 dell'esecuzione di qualsiasi operazione di scrittura. Di conseguenza, i dati esistenti non possono essere sovrascritti.

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

Quando il tipo di accesso "r+", "w+"o "a+" viene specificato, sono consentite sia la lettura che la scrittura (il file viene definito aperto per "l'aggiornamento"). Tuttavia, quando si passa dalla lettura alla scrittura, l'operazione di input deve rilevare un marcatore EOF. Se non è presente alcun EOF, è necessario usare una chiamata intermedia a una funzione di posizionamento dei file. Le funzioni di posizionamento dei file sono fsetpos, fseeke rewind. Quando si passa dalla scrittura alla lettura, è necessario usare una nuova chiamata a fflush o a una funzione di posizionamento dei file.

Oltre ai valori iniziali, è possibile aggiungere i caratteri seguenti a 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. Inoltre, CTRL+Z viene interpretato nell'input come carattere di fine file.
b	Apri in modalità binaria (non tradotta); le traduzioni che coinvolgono caratteri ritorno a capo e avanzamento riga vengono eliminate.

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

In modalità testo, le combinazioni di ritorno a capo del feed di 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. Di conseguenza, le funzioni Unicode di input flusso convertono i caratteri multibyte in caratteri "wide", come se fosse una chiamata alla funzione mbtowc . 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 su come usare le modalità di testo e binario 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.

È possibile aggiungere le opzioni seguenti a per specificare mode altri comportamenti.

mode Modificatore	Comportamento
x	Forza l'esito negativo della funzione se filename esiste già. Può essere usato solo con gli identificatori "w" o "w+".
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 inoltre l'override del flag commit globale se il programma viene collegato a COMMODE.OBJ. Il flag di commit globale predefinito è "no-commit", a meno che non si collega esplicitamente il programma a 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=encoding	Specifica il set di caratteri codificato da utilizzare (uno di UTF-8, UTF-16LEo UNICODE) per questo file. Lasciare non specificato se si vuole la codifica ANSI. Questo flag è separato dai flag che lo precedono da una virgola (,). Ad esempio: FILE *f = fopen("newfile.txt", "rt+, ccs=UTF-8");

Caratteri validi per la mode stringa usata in fopen e _fdopen corrispondono agli oflag argomenti usati in _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)
x	_O_EXCL
c	None
n	None
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 usi rb la modalità, non devi convertire il codice e se prevedi di leggere la maggior parte di un file di grandi dimensioni o non ti preoccupi delle prestazioni di rete, potresti anche considerare se usare i file Win32 mappati alla memoria come opzione.

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.

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

Requisiti

Funzione	Intestazione obbligatoria
fopen	<stdio.h>
_wfopen	<stdio.h> oppure <wchar.h>

_wfopen è un'estensione Microsoft. Per altre informazioni sulla compatibilità, vedere Compatibilità.

Le copzioni , tn, SR, , T, e Dmode sono estensioni Microsoft per e _fdopen e non devono essere usate in fopen base alle esigenze di portabilità ANSI.

Esempio 1

Il seguente programma apre due file. Usa fclose per chiudere il primo file e _fcloseall per chiudere tutti i file rimanenti.

// crt_fopen.c
// compile with: /W3
// 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 )
{
   int numclosed;

   // Open for read (will fail if file "crt_fopen.c" does not exist)
   if( (stream  = fopen( "crt_fopen.c", "r" )) == NULL ) // C4996
   // Note: fopen is deprecated; consider using fopen_s instead
      printf( "The file 'crt_fopen.c' was not opened\n" );
   else
      printf( "The file 'crt_fopen.c' was opened\n" );

   // Open for write
   if( (stream2 = fopen( "data2", "w+" )) == NULL ) // C4996
      printf( "The file 'data2' was not opened\n" );
   else
      printf( "The file 'data2' was opened\n" );

   // Close stream if it is not NULL
   if( stream)
   {
      if ( fclose( stream ) )
      {
         printf( "The file 'crt_fopen.c' was not closed\n" );
      }
   }

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

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

Esempio 2

Il seguente programma crea un file (o ne sovrascrive uno se esistente), in modalità testo con codifica Unicode. Scrive quindi due stringhe nel file e chiude il file. L'output è un file denominato _wfopen_test.xml, che contiene i dati della sezione di output.

// crt__wfopen.c
// compile with: /W3
// This program creates a file (or overwrites one if
// it exists), in text mode using Unicode encoding.
// It then writes two strings into the file
// and then closes the file.

#include <stdio.h>
#include <stddef.h>
#include <stdlib.h>
#include <wchar.h>

#define BUFFER_SIZE 50

int main(int argc, char** argv)
{
    wchar_t str[BUFFER_SIZE];
    size_t  strSize;
    FILE*   fileHandle;

    // Create an the xml file in text and Unicode encoding mode.
    if ((fileHandle = _wfopen( L"_wfopen_test.xml",L"wt+,ccs=UNICODE")) == NULL) // C4996
    // Note: _wfopen is deprecated; consider using _wfopen_s instead
    {
        wprintf(L"_wfopen failed!\n");
        return(0);
    }

    // Write a string into the file.
    wcscpy_s(str, sizeof(str)/sizeof(wchar_t), L"<xmlTag>\n");
    strSize = wcslen(str);
    if (fwrite(str, sizeof(wchar_t), strSize, fileHandle) != strSize)
    {
        wprintf(L"fwrite failed!\n");
    }

    // Write a string into the file.
    wcscpy_s(str, sizeof(str)/sizeof(wchar_t), L"</xmlTag>");
    strSize = wcslen(str);
    if (fwrite(str, sizeof(wchar_t), strSize, fileHandle) != strSize)
    {
        wprintf(L"fwrite failed!\n");
    }

    // Close the file.
    if (fclose(fileHandle))
    {
        wprintf(L"fclose failed!\n");
    }
    return 0;
}

Vedi anche

I/O di flusso
Interpretazione di sequenze di caratteri multibyte
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode
_sopen, _wsopen