Delen via

fopen_s, _wfopen_s

  • Artikel

Hiermee opent u een bestand. Deze versies van fopen, _wfopen hebben beveiligingsverbeteringen, zoals beschreven in Beveiligingsfuncties in de CRT-.

Syntaxis

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

Parameterwaarden

pFile
Een aanwijzer naar de bestandswijzer die de aanwijzer ontvangt naar het geopende bestand.

filename
De naam van het bestand dat moet worden geopend.

mode
Het type toegang is toegestaan.

Retourwaarde

Nul indien geslaagd; een foutcode bij fout. Zie errno, _doserrno, _sys_errlisten _sys_nerrvoor meer informatie over deze foutcodes.

Foutvoorwaarden

pFile filename mode Retourwaarde Inhoud van pFile
NULL enig enig EINVAL ongewijzigd
enig NULL enig EINVAL ongewijzigd
enig enig NULL EINVAL ongewijzigd

Opmerkingen

De functies fopen_s en _wfopen_s kunnen geen bestand openen voor delen. Als u het bestand wilt delen, gebruikt u _fsopen of _wfsopen met de juiste constante voor delen. Gebruik bijvoorbeeld _SH_DENYNO voor het delen van lees-/schrijfbewerkingen.

Met de functie fopen_s wordt het bestand geopend dat is opgegeven door filename. _wfopen_s is een uitgebreide versie van fopen_s en de argumenten voor _wfopen_s tekenreeksen zijn breedtekenreeksen. _wfopen_s en fopen_s zich identiek gedragen, anders.

fopen_s accepteert paden die geldig zijn in het bestandssysteem op het moment van uitvoering; UNC-paden en -paden die betrekking hebben op toegewezen netwerkstations worden geaccepteerd door fopen_s zolang het systeem dat de code uitvoert, toegang heeft tot het gedeelde of toegewezen netwerkstation op het moment van uitvoering. Wanneer u paden voor fopen_smaakt, maakt u geen veronderstellingen over de beschikbaarheid van stations, paden of netwerkshares in de uitvoeringsomgeving. U kunt slashes (/) of backslashes (\) gebruiken als de adreslijstscheidingstekens in een pad.

Deze functies valideren hun parameters. Als pFile, filenameof mode een null-aanwijzer is, genereren deze functies een ongeldige parameter-uitzondering, zoals beschreven in parametervalidatie.

Controleer altijd de retourwaarde om te zien of de functie is geslaagd voordat u verdere bewerkingen op het bestand uitvoert. Als er een fout optreedt, wordt de foutcode geretourneerd en wordt de globale variabele errno ingesteld. Zie errno, _doserrno, _sys_errlisten _sys_nerrvoor meer informatie.

De globale status van deze functie is standaard gericht op de toepassing. Zie Globale status in de CRT-om deze te wijzigen.

Unicode-ondersteuning

fopen_s ondersteunt Unicode-bestandsstromen. Als u een nieuw of bestaand Unicode-bestand wilt openen, geeft u een ccs vlag door die de gewenste codering opgeeft aan fopen_s, bijvoorbeeld:

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

Toegestane waarden van de vlag ccs zijn UNICODE, UTF-8en UTF-16LE. Als er geen waarde is opgegeven voor ccs, gebruikt fopen_s ANSI-codering.

Als het bestand al bestaat en wordt geopend voor lezen of toevoegen, bepaalt de bytevolgordemarkering (BOM), indien aanwezig in het bestand, de codering. De bomcodering heeft voorrang op de codering die is opgegeven door de vlag ccs. De ccs codering wordt alleen gebruikt wanneer er geen stuklijst aanwezig is of als het bestand een nieuw bestand is.

Notitie

BOM-detectie is alleen van toepassing op bestanden die zijn geopend in unicode-modus; Dat wil gezegd, door de ccs vlag door te geven.

De volgende tabel bevat een overzicht van de modi voor verschillende ccs vlagwaarden die worden gegeven aan fopen_s en voor BOM's in het bestand.

Coderingen die worden gebruikt op basis van ccs vlag en bom

ccs vlag Geen bom (of nieuw bestand) BOM: UTF-8 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

Bestanden die worden geopend voor schrijven in de Unicode-modus, hebben automatisch een stuklijst naar deze bestanden geschreven.

Als mode is "a, ccs=UNICODE", "a, ccs=UTF-8"of "a, ccs=UTF-16LE", probeert fopen_s eerst het bestand te openen met zowel leestoegang als schrijftoegang. Als dit lukt, leest de functie de bom om de codering voor het bestand te bepalen; als dit niet lukt, gebruikt de functie de standaardcodering voor het bestand. In beide gevallen opent fopen_s het bestand vervolgens opnieuw met alleen-schrijventoegang. (Dit gedrag geldt alleen voor a modus, niet a+.)

De tekenreeks mode geeft als volgt het type toegang op dat voor het bestand wordt aangevraagd.

mode Toegang
"r" Wordt geopend voor lezen. Als het bestand niet bestaat of niet kan worden gevonden, mislukt de fopen_s aanroep.
"w" Hiermee opent u een leeg bestand voor schrijven. Als het opgegeven bestand bestaat, wordt de inhoud ervan vernietigd.
"a" Wordt geopend voor schrijven aan het einde van het bestand (toevoegen) zonder de EOF-markering (end-of-file) te verwijderen voordat nieuwe gegevens naar het bestand worden geschreven. Hiermee maakt u het bestand als het niet bestaat.
"r+" Wordt geopend voor zowel lezen als schrijven. Het bestand moet bestaan.
"w+" Hiermee opent u een leeg bestand voor zowel lezen als schrijven. Als het bestand bestaat, wordt de inhoud ervan vernietigd.
"a+" Wordt geopend voor lezen en toevoegen. De toevoegbewerking omvat het verwijderen van de EOF-markering voordat nieuwe gegevens naar het bestand worden geschreven. De EOF-markering wordt niet hersteld nadat het schrijven is voltooid. Hiermee maakt u het bestand als het niet bestaat.

Wanneer een bestand wordt geopend met behulp van het "a" of "a+" toegangstype, vinden alle schrijfbewerkingen plaats aan het einde van het bestand. De bestandspointer kan worden verplaatst met behulp van fseek of rewind, maar wordt altijd teruggezet naar het einde van het bestand voordat een schrijfbewerking wordt uitgevoerd, zodat bestaande gegevens niet kunnen worden overschreven.

De "a" modus verwijdert de EOF-markering niet voordat u het bestand toevoegt. Nadat het toevoegen is opgetreden, worden met de opdracht MS-DOS TYPE alleen gegevens weergegeven tot de oorspronkelijke EOF-markering en geen gegevens die aan het bestand zijn toegevoegd. De "a+"-modus verwijdert de EOF-markering voordat u het bestand toevoegt. Na het toevoegen worden met de opdracht MS-DOS TYPE alle gegevens in het bestand weergegeven. De "a+" modus is vereist voor het toevoegen aan een stroombestand dat is beëindigd met de markering CTRL+Z EOF.

Wanneer de "r+", "w+"of "a+" toegangstype is opgegeven, zijn zowel lezen als schrijven toegestaan. (Het bestand is geopend voor 'update'.) Wanneer u echter overschakelt van lezen naar schrijven, moet de invoerbewerking een EOF-markering tegenkomen. Als er geen EOF-markering is, moet u een tussenliggende aanroep naar een functie voor bestandspositionering gebruiken. De bestandspositioneringsfuncties zijn fsetpos, fseeken rewind. Wanneer u overschakelt van schrijven naar lezen, moet u een tussenliggende aanroep gebruiken naar fflush of naar een functie voor bestandspositionering.

Vanaf C11 kunt u "x" toevoegen aan "w" of "w+" om de functie te laten mislukken als het bestand bestaat, in plaats van het te overschrijven.

Naast de vorige waarden kunnen de volgende tekens worden opgenomen in mode om de vertaalmodus voor newlinetekens op te geven:

mode modifier Vertaalmodus
t Openen in de tekstmodus (vertaald). Combinaties van regelterugloopinvoer (CR-LF) worden omgezet in één regelfeeds (LF) op invoer en LF-tekens worden omgezet in CR-LF combinaties op uitvoer. Ctrl+Z wordt geïnterpreteerd als een teken aan het einde van het bestand bij invoer.
b Openen in binaire (niet-vertaalde) modus; vertalingen met regelterugloop- en regelinvoertekens worden onderdrukt.

In de tekstmodus (vertaald) wordt CTRL+Z- geïnterpreteerd als een eindbestandsteken op invoer. Voor bestanden die zijn geopend voor lezen/schrijven met "a+", controleert fopen_s op een CTRL+Z- aan het einde van het bestand en verwijdert u het, indien mogelijk. Het wordt verwijderd omdat het gebruik van fseek en ftell om te verplaatsen binnen een bestand dat eindigt op een CTRL+Z, ertoe kan leiden dat fseek zich onjuist gedraagt aan het einde van het bestand.

In de tekstmodus worden crlf-combinaties (regelterugloop/regelinvoer) ook omgezet in LF-tekens (single line feed) voor invoer en worden LF-tekens vertaald naar CRLF-combinaties op uitvoer. Wanneer een Unicode-stream-I/O-functie werkt in de tekstmodus (de standaardinstelling), wordt ervan uitgegaan dat de bron- of doelstroom een reeks multibytetekens is. De Unicode-functies voor stroominvoer converteren multibyte-tekens naar brede tekens (alsof door een aanroep naar de mbtowc functie). Om dezelfde reden converteren de Unicode-stroomuitvoerfuncties brede tekens naar meerderebyte tekens (alsof door een aanroep naar de functie wctomb).

Als t of b niet wordt gegeven in mode, wordt de standaardomzettingsmodus gedefinieerd door de globale variabele _fmode. Als t of b wordt voorafgegaan door het argument, mislukt de functie en wordt NULLgeretourneerd.

Zie voor meer informatie over het gebruik van tekst en binaire modi in Unicode en multibyte stream-I/O Text and binary mode file I/O en Unicode stream I/O in tekst- en binaire modi.

mode modifier Gedrag
c Schakel de doorvoervlag in voor de gekoppelde filename, zodat de inhoud van de bestandsbuffer rechtstreeks naar de schijf wordt geschreven als fflush of _flushall wordt aangeroepen.
n Stel de doorvoervlag voor de bijbehorende filename opnieuw in op 'no-commit'. Deze vlag is de standaardwaarde. De algemene doorvoervlag wordt ook overschreven als u uw programma koppelt aan COMMODE.OBJ. De standaardinstelling voor de algemene doorvoermarkering is 'no-commit', tenzij u uw programma expliciet koppelt aan COMMODE.OBJ (zie Koppelingsopties).
N Hiermee geeft u op dat het bestand niet wordt overgenomen door onderliggende processen.
S Hiermee geeft u op dat caching is geoptimaliseerd voor, maar niet beperkt tot, sequentiële toegang vanaf schijf.
R Hiermee geeft u op dat caching is geoptimaliseerd voor, maar niet beperkt tot, willekeurige toegang vanaf schijf.
T Hiermee geeft u een bestand dat niet naar schijf wordt geschreven, tenzij geheugendruk vereist.
D Hiermee geeft u een tijdelijk bestand dat wordt verwijderd wanneer de laatste bestandswijzer naar het bestand wordt gesloten.
ccs=UNICODE Hiermee geeft u UNICODE op als de gecodeerde tekenset die moet worden gebruikt voor dit bestand. Laat niet opgegeven als u ANSI-codering wilt.
ccs=UTF-8 Hiermee geeft u UTF-8 op als de gecodeerde tekenset die moet worden gebruikt voor dit bestand. Laat niet opgegeven als u ANSI-codering wilt.
ccs=UTF-16LE Hiermee geeft u UTF-16LE op als de gecodeerde tekenset die moet worden gebruikt voor dit bestand. Laat niet opgegeven als u ANSI-codering wilt.

Geldige tekens voor de mode tekenreeks die wordt gebruikt in fopen_s en _fdopen komen als volgt overeen met oflag argumenten die worden gebruikt in _open en _sopen.

Tekens in mode tekenreeks Equivalente oflag waarde voor _open/_sopen
a _O_WRONLY | _O_APPEND (meestal _O_WRONLY | _O_CREAT | _O_APPEND)
a+ _O_RDWR | _O_APPEND (meestal _O_RDWR | _O_APPEND | _O_CREAT)
R _O_RDONLY
r+ _O_RDWR
w _O_WRONLY (meestal _O_WRONLY | _O_CREAT | _O_TRUNC)
w+ _O_RDWR (meestal **_O_RDWR | _O_CREAT | _O_TRUNC)
b _O_BINARY
t _O_TEXT (vertaald)
c Geen
n Geen
N _O_NOINHERIT
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

De c, n, R, S, t, Ten Dmode opties zijn Microsoft-extensies voor fopen_s en _wfopen_s en mogen niet worden gebruikt wanneer u ANSI-draagbaarheid wilt.

Als u de rb-modus gebruikt, zijn geheugen toegewezen Win32-bestanden mogelijk ook een optie als u uw code niet hoeft over te zetten, verwacht u veel van het bestand te lezen, of maakt u zich geen zorgen over de netwerkprestaties.

Met betrekking tot T en D:

  • T vermijdt het schrijven van het bestand naar schijf zolang geheugendruk dit niet vereist. Zie FILE_ATTRIBUTE_TEMPORARY in Bestandskenmerken constantenen dit blogbericht Het is alleen tijdelijkvoor meer informatie.
  • D geeft een gewoon bestand op dat naar schijf wordt geschreven. Het verschil is dat het automatisch wordt verwijderd wanneer deze wordt gesloten. U kunt TD combineren om beide semantiek te verkrijgen.

Vereisten

Functie Vereiste header C++ koptekst
fopen_s <stdio.h> <cstdio>
_wfopen_s <stdio.h> of <wchar.h> <cstdio>

Zie Compatibiliteits-voor meer informatie over standaardencompatibiliteit en naamconventies in de C-runtimebibliotheek.

Algemene routinetoewijzingen voor tekst

<tchar.h> routine _UNICODE en _MBCS niet gedefinieerd _MBCS gedefinieerd _UNICODE gedefinieerd
_tfopen_s fopen_s fopen_s _wfopen_s

Bibliotheken

Alle versies van de C-runtimebibliotheken.

Voorbeeld

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

Zie ook

Stream I/O-
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode