le fopen, _wfopen

Ouvre un fichier.Les versions sécurisées de ces fonctions sont disponibles ; consultez fopen_s, _wfopen_s.

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

Paramètres

• filename
  Nom du fichier.

• mode
  Type d'accès qui est activé.

Valeur de retour

Chacune de ces fonctions retourne un pointeur vers le fichier ouvert.Une valeur de pointeur null indique une erreur.Si filename ou mode est NULL ou une chaîne vide, ces fonctions déclenchent le gestionnaire de paramètre non valide, qui est décrit dans Validation des paramètres.Si est autorisé à l'exécution pour continuer, ces fonctions NULL de retour et affectez errno à EINVAL.

Pour plus d'informations, consultez errno, _doserrno, _sys_errlist, et _sys_nerr.

Notes

La fonction d' fopen ouvre le fichier spécifié par filename._wfopen est une version à caractère élargi d' fopen; les arguments à _wfopen sont des chaînes à caractères larges.Sinon, _wfopen et fopen se comportent de la même façon.Juste à l'aide de _wfopen n'a aucun effet sur le jeu de caractères codés utilisé dans le flux de fichiers.

fopen reçoit les chemins d'accès valides sur le système de fichiers au point de l'exécution ; fopen reçoit les chemins d'accès UNC et les chemins qui font participer les lecteurs mappés réseau tant que le système qui exécute le code a accès au partage ou au lecteur mappé au moment de l'exécution.Lorsque vous construisez des chemins d'accès pour fopen, assurez-vous que les lecteurs, les chemins, ou des partages réseau sont disponibles dans l'environnement d'exécution.Vous pouvez utiliser les barres obliques (///) ou des barres obliques inverses (\) comme séparateurs de répertoire dans un chemin d'accès.

Vérifiez toujours la valeur de retour pour voir si le pointeur est NULL avant d'exécuter une opération sur le fichier.Si une erreur se produit, la variable globale errno a la valeur et peut être utilisée pour obtenir des informations d'erreur spécifiques.Pour plus d'informations, consultez errno, _doserrno, _sys_errlist, et _sys_nerr.

Prise en charge Unicode

flux de fichiers Unicode prend en charge d'fopen .Pour ouvrir un fichier Unicode, passez une balise d' ccs qui spécifie l'encodage souhaité à fopen, comme suit.

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

Les valeurs autorisées d' encoding sont UNICODE, UTF-8, et UTF-16LE.

Si le fichier existe déjà et est ouvert pour lire ou ajouter, la marque d'ordre d'octet (BOM), s'il est présent dans le fichier, détermine l'encodage.L'encodage de BOM est prioritaire sur le codage qui est spécifié par la balise d' ccs .Encodage d' ccs est utilisé uniquement lorsque aucun BOM n'est présent ou le fichier est un fichier.

[!REMARQUE]

La détection de BOM s'applique uniquement aux fichiers qui sont en Unicode état ouvert (autrement dit, en passant la balise d' ccs ).

Le tableau suivant résume les modes utilisés pour des balises d' ccs données à fopen et aux marque d'ordre d'octet dans le fichier.

Encodages utilisés sur la balise de ccs et le BOM

Indicateur ccs	Aucun (BOM ou fichier)	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

Les fichiers ouverts pour entrer en Unicode mode ont un BOM écrit à eux automatiquement.

Si mode est « a, ccs=<encoding> », d' fopen des tests d'abord pour ouvrir le fichier avec les deux accès en lecture et en écriture.Si cette opération réussit, la fonction lit le BOM pour déterminer l'encodage du fichier ; si cela échoue, la fonction utilise l'encodage par défaut pour le fichier.Dans les deux cas, fopen rouvrira le fichier avec un accès en écriture seule.(Cela s'applique à a mode uniquement, pas au mode d' a+ .)

Mappages de routines de texte générique

Routine de TCHAR.H	_UNICODE et non définis _MBCS	_MBCS défini	_UNICODE défini
_tfopen	fopen	fopen	_wfopen

La chaîne mode spécifie le type d'accès qui est demandé pour le fichier, comme suit.

• "r"
  S'ouvre pour la lecture.Si le fichier n'existe pas ou est introuvable, l'appel d' fopen échoue.

• "w"
  Ouvre un fichier vide pour écrire.Si le fichier spécifié existe, son contenu est détruit.

• "a"
  S'ouvre pour écrire à la fin de le fichier (ajouter) sans supprimer la marque de fin de fichier (EOF) avant de nouvelles données sont écrites dans le fichier.Crée le fichier s'il n'existe pas.

• "r+"
  S'ouvre pour la lecture et l'écriture.Le fichier doit exister.

• "w+"
  Ouvre un fichier vide pour la lecture et l'écriture.Si le fichier existe, son contenu est détruit.

• "a+"
  S'ouvre pour lire et ajouter.L'opération d'ajout inclut la suppression de marqueur EOF avant de nouvelles données sont écrites dans le fichier.Marqueur EOF n'est pas restauré une fois que l'écriture soit terminé.Crée le fichier s'il n'existe pas.

Lorsqu'un fichier est ouvert à l'aide de le type d'accès d' "a" ou du type d'accès d' "a+", toutes les opérations d'écriture se produisent à la fin de le fichier.Le pointeur de fichier peut être réadressé à l'aide de fseek ou d' rewind, mais est toujours déplacé vers la fin du fichier avant qu'une opération d'écriture soit exécutée.Par conséquent, les données existantes ne peuvent pas être remplacées.

Le mode d' "a" ne supprime pas marqueur EOF avant qu'il ajoute au fichier.Après avoir ajouté s'est produit, le TYPE de commande MS-DOS affiche uniquement les données jusqu'à EOF marqueur d'origine et non les données ajoutées au fichier.Avant qu'il ajoute au fichier, le mode d' "a+" supprime marqueur EOF.Après avoir ajouté, le TYPE de commande MS-DOS affiche toutes les données dans le fichier.Le mode d' "a+" est requis pour ajouter à un fichier de flux qui a fini CTRL+Z le marqueur EOF.

Lorsque "r+", "w+", ou le type d'accès d' "a+" est spécifié, il permet la lecture et l'écriture (le fichier est dit ouvert pour « update »).Toutefois, lorsque vous basculez de la lecture à écrire, l'opération d'entrée doit rencontrer marqueur EOF.S'il n'existe aucun EOF, vous devez utiliser un appel intervenant à une fonction de positionnement de fichier.Les fonctions de positionnement de fichier sont fsetpos, fseek, et rewind.Lorsque vous basculez d'écriture à lire, vous devez utiliser un appel intervenant à fflush ou une fonction de positionnement de fichier.

Outre les valeurs précédemment, les caractères suivants peuvent être ajoutés à mode pour spécifier un en mode de traduction des caractères de saut de ligne.

• t
  Ouvrez en mode de texte (traduits).Dans ce mode, CTRL+Z est interprète comme un caractère d'EOF sur l'entrée.Dans les fichiers ouverts pour la lecture/écriture à l'aide de "a+", fopen vérifie un CTRL+Z à la fin de le fichier et le supprime, si possible.Cette opération est exécutée car l'utilisation d' fseek et d' ftell pour déplacer dans un fichier qui se termine par CTRL+Z peut faire comporter fseek correctement près de la fin de le fichier.

En mode texte, des combinaisons de saut de ligne-retour de chariot sont traduites en sauts de ligne unique sur l'entrée, et les caractères de saut de ligne sont traduits aux combinaisons de saut de ligne-retour de chariot dans la sortie.Lorsqu'une fonction Unicode stream-I/O exécute en mode texte (par défaut), la source ou il est supposé que le flux de données de destination est une séquence de caractères multioctets.Par conséquent, les fonctions de flot- entrée Unicode convertissent des caractères multioctets aux caractères larges (comme si par un appel à la fonction d' mbtowc ).Pour la même raison, les fonctions de flot- sortie Unicode convertissent des caractères larges aux caractères multioctets (comme si par un appel à la fonction d' wctomb ).

• b
  Ouvrez en mode (non traduit) binaire ; les traductions impliquant des caractères de retour chariot/saut de ligne sont supprimées.

Si t ou b n'est pas donné dans mode, à l'état de interprétation par défaut est défini par la variable globale _fmode.Si t ou b est préfixé à l'argument, la fonction échoue et retourne NULL.

Pour plus d'informations sur l'utilisation des modes de texte et binaire en Unicode et stream-I/O multioctets, consultez E/S de fichier du mode de texte et binaire et l' E/S de flux de données Unicode dans des modes de texte et binaire.

• c
  Activez la balise de validation pour filename associé afin que le contenu de la mémoire tampon de fichier est écrit directement sur le disque si fflush ou _flushall est appelé.

• n
  Réinitialisez la balise de validation pour filename associé à la « -- sans validation. » Valeur par défaut.Il substitue également l'indicateur global de validation si vous liez votre programme avec COMMODE.OBJ.La valeur par défaut globale de balise de validation est « -- sans validation » sauf si vous joindre explicitement votre programme avec COMMODE.OBJ (consultez Options de lien).

• N
  Spécifie que le fichier n'est pas héritée par les processus enfant.

• S
  Spécifie que la mise en cache est optimisé pour, mais pas limité à, un accès séquentiel à partir de le disque.

• R
  Spécifie que la mise en cache est optimisé pour, mais pas limité à, l'accès aléatoire à partir de le disque.

• T
  Spécifie un fichier comme temporaire.Si possible, il n'est pas vidé sur le disque.

• D
  Spécifie un fichier comme temporaire.Il est supprimé lorsque le dernier pointeur de fichier est fermé.

• ccs=ENCODING
  Spécifie le jeu de caractères codés à utiliser (UTF-8, UTF-16LE, ou UNICODE) pour ce fichier.Laissez pas spécifié si vous souhaitez l'encodage ANSI.

Caractères valides pour la chaîne d' mode utilisée dans fopen et _fdopen correspondent aux arguments d' oflag utilisés dans _open et _sopen, comme suit.

Caractères dans la chaîne d'état	Valeur équivalente d' oflag pour _open/_sopen
a	_O_WRONLY | _O_APPEND(généralement _O_WRONLY | _O_CREAT | _O_APPEND)
a+	_O_RDWR | _O_APPEND (généralement _O_RDWR | _O_APPEND | _O_CREAT)
r	_O_RDONLY
r+	_O_RDWR
w	_O_WRONLY (généralement _O_WRONLY | _O_CREAT | _O_TRUNC)
w+	_O_RDWR (généralement _O_RDWR | _O_CREAT | _O_TRUNC)
b	_O_BINARY
t	_O_TEXT
c	Aucun
n	Aucun
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

Si vous utilisez le mode d' rb, ne devez pas déplacer le code, et le comptez lire la majeure partie d'un fichier volumineux ou n'êtes pas préoccuper des performances réseau, vous pouvez également déterminer si l'utilisation de la mémoire avez mappé des fichiers Win32 comme option.

Configuration requise

Fonction	En-tête requis
fopen	<stdio.h>
_wfopen	<stdio.h> ou <wchar.h>

Pour plus d'informations sur la compatibilité, consultez Compatibilité.

c, n, t, S, R, T, et les options d' Dmode sont des extensions Microsoft pour fopen et _fdopen et ne doivent pas être utilisés où la portabilité ANSI est souhaitée.

Exemple

Le programme suivant affiche deux fichiers.Il utilise fclose pour fermer le premier fichier et _fcloseall pour fermer tous les fichiers restants.

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

Le programme suivant crée un fichier (ou écrasers un s'il existe), en mode texte qui a l'encodage Unicode.Il écrit deux chaînes dans le fichier et ferme le fichier.La sortie est un fichier nommé _wfopen_test.xml, qui contient les données de la section de sortie.

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

Équivalent .NET Framework

• System::IO::File::Open

• System::IO::FileStream::FileStream

Voir aussi

Référence

E/S de flux

Interprétation des séquences de caractères multioctets

fclose, _fcloseall

_fdopen, _wfdopen

ferror

_fileno

freopen, _wfreopen

_open, _wopen

_setmode

_sopen, _wsopen