fopen_s, _wfopen_s

Öppnar en fil. Dessa versioner av fopen, _wfopen har säkerhetsförbättringar enligt beskrivningen i Säkerhetsfunktioner i CRT-.

Syntax

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

Parameterar

pFile
En pekare till filpekaren som tar emot pekaren till den öppnade filen.

filename
Namnet på filen som ska öppnas.

mode
Typ av åtkomst tillåten.

Returvärde

Noll om det lyckas. en felkod vid fel. Mer information om dessa felkoder finns i errno, _doserrno, _sys_errlistoch _sys_nerr.

Feltillstånd

Anmärkningar

Funktionerna fopen_s och _wfopen_s kan inte öppna en fil för delning. Om du behöver dela filen använder du _fsopen eller _wfsopen med rätt konstant delningsläge, till exempel använda _SH_DENYNO för läs-/skrivdelning.

Funktionen fopen_s öppnar filen som anges av filename. _wfopen_s är en bred karaktärsversion av fopen_s och argumenten som ska _wfopen_s är breda teckensträngar. _wfopen_s och fopen_s beter sig identiskt, annars.

fopen_s accepterar sökvägar som är giltiga i filsystemet vid körningspunkten. UNC-sökvägar och sökvägar som omfattar mappade nätverksenheter godkänns av fopen_s så länge det system som kör koden har åtkomst till resursen eller den mappade nätverksenheten vid tidpunkten för körningen. När du skapar sökvägar för fopen_sska du inte göra antaganden om tillgängligheten för enheter, sökvägar eller nätverksresurser i körningsmiljön. Du kan använda snedstreck (/) eller omvänt snedstreck (\) som katalogavgränsare i en sökväg.

Dessa funktioner verifierar sina parametrar. Om pFile, filenameeller mode är en null-pekare genererar dessa funktioner ett ogiltigt parameterfel enligt beskrivningen i Parameterverifiering.

Kontrollera alltid returvärdet för att se om funktionen lyckades innan du utför några ytterligare åtgärder i filen. Om ett fel inträffar returneras felkoden och den globala variabeln errno anges. Mer information finns i errno, _doserrno, _sys_errlistoch _sys_nerr.

Som standard är den här funktionens globala tillstånd begränsat till programmet. Information om hur du ändrar det finns i Globalt tillstånd i CRT-.

Unicode-stöd

fopen_s stöder Unicode-filströmmar. Om du vill öppna en ny eller befintlig Unicode-fil skickar du en ccs flagga som anger önskad kodning till fopen_s, till exempel:

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

Tillåtna värden för flaggan ccs är UNICODE, UTF-8och UTF-16LE. Om inget värde anges för ccsanvänder fopen_s ANSI-kodning.

Om filen redan finns och öppnas för läsning eller tillägg, avgör byteordningsmarkeringen (BOM) om den finns i filen kodningen. BOM-kodningen har företräde framför den kodning som anges av flaggan ccs. Den ccs kodningen används bara när ingen strukturlista finns eller om filen är en ny fil.

I följande tabell sammanfattas lägena för olika ccs flaggvärden som ges till fopen_s och för BPM i filen.

Kodningar som används baserat på ccs flagga och BOM

Filer som öppnas för skrivning i Unicode-läge har en strukturlista som skrivs till dem automatiskt.

Om mode är "a, ccs=UNICODE", "a, ccs=UTF-8"eller "a, ccs=UTF-16LE"försöker fopen_s först öppna filen med både läsåtkomst och skrivåtkomst. Om det lyckas läser funktionen bommen för att fastställa kodningen för filen. Om det inte lyckas använder funktionen standardkodningen för filen. I båda fallen öppnar fopen_s filen igen med skrivskyddad åtkomst. (Det här beteendet gäller endast för a läge, inte a+.)

Teckensträngen mode anger vilken typ av åtkomst som begärs för filen enligt följande.

När en fil öppnas med hjälp av "a" eller "a+" åtkomsttyp sker alla skrivåtgärder i slutet av filen. Filpekaren kan flyttas med hjälp av fseek eller rewind, men den flyttas alltid tillbaka till slutet av filen innan någon skrivåtgärd utförs så att befintliga data inte kan skrivas över.

Det "a" läget tar inte bort EOF-markören innan den lägger till filen. När det har lagts till visar kommandot MS-DOS TYPE endast data upp till den ursprungliga EOF-markören och inte några data som läggs till i filen. "a+"-läget tar bort EOF-markören innan den lägger till filen. När du har lagt till kommandot MS-DOS TYPE visas alla data i filen. Det "a+" läget krävs för att lägga till en dataströmfil som avslutas med CTRL+Z EOF-markör.

När åtkomsttypen "r+", "w+"eller "a+" anges tillåts både läsning och skrivning. (Filen sägs vara öppen för "uppdatering".) Men när du växlar från läsning till skrivning måste indataåtgärden stöta på en EOF-markör. Om det inte finns någon EOF-markör måste du använda ett mellanliggande anrop till en filplaceringsfunktion. Filplaceringsfunktionerna är fsetpos, fseekoch rewind. När du växlar från skrivning till läsning måste du använda ett mellanliggande anrop till antingen fflush eller till en filplaceringsfunktion.

Från och med C11 kan du lägga till "x" till "w" eller "w+" för att orsaka att funktionen misslyckas om filen finns, i stället för att skriva över den.

Förutom föregående värden kan följande tecken inkluderas i mode för att ange översättningsläget för nya radtecken:

I textläge (översatt) tolkas CTRL+Z- som ett filslutstecken vid indata. För filer som öppnats för läsning/skrivning med "a+"söker fopen_s efter en CTRL+Z- i slutet av filen och tar bort den, om möjligt. Den tas bort eftersom användning av fseek och ftell för att flytta i en fil som slutar med en CTRL+Z, kan leda till att fseek beter sig felaktigt nära slutet av filen.

I textläge översätts crlf-kombinationer (vagnretur/radmatning) till LF-tecken (single line feed) vid indata, och LF-tecken översätts till CRLF-kombinationer vid utdata. När en Unicode stream-I/O-funktion fungerar i textläge (standard) antas käll- eller målströmmen vara en sekvens med flerabytestecken. Unicode stream-input-funktionerna konverterar flerabytestecken till breda tecken (som vid ett anrop till funktionen mbtowc). Av samma anledning konverterar Unicode-strömutdatafunktionerna breda tecken till flerbytestecken (som vid ett anrop till funktionen wctomb).

Om t eller b inte anges i modedefinieras standardöversättningsläget av den globala variabeln _fmode. Om t eller b är prefix för argumentet misslyckas funktionen och returnerar NULL.

Mer information om hur du använder text- och binärlägen i Unicode och stream-I/O i flerabyte finns i text- och binärlägesfil i I/O- och Unicode stream I/O i text- och binärlägen.

Giltiga tecken för den mode sträng som används i fopen_s och _fdopen motsvarar oflag argument som används i _open och _sopen, enligt följande.

Alternativen c, n, R, S, t, Toch Dmode är Microsoft-tillägg för fopen_s och _wfopen_s och bör inte användas när du vill ha ANSI-portabilitet.

Om du använder rb läge kan minnesmappade Win32-filer också vara ett alternativ om du inte behöver porta koden, du förväntar dig att läsa mycket av filen eller om du inte bryr dig om nätverksprestanda.

Angående T och D:

• T undviker att skriva filen till disk så länge minnesbelastningen inte kräver det. Mer information finns i FILE_ATTRIBUTE_TEMPORARY i Filattributkonstanter, och även det här blogginlägget Det är bara tillfälligt.
• D anger en vanlig fil som skrivs till disk. Skillnaden är att den tas bort automatiskt när den stängs. Du kan kombinera TD för att få båda semantiken.

Krav

Mer information om standarders efterlevnads- och namngivningskonventioner i C-körningsbiblioteket finns i Compatibility.

Allmän textrutinmappning

Bibliotek

Alla versioner av C-körningsbibliotek.

Exempel

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

Se även

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