fopen_s, _wfopen_s

Ouvre un fichier. Ces versions ont des améliorations de fopen_wfopensécurité, comme décrit dans les fonctionnalités de sécurité du CRT.

Syntaxe

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

Paramètres

pFile
Pointeur vers le pointeur de fichier qui reçoit le pointeur vers le fichier ouvert.

filename
Nom du fichier à ouvrir.

mode
Type d'accès autorisé.

Valeur retournée

Zéro si l'opération a réussi ; code d'erreur en cas de échec. Pour plus d’informations sur ces codes d’erreur, consultez , , _sys_errlist_doserrnoet _sys_nerr.errno

Conditions de l’erreur

pFile	filename	mode	Valeur de retour	Contenu de pFile
NULL	tous	tous	EINVAL	inchangé
tous	NULL	tous	EINVAL	inchangé
tous	tous	NULL	EINVAL	inchangé

Notes

Les fopen_s fonctions et _wfopen_s ne peuvent pas ouvrir un fichier pour le partage. Si vous avez besoin de partager le fichier, utilisez _fsopen ou _wfsopen utilisez la constante de mode de partage appropriée, par exemple pour _SH_DENYNO le partage en lecture/écriture.

La fopen_s fonction ouvre le fichier spécifié par filename. _wfopen_s est une version à caractères larges et fopen_s les arguments à mettre en valeur sont des chaînes à _wfopen_s caractères larges. _wfopen_s et fopen_s se comportent de façon identique, sinon.

fopen_s accepte les chemins d'accès valides sur le système de fichiers au point d'exécution ; les chemins d'accès UNC et les chemins d'accès qui impliquent des lecteurs réseau mappés sont acceptés par fopen_s du moment où le système qui exécute le code a accès au partage ou au lecteur réseau mappé au moment de l'exécution. Quand il s'agit de construire des chemins d'accès pour fopen_s, ne faites pas d'hypothèses quant à la disponibilité des lecteurs, chemins d'accès ou partages réseau 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.

Ces fonctions valident leurs paramètres. Si pFile, filenameou mode est un pointeur Null, ces fonctions génèrent une exception de paramètre non valide, comme décrit dans la validation des paramètres.

Toujours case activée la valeur de retour pour voir si la fonction a réussi avant d’effectuer d’autres opérations sur le fichier. Si une erreur se produit, le code d’erreur est retourné et la variable errno globale est définie. 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_s prend en charge les flux de fichiers Unicode. Pour ouvrir un fichier Unicode nouveau ou existant, transmettez un ccs indicateur qui spécifie l’encodage souhaité, fopen_spar exemple :

fopen_s(&fp, "newfile.txt", "w+, ccs=UNICODE");

Les valeurs autorisées de l’indicateur ccs sont UNICODE, UTF-8et UTF-16LE. Si aucune valeur n’est spécifiée pour ccs, fopen_s utilise l’encodage ANSI.

Si le fichier existe déjà et est ouvert pour la lecture ou l’ajout, la marque d’ordre d’octet (BOM), s’il est présent dans le fichier, détermine l’encodage. Le codage BOM est prioritaire sur le codage spécifié par l'indicateur ccs. Le codage ccs est utilisé uniquement quand aucune marque BOM n'est présente ou si le fichier est 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écapitule les modes des différentes ccs valeurs d’indicateur qui sont données aux fopen_s machines virtuelles dans le fichier et pour les machines virtuelles.

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

Indicateurccs	Aucune marque BOM (ou nouveau fichier)	Marque BOM : UTF-8	Marque BOM : UTF-16
UNICODE	UTF-8	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=UNICODE", "a, ccs=UTF-8"ou , ou "a, ccs=UTF-16LE", fopen_s tente d’abord d’ouvrir le fichier avec accès en lecture et accès en écriture. En cas de réussite, la fonction lit la marque BOM pour déterminer le codage du fichier ; en cas d'échec, elle utilise le codage par défaut pour le fichier. Dans les deux cas, fopen_s rouvert le fichier avec un accès en écriture seule. (Ce comportement s’applique uniquement au mode, pas a+à a .)

La chaîne de caractères mode spécifie le type 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_s é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.

Quand un fichier est ouvert en utilisant le type d'accès "a" ou "a+", toutes les opérations d'écriture se produisent à la fin du fichier. Le pointeur de fichier peut être repositionné à l’aide fseek ou rewind, mais il est toujours déplacé vers la fin du fichier avant qu’une opération d’écriture soit effectuée afin que les données existantes ne puissent pas être remplacées.

Le "a" mode ne supprime pas le marqueur EOF avant de l’ajouter au fichier. Une fois l’ajout effectué, 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. Le mode "a+" supprime le marqueur EOF avant l'ajout des données au fichier. 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.

Lorsque le type d’accès ou "a+" de "w+"lecture est spécifié, la lecture et l’écriture "r+"sont autorisées. (Le fichier est dit ouvert pour « update ». Toutefois, lorsque vous passez de la lecture à l’écriture, l’opération d’entrée doit se trouver sur un marqueur EOF. S’il n’existe aucun marqueur EOF, vous devez utiliser un appel intermédiaire à une fonction de positionnement de fichier. Les fonctions de positionnement de fichier sont fsetpos, fseek et rewind. Quand vous passez de l'écriture à la lecture, vous devez faire un appel intermédiaire à fflush ou à une fonction de positionnement de fichier.

À compter de C11, vous pouvez ajouter "x" ou "w+""w" provoquer l’échec de la fonction si le fichier existe, au lieu de le remplacer.

Outre les valeurs précédentes, les caractères suivants peuvent être inclus pour mode spécifier le mode de traduction pour les 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. Ctrl+Z est interprété comme un caractère de fin de fichier lors de l’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 (traduit), CTRL+Z est interprété comme un caractère de fin de fichier lors de l’entrée. Pour les fichiers ouverts pour la lecture/écriture avec "a+", fopen_s case activée s pour un+CTRL Z à la fin du fichier et le supprime, si possible. Elle est supprimée, car l’utilisation fseek et ftell le déplacement dans un fichier qui se termine par unCTRL+ Z peuvent entraîner fseek un comportement incorrect près de la fin du fichier.

En outre, en mode texte, les combinaisons retour chariot/flux de ligne (CRLF) sont traduites en caractères LF (Single Line Feed) sur 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. Les fonctions d’entrée de flux Unicode convertissent des caractères multioctets en caractères larges (comme s’il s’agit d’un appel à la mbtowc fonction). 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 de 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.

mode Modificateur	Comportement
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. Il remplace é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 qui est supprimé lorsque le dernier pointeur de fichier vers celui-ci est fermé.
ccs=UNICODE	Spécifie UNICODE comme jeu de caractères encodé à utiliser pour ce fichier. Laissez ce paramètre non spécifié si vous souhaitez bénéficier de l'encodage ANSI.
ccs=UTF-8	Spécifie UTF-8 comme jeu de caractères encodé à utiliser pour ce fichier. Laissez ce paramètre non spécifié si vous souhaitez bénéficier de l'encodage ANSI.
ccs=UTF-16LE	Spécifie UTF-16LE comme jeu de caractères encodé à utiliser pour ce fichier. Laissez ce paramètre non spécifié si vous souhaitez bénéficier de l'encodage ANSI.

Caractères valides pour la mode chaîne utilisée dans fopen_s et _fdopen 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)
c	None
n	None
D	_O_TEMPORARY
R	_O_RANDOM
S	_O_SEQUENTIAL
T	_O_SHORTLIVED
ccs=UNICODE	_O_WTEXT
ccs=UTF-8	_O_UTF8
ccs=UTF-16LE	_O_UTF16

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

Si vous utilisez rb le mode, les fichiers Win32 mappés en mémoire peuvent également être une option si vous n’avez pas besoin de porter votre code, vous vous attendez à lire une grande partie du fichier, ou vous ne vous souciez pas des performances réseau.

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.

Spécifications

Fonction	En-tête requis	En-tête C++
fopen_s	<stdio.h>	<cstdio>
_wfopen_s	<stdio.h> ou <wchar.h>	<cstdio>

Pour plus d’informations sur la conformité aux normes et les conventions d’affectation de noms dans la bibliothèque runtime C, consultez Compatibilité.

Mappages de routine de texte générique

<tchar.h> Routine	_UNICODE et _MBCS non défini	_MBCS Défini	_UNICODE Défini
_tfopen_s	fopen_s	fopen_s	_wfopen_s

Bibliothèques

Toutes les versions des bibliothèques Runtime C.

Exemple

// 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" doesn't 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+, ccs=UTF-8" );
   if( err == 0 )
   {
      printf( "The file 'data2' was opened\n" );
   }
   else
   {
      printf( "The file 'data2' was not opened\n" );
   }

   // Close stream if it isn't 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 );
}

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

Voir aussi

E/S de flux
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode