fopen, _wfopen

Apre un file. Sono disponibili versioni più sicure di queste funzioni. Vedere fopen_s, _wfopen_s.

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

Parametri

• filename
  Nome 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 è NULL o una stringa vuota, queste funzioni attivano il gestore di parametro non valido, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, queste funzioni restituiscono NULL e impostano errno su EINVAL.

Per altre informazioni, vedere errno, _doserrno, _sys_errlist, and _sys_nerr.

Note

La funzione fopen apre il file specificato da filename. _wfopen è una versione a caratteri "wide" di fopen. Gli argomenti per _wfopen sono stringhe a caratteri "wide". In caso contrario, _wfopen e fopen si comportano in modo identico. L'uso solo di _wfopen non ha effetto sul set di caratteri codificati 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 i percorsi per fopen, assicurarsi che le unità, i percorsi o le condivisioni di rete saranno disponibili nell'ambiente di esecuzione. È possibile usare barre (/) o barre rovesciate (\) come separatori di directory in un percorso.

Controllare sempre il valore restituito per verificare se il puntatore è NULL prima di eseguire qualsiasi altra operazione sul file. Se si verifica un errore, la variabile globale errno viene impostata e può essere usata per ottenere informazioni specifiche sugli errori. Per altre informazioni, vedere errno, _doserrno, _sys_errlist, and _sys_nerr.

Supporto per Unicode

fopen supporta flussi di file di Unicode. Per aprire un file Unicode, passare un flag ccs che specifica la codifica voluta a fopen, come segue.

fopen(&fp, "newfile.txt", "rt+, ccs=encoding");

I valori consentiti di encoding sono UNICODE, UTF-8 e 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 è codificato come UTF-8, i dati UTF-16 vengono tradotti in UTF-8 alla scrittura e il contenuto del file codificato in UTF-8 viene tradotto in UTF-16 alla lettura. Un tentativo di leggere o scrivere 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. Eventuali traduzioni della codifica vanno gestite dall'utente.

Se il file esiste già e viene aperto per la lettura o l'aggiunta, l'indicatore ordine byte (BOM), se presente nel file, determina la codifica. La codifica dell'indicatore ordine byte ha la precedenza sulla codifica specificata dal flag ccs. 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 a flag ccs e indicatore ordine byte

Flag di ccs	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>", fopen tenta innanzitutto di aprire il file con accesso sia in lettura che in scrittura. Se questa operazione ha esito positivo, la funzione legge l'indicatore ordine byte per determinare la codifica del file. Se l'operazione non riesce, la funzione usa la codifica predefinita per il file. In entrambi i casi, fopen riaprirà quindi il file con accesso di sola scrittura. Si applica solo alla modalità a, non alla modalità a+.

Mapping di routine di testo generico

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

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

• "r"
  Viene aperto per la lettura. Se il file non esiste o non viene trovato, la chiamata a fopen avrà esito negativo.

• "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 è inesistente.

• "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. Il marcatore EOF non viene ripristinato dopo il completamento della scrittura. Creare il file se è inesistente.

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 modalità "a" 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 modalità "a+" è necessaria per l'aggiunta a un file di flusso terminato con il marcatore EOF CTRL+Z.

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 esiste alcun EOF, è necessario usare una nuova chiamata a una funzione di posizionamento dei file. Le funzioni di posizionamento dei 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 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.

• t
  Aprire in modalità testo (convertita). In questa modalità l'input di CTRL+Z viene interpretato come carattere EOF. Nei file aperti per la lettura/scrittura tramite "a+", fopen verifica la presenza della combinazione CTRL+Z alla fine del file e la rimuove, se possibile. Questa operazione viene eseguita perché l'uso di fseek e ftell per spostarsi all'interno di un file che termina con CTRL+Z può causare un comportamento non corretto di fseek in prossimità della fine del file.

In modalità testo, le combinazioni ritorno a capo-avanzamento riga vengono convertite in singoli avanzamenti riga al momento dell'input e i caratteri di avanzamento riga vengono convertiti in combinazioni di ritorno a capo-avanzamento riga al momento dell'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. Pertanto, 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.

• b
  Aprire in modalità binaria (non convertita). Le conversioni che includono caratteri di ritorno a capo e avanzamento riga vengono eliminate.

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

Per altre informazioni su come usare le modalità binaria e di testo in formato Unicode e I/O flusso multibyte, vedere I/O file modalità testo e binaria e I/O flusso Unicode in modalità testo e binaria.

• 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 commit per filename associato su "no-commit". Questa è l'impostazione predefinita. Esegue inoltre l'override del flag commit globale se il programma viene collegato a COMMODE.OBJ. L'impostazione predefinita del flag commit globale è "no-commit", a meno che il programma venga collegato in modo esplicito a COMMODE.OBJ (vedere Opzioni 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 come temporaneo. Se possibile, non viene scaricato su disco.

• D
  Specifica un file come temporaneo. Viene eliminato quando viene chiuso l'ultimo puntatore del file.

• ccs=ENCODING
  Specifica il set di caratteri codificati da usare (UTF-8, UTF-16LE o UNICODE) per il file. Lasciare non specificato se si vuole la codifica ANSI.

I caratteri validi per la stringa mode usata in fopen e _fdopen corrispondono ad argomenti oflag usati in _open e _sopen, come segue.

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
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 usa la modalità rb, non è necessario trasferire il codice e si vuole leggere la maggior parte di un file di grandi dimensioni o le prestazioni di rete non costituiscono un problema, è inoltre consigliabile considerare se usare come opzione file Win32 mappati in memoria.

Requisiti

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

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

Le opzioni c, n, t, S, R, T e D mode sono estensioni Microsoft per fopen e _fdopen e non devono essere usate quando è richiesta la portabilità ANSI.

Esempio

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 );
}

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, contenente 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;
}

Equivalente .NET Framework

• System::IO::File::Open

• System::IO::FileStream::FileStream

Vedere anche

Riferimenti

I/O di flusso

Interpretazione di sequenze di caratteri multibyte

fclose, _fcloseall

_fdopen, _wfdopen

ferror

_fileno

freopen, _wfreopen

_open, _wopen

_setmode

_sopen, _wsopen