fopen_s, _wfopen_s

Article
06/09/2015

Ouvre un fichier. Ces versions de fopen, _wfopen ont des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le CRT.

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

[out]pFile
Pointeur vers le pointeur de fichier qui reçoit le pointeur vers le fichier ouvert.
[in]filename
Nom de fichier.
[in]mode
Type d'accès autorisé.

Valeur de retour

Zéro si l'opération réussit ; un code d'erreur en cas d'échec. Voir errno, _doserrno, _sys_errlist et _sys_nerrPour plus d'informations sur ces codes d'erreur.

Conditions d'erreur

pFile	filename	mode	Valeur de retour	Contenu depFile
NULL	n'importe quel	n'importe quel	EINVAL	inchangé
n'importe quel	NULL	n'importe quel	EINVAL	inchangé
n'importe quel	n'importe quel	VALEUR NULL	EINVAL	inchangé

Notes

Fichiers qui sont ouverts par fopen_set _wfopen_sne sont pas partageable. Si vous avez besoin qu'un fichier est partageable, utilisez _fsopen, _wfsopenavec la constante appropriée de mode partage — par exemple, _SH_DENYNOpour le partage en lecture-écriture.

Le fopen_sfonction ouvre le fichier qui est spécifié par filename. _wfopen_sest une version à caractère élargi de fopen_s; les arguments de _wfopen_ssont des chaînes de caractères larges. _wfopen_set fopen_sse comportent de manière identique dans le cas contraire.

fopen_saccepte les chemins d'accès valides sur le système de fichiers au moment de l'exécution ; Les chemins qui impliquent des lecteurs réseau mappés et les chemins d'accès UNC sont acceptés par fopen_stant que le système qui exécute le code a accès au partage ou lecteur réseau mappé au moment de l'exécution. Lors de la construction de chemins d'accès de fopen_s, ne pas faire d'hypothèses sur la disponibilité de lecteurs, de chemins d'accès, ou les partages du réseau dans l'environnement d'exécution. Vous pouvez utiliser des barres obliques (/) ou barres obliques inverses (\) comme séparateur de répertoire dans un chemin d'accès.

Ces fonctions valident leurs paramètres. Si pFile, filename, ou modeest un pointeur null, ces fonctions génèrent une exception de paramètre non valide, comme décrit dans Validation de paramètre.

Toujours vérifier la valeur de retour pour voir si la fonction a réussi avant d'effectuer toute opération ultérieure sur le fichier. Si une erreur se produit, le code d'erreur est renvoyé et la variable globale errnoa. Pour plus d'informations, consultez errno, _doserrno, _sys_errlist et _sys_nerr.

Prise en charge Unicode

fopen_sprend en charge les flux de fichiers Unicode. Pour ouvrir un fichier Unicode nouveau ou existant, transmettez une ccsindicateur qui spécifie l'encodage souhaité pour fopen_s:

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

Autorisé des valeurs de encodingsont UNICODE, UTF-8, et UTF-16LE. Si il aucune valeur n'est spécifiée pour encoding, fopen_sutilise le codage ANSI.

Si le fichier existe déjà et est ouvert pour la lecture ou de l'ajout, l'octet BOM (Order Mark), s'il est présent dans le fichier, détermine le codage. Le codage de la nomenclature est prioritaire sur l'encodage qui est spécifié par le ccsindicateur. Le ccsde codage est utilisé uniquement lorsque aucune marque n'est présent ou si le fichier est un fichier.

Notes

Détection de nomenclature s'applique uniquement aux fichiers qui sont ouverts en mode Unicode ; Autrement dit, en passant par le ccsindicateur.

Le tableau suivant résume les modes pour différents ccsindicateurs qui sont accordées aux fopen_set pour les marques d'ordre octet dans le fichier.

Codages utilisés selon ccs indicateur et la nomenclature

ccsindicateur	Aucune nomenclature (ou nouveau fichier)	NOMENCLATURE : UTF-8	NOMENCLATURE : 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

Fichiers qui sont ouverts pour l'écriture en mode Unicode ont une nomenclature écrite automatiquement.

Si modeest «a, ccs=<encoding>", fopen_sessaie d'abord d'ouvrir le fichier avec accès en lecture et en écriture. Si l'opération réussit, la fonction lit la nomenclature afin de déterminer l'encodage du fichier ; en cas d'échec, la fonction utilise le codage par défaut pour le fichier. Dans les deux cas, fopen_sOuvrir à nouveau le fichier en écriture seule. (Cela s'applique aux an'est pas unique, le mode a+.)

Mappages de Routine de texte générique

TCHAR.Routine H	_UNICODE & _MBCS non défini	_MBCS défini	_UNICODE défini
_tfopen_s	fopen_s	fopen_s	_wfopen_s

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

"r"
S'ouvre en mode lecture. Si le fichier n'existe pas ou est introuvable, la fopen_sappeler défaillance.
"w"
Ouvre un fichier vide pour l'écriture. Si le fichier existe, son contenu est détruit.
"a"
S'ouvre en écriture à la fin du fichier (joindre) sans supprimer le marqueur EOF avant d'écrire les nouvelles données 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 modifier. L'opération d'ajout comprend la suppression du marqueur EOF avant que les nouvelles données sont écrites dans le fichier et le marqueur EOF est restauré une fois l'écriture terminée. Crée le fichier s'il n'existe pas.

Lorsqu'un fichier est ouvert à l'aide de le "a"ou "a+"accéder à type, toutes les opérations ont lieu à la fin du fichier d'écriture. Le pointeur de fichier peut être repositionné à l'aide de fseekou rewind, mais il est toujours déplacé vers la fin du fichier avant de les écrire sont effectuées afin que les données existantes ne peuvent pas être remplacées.

Le "a"mode ne supprime pas le marqueur EOF avant de l'ajouter au fichier. Après l'ajout, la commande de TYPE MS-DOS affiche uniquement les données du marqueur EOF d'origine et pas toutes les données sont ajoutées au fichier. Le "a+"mode supprime-t-il le marqueur EOF avant de l'ajouter au fichier. Après avoir ajouté, la commande de TYPE MS-DOS affiche toutes les données dans le fichier. Le "a+"mode est nécessaire pour permettre l'ajout d'un fichier qui se termine à l'aide de l'indicateur EOF CTRL + Z.

Lors de la "r+", "w+",ou "a+"type d'accès est spécifié, en lecture et en écriture sont autorisées. (Le fichier est considéré comme ouvert « Update ».) Toutefois, lorsque vous passez de lecture à la rédaction, l'opération d'entrée doit rencontrer un marqueur EOF. S'il n'existe aucun EOF, vous devez utiliser un appel à une fonction de positionnement du fichier. Les fonctions de positionnement du fichier sont fsetpos, fseek, et rewind. Lorsque vous basculez de l'écriture à lecture, vous devez utiliser un appel à fflushou à une fonction de positionnement du fichier.

Outre les valeurs ci-dessus, les caractères suivants peuvent être inclus dans modepour spécifier le mode de traduction des caractères de saut de ligne :

t
Ouvrir au format texte (traduites) mode. Dans ce mode, CTRL + Z est interprété comme un caractère de fin de fichier en entrée. Dans les fichiers ouverts en mode lecture/écriture avec "a+", fopen_srecherche un CTRL + Z à la fin du fichier et le supprime, si possible. Cela est fait à l'aide de fseeket ftellpour vous déplacer dans un fichier qui se termine par un CTRL + Z, peut provoquer fseekpour fonctionner correctement à la fin du fichier.

Également en mode texte, combinaisons argument de transport sont traduites en sauts de ligne unique à l'entrée et les caractères de saut de ligne sont convertis en combinaisons argument de transport en sortie. Lorsqu'une fonction d'e/S de flux de données Unicode fonctionne en mode texte (par défaut), la source ou flux de destination est supposé pour être une séquence de caractères codés sur plusieurs octets. Par conséquent, les fonctions de flux d'entrée Unicode convertissent des caractères codés sur plusieurs octets en caractères étendus (comme si par un appel à la mbtowcfonction). Pour la même raison, les fonctions de sortie de flux de données Unicode pour convertir les caractères étendus à des caractères codés sur plusieurs octets (comme si par un appel à la wctombfonction).

b
Ouvrir dans le mode binaire (non traduit) ; traductions de caractères de retour chariot et saut de ligne sont supprimées.

Si tou bn'est pas spécifié mode, le mode de conversion par défaut est défini par la variable globale _fmode. Si tou best préfixé à l'argument, la fonction échoue et retourne NULL.

Pour plus d'informations sur l'utilisation des modes texte et binaires dans Unicode et codés sur plusieurs octets flux e/S, consultez e/s de fichier en Mode binaire et de texte et E/s de flux de données Unicode en mode binaire et de texte.

c
Activer l'indicateur de validation pour le filenameafin que le contenu de la mémoire tampon du fichier est écrites directement sur le disque si fflushou _flushallest appelée.
n
Réinitialiser l'indicateur de validation pour le filenameà « sans engagement. » Il s'agit de la 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 d'indicateur global de validation est « sans engagement » sauf si vous liez votre programme avec COMMODE d'explicitement.OBJ (voir Options de lien).
N
Spécifie que le fichier n'est pas hérité par les processus enfants.
S
Spécifie que la mise en cache est optimisé pour, mais pas limité à un accès séquentiel à partir du disque.
R
Spécifie que la mise en cache est optimisé pour, mais pas limité à un accès aléatoire à partir du disque.
T
Spécifie un fichier en tant que fichier temporaire. Dans la mesure du possible, il n'est pas vidé sur le disque.
D
Spécifie un fichier en tant que fichier temporaire. Il est supprimé lorsque le dernier pointeur de fichier est fermé.
ccs=ENCODING
Spécifiez le caractère codé pour utiliser (UTF-8, UTF-16LE et UNICODE) pour ce fichier. Laissez ce n'est pas spécifié si vous souhaitez que le codage ANSI.

Les caractères valides pour les modechaîne utilisée dans les fopen_set _fdopencorrespondent aux oflagarguments utilisés dans les _open et _sopen, comme suit.

Caractères dans la chaîne de mode	Équivalent oflagvaleur de _open/_sopen
a	_O_WRONLY \| _O_APPEND(en général_O_WRONLY \| _O_CREAT \|_O_APPEND)
a+	_O_RDWR \| _O_APPEND(en général_O_RDWR \| _O_APPEND \| _O_CREAT )
r	_O_RDONLY
r+	_O_RDWR
w	_O_WRONLY(en général_O_WRONLY \|_O_CREAT \| _O_TRUNC)
w+	_O_RDWR(en général_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 rbmode, ne sont pas nécessaires pour votre code de port et s'attendent à lire un grand nombre de fichier et/ou peu sur les performances du réseau, les fichiers mappés en mémoire Win32 peuvent également être une option.

Configuration requise

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

Pour plus d'informations de compatibilité supplémentaires, consultez compatibilité dans l'Introduction.

Bibliothèques

Toutes les versions de la les bibliothèques Runtime C.

Le c, n, et t modeoptions sont des extensions Microsoft fopen_set _fdopenet ne doit pas être utilisé lorsque la portabilité ANSI est souhaitée.

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" does not 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+" );
   if( err == 0 )
   {
      printf( "The file 'data2' was opened\n" );
   }
   else
   {
      printf( "The file 'data2' was not opened\n" );
   }

   // Close stream if it is not 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 );
}