fopen, _wfopen

Ouvre un fichier. Des versions plus sécurisées de ces fonctions qui effectuent davantage de validation des paramètres et de codes d’erreur de retour sont disponibles ; voir fopen_s, _wfopen_s.

Syntaxe

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
Genre d'accès qui est activé.

Valeur retournée

Chacune de ces fonctions retourne un pointeur vers le fichier ouvert. Une valeur de pointeur null indique une erreur. Si filename ou mode est ou une NULL chaîne vide, ces fonctions déclenchent le gestionnaire de paramètres non valide, qui est décrit dans la validation des paramètres. Si l'exécution est autorisée à se poursuivre, ces fonctions retournent NULL et définissent errno avec la valeur EINVAL.

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

Notes

La fopen fonction ouvre le fichier spécifié par filename. Par défaut, une chaîne étroite filename est interprétée à l’aide de la page de codes ANSI (CP_ACP). Dans les applications de bureau Windows, il peut être remplacé par la page de codes OEM (CP_OEMCP) à l’aide de la SetFileApisToOEM fonction. Vous pouvez utiliser la AreFileApisANSI fonction pour déterminer si filename elle est interprétée à l’aide de l’ANSI ou de la page de codes OEM par défaut du système. _wfopen est une version à caractères larges de fopen; les _wfopen arguments sont des chaînes à caractères larges. Sinon, _wfopen et fopen se comportent de la même façon. L’utilisation _wfopen n’affecte pas le jeu de caractères codé utilisé dans le flux de fichiers.

fopen accepte les chemins d'accès valides sur le système de fichiers au point d'exécution ; fopen accepte les chemins UNC et les chemins d'accès qui impliquent des lecteurs réseau mappés 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 créez des chemins d’accès pour fopen, assurez-vous que les lecteurs, les chemins ou les partages réseau sont disponibles dans l’environnement d’exécution. Vous pouvez utiliser des barres obliques (/) ou des barres obliques inverses (\) comme séparateurs de répertoires dans un chemin d’accès.

Toujours case activée la valeur de retour pour voir si le pointeur a la valeur NULL avant d’effectuer d’autres opérations sur le fichier. Si une erreur se produit, la variable errno globale est définie et peut être utilisée pour obtenir des informations d’erreur spécifiques. Pour plus d'informations, voir errno, _doserrno, _sys_errlist et _sys_nerr.

Par défaut, l’état global de cette fonction est limité à l’application. Pour le modifier, consultez l’état global dans le CRT.

Prise en charge d’Unicode

fopen prend en charge les flux de fichiers Unicode. Pour ouvrir un fichier Unicode, passez un indicateur ccs=encoding qui spécifie l'encodage souhaité à fopen, comme suit.

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

Les valeurs autorisées pour l’encodage ccs sont UNICODE, UTF-8et UTF-16LE.

Quand un fichier est ouvert en mode Unicode, les fonctions d'entrée traduisent les données qui sont lues à partir du fichier en données UTF-16 stockées comme type wchar_t. Les fonctions qui écrivent dans un fichier ouvert en mode Unicode attendent des mémoires tampons qui contiennent des données UTF-16 stockées comme type wchar_t. Si le fichier est encodé en UTF-8, les données UTF-16 sont traduites en UTF-8 lorsqu’elles sont écrites. Le contenu encodé en UTF-8 du fichier est traduit en UTF-16 lorsqu’il est lu. Toute tentative de lecture ou d'écriture d'un nombre impair d'octets en mode Unicode provoque une erreur de validation de paramètre . Pour lire ou écrire des données stockées dans votre programme au format UTF-8, utilisez un mode de fichier binaire ou texte au lieu d'un mode Unicode. Vous êtes responsable de toute traduction d’encodage requise.

Si le fichier existe déjà et est ouvert pour la lecture ou l’ajout, une marque d’ordre d’octet (BOM) dans le fichier détermine l’encodage. L’encodage boM est prioritaire sur l’encodage spécifié par l’indicateur ccs . L'encodage ccs est utilisé uniquement lorsque aucune marque BOM n'est présente ou lorsqu'il s'agit d'un nouveau fichier.

Remarque

La détection BOM s'applique uniquement aux fichiers ouverts en mode Unicode (autrement dit, en passant l'indicateur ccs ).

Le tableau suivant résume les modes utilisés pour différents indicateurs ccs donnés à fopen et les marques BOM dans le fichier.

Encodages utilisés en fonction de l’indicateur ccs et du boM

Indicateurccs	Aucune marque BOM (ou nouveau fichier)	Marque BOM : UTF-8	Marque 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

Une marque BOM est écrite automatiquement dans les fichiers ouverts pour écriture en mode Unicode.

Si mode c’est a, ccs=encoding pour une encoding valeur, fopen commencez par essayer d’ouvrir le fichier à l’aide de l’accès en lecture et en écriture. Si cette action réussit, la fonction lit le boM pour déterminer l’encodage du fichier. En cas d’échec, la fonction utilise l’encodage par défaut pour le fichier. Dans les deux cas, fopen rouvrez le fichier à l’aide d’un accès en écriture seule. (Ce comportement s’applique uniquement au "a" mode, pas au "a+" mode.)

Mappages de routine de texte générique

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

La chaîne de caractères mode spécifie le genre d'accès demandé pour le fichier, comme suit.

mode	Access
"r"	Ouvre pour l'accès en lecture. Si le fichier n’existe pas ou est introuvable, l’appel fopen échoue.
"w"	Ouvre un fichier vide pour l'accès en écriture. Si le fichier spécifié existe, son contenu est détruit.
"a"	S'ouvre pour écriture à la fin du fichier (ajout) sans supprimer le marqueur de fin de fichier (EOF) avant que de nouvelles données soient écrites dans le fichier. Crée le fichier s'il n'existe pas.
"r+"	Ouvre pour l'accès en lecture et en écriture. Le fichier doit exister.
"w+"	Ouvre un fichier vide pour l'accès en lecture et en écriture. Si le fichier existe, son contenu est détruit.
"a+"	S'ouvre pour lecture et ajout. L'opération d'ajout inclut la suppression du marqueur EOF avant que de nouvelles données soient écrites dans le fichier. Le marqueur EOF n’est pas restauré une fois l’écriture terminée. Crée le fichier s'il n'existe pas.

Lorsqu'un fichier est ouvert en utilisant le type d'accès "a" ou le type d'accès "a+" , toutes les opérations d'écriture ont lieu à la fin du fichier. Le pointeur du fichier peut être repositionné à l'aide de fseek ou de rewind, mais il est toujours replacé à la fin du fichier avant toute opération d'écriture. Par conséquent, les données existantes ne peuvent pas être remplacées.

Le "a" mode ne supprime pas le marqueur EOF avant qu’il ne soit ajouté au fichier. Après l'ajout, la commande MS-DOS TYPE affiche uniquement les données jusqu'au marqueur EOF d'origine, et non les données ajoutées au fichier. Avant d'ajouter des données au fichier, le mode "a+" ne supprime pas le marqueur EOF. Après l'ajout, la commande MS-DOS TYPE affiche toutes les données du fichier. Le "a+" mode est requis pour l’ajout à un fichier de flux qui est arrêté avec leCTRL+ marqueur Z EOF.

Quand le type d'accès "r+", "w+"ou "a+" est spécifié, la lecture et l'écriture sont autorisées (on dit que le fichier est ouvert pour « mise à jour »). Toutefois, lorsque vous basculez de la lecture à l'écriture, l'opération d'entrée doit rencontrer un marqueur EOF. S’il n’y a pas d’EOF, vous devez utiliser un appel intermédiaire à une fonction de positionnement de fichier. Les fonctions de positionnement de fichier sont fsetpos, fseeket rewind. Lorsque vous basculez de l'écriture à la lecture, vous devez utiliser un appel à fflush ou à une fonction de positionnement de fichier.

Outre les valeurs précédentes, les caractères suivants peuvent être ajoutés à mode pour spécifier le mode de traduction des caractères de nouvelle ligne.

mode Modificateur	Mode de traduction
t	Ouvrir en mode texte (traduit). Les combinaisons de saut de ligne de retour chariot (CR-LF) sont traduites en flux de ligne simples (LF) sur les entrées et les caractères LF sont traduits en combinaisons CR-LF en sortie. De même, Ctrl+Z est interprété comme un caractère de fin de fichier en entrée.
b	Ouvrez en mode binaire (non traduit) ; les traductions impliquant des caractères de retour chariot et de saut de ligne sont supprimées.

En mode texte, CTRL+Z est interprété comme un caractère EOF en entrée. Dans les fichiers ouverts pour la lecture/écriture à l’aide "a+"de , fopen case activée s pour un CTRL+Z à la fin du fichier et le supprime, s’il est possible. Elle est supprimée, car l’utilisation fseek et ftell le déplacement dans un fichier qui se termine+CTRL par Z peuvent entraîner fseek un comportement incorrect à proximité de la fin du fichier.

En mode texte, les combinaisons de flux de retour chariot (CRLF) sont traduites en caractères de flux de ligne unique (LF) lors de l’entrée, et les caractères LF sont traduits en combinaisons CRLF en sortie. Lorsqu'une fonction d'E/S de flux Unicode s'exécute en mode texte (comportement par défaut), on suppose que le flux source ou de destination est une séquence de caractères multioctets. Par conséquent, les fonctions d'entrée de flux Unicode convertissent les caractères multioctets en caractères larges (comme suite à un appel à la fonction mbtowc ). Pour la même raison, les fonctions de flux de sortie Unicode convertissent les caractères larges en caractères multioctets (comme suite à un appel à la fonction wctomb ).

Si t la b variable globale est définie ou non, modele mode de traduction par défaut est défini par la variable _fmodeglobale. Si t ou b a l'argument comme préfixe, la fonction échoue et retourne NULL.

Pour plus d’informations sur l’utilisation des modes texte et binaire dans les E/S de flux Unicode et multioctets, consultez E/S de fichier de texte et de mode binaire et E/S de flux Unicode dans les modes texte et binaire.

Les options suivantes peuvent être ajoutées pour mode spécifier plus de comportements.

mode Modificateur	Comportement
x	Force la fonction à échouer s’il filename existe déjà. Peut uniquement être utilisé avec les spécificateurs « w » ou « w+ ».
c	Activer l'indicateur de validation pour le filename associé, afin que le contenu de la mémoire tampon de fichier soit écrit directement sur disque si fflush ou _flushall est appelé.
n	Réinitialisez l’indicateur de validation associé filename à « no-commit ». Cet indicateur est la valeur par défaut. Substitue également l'indicateur de validation global si vous liez votre programme avec COMMODE.OBJ. L’indicateur de validation global par défaut est « sans validation », sauf si vous liez explicitement votre programme à COMMODE. OBJ (voir options de lien).
N	Spécifie que le fichier n’est pas hérité par les processus enfants.
S	Indique que la mise en cache est optimisée pour, mais non limitée à, l'accès séquentiel à partir du disque.
R	Indique que la mise en cache est optimisée pour, mais non limitée à, l'accès aléatoire à partir du disque.
T	Spécifie un fichier qui n’est pas écrit sur le disque, sauf si la pression de la mémoire l’exige.
D	Spécifie un fichier temporaire supprimé lorsque le dernier pointeur de fichier vers celui-ci est fermé.
ccs=encoding	Spécifie le jeu de caractères encodé à utiliser (l’un des UTF-8fichiers , UTF-16LEou UNICODE) pour ce fichier. Laissez ce paramètre non spécifié si vous souhaitez bénéficier de l'encodage ANSI. Cet indicateur est séparé des indicateurs qui l’précèdent par une virgule (,). Par exemple : FILE *f = fopen("newfile.txt", "rt+, ccs=UTF-8");

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

Caractères dans la chaîne mode	Valeur oflag équivalente 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 (traduit)
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

Si vous utilisez rb le mode, vous n’avez pas besoin de porter votre code et si vous prévoyez de lire la plupart d’un fichier volumineux ou ne vous inquiétez pas des performances réseau, vous pouvez également envisager d’utiliser des fichiers Win32 mappés en mémoire comme option.

En ce qui concerne T et D:

• T évite d’écrire le fichier sur le disque tant que la pression de la mémoire ne le nécessite pas. Pour plus d’informations, consultez FILE_ATTRIBUTE_TEMPORARY les constantes d’attributs de fichier et ce billet de blog uniquement temporaire.
• D spécifie un fichier standard écrit sur le disque. La différence est qu’elle est automatiquement supprimée lorsqu’elle est fermée. Vous pouvez combiner TD pour obtenir les deux sémantiques.

Les cextensions , , SRt, n, T, et Dmode les options Microsoft sont pour fopen et _wfopen ne doivent pas être utilisées lorsque vous souhaitez la portabilité ANSI.

Spécifications

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

_wfopen est une extension Microsoft. Pour plus d'informations sur la compatibilité, consultez Compatibilité.

Les cextensions Microsoft tTSnDmodeRpour fopen , _fdopen et ne doivent pas être utilisées lorsque la portabilité ANSI est souhaitée.

Exemple 1

Le programme suivant ouvre 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 );
}

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

Exemple 2

Le programme suivant crée un fichier (ou le remplace s'il existe), en mode texte avec encodage Unicode. Il écrit ensuite 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;
}

Voir aussi

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