fopen_s, _wfopen_s

Artykuł
03/26/2013

Otwiera plik.Te wersje fopen, _wfopen mieć rozszerzenia zabezpieczeń opisane w Funkcje zabezpieczeń w 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 
);

Parametry

[Brak]pFile
Wskaźnik do wskaźnika pliku, który będzie odbierał wskaźnika do otwartego pliku.
[in]filename
Nazwa pliku.
[in]mode
Typ dostępu zezwala.

Wartość zwracana

Zero, jeśli kończy się pomyślnie; Kod błędu w przypadku awarii.Zobacz errno, _doserrno, _sys_errlist i _sys_nerr uzyskać więcej informacji dotyczących kodów błędów.

Warunki błędów

pFile	filename	mode	Zwracana wartość	ZawartośćpFile
NULL	wszelkie	wszelkie	EINVAL	bez zmian
wszelkie	NULL	wszelkie	EINVAL	bez zmian
wszelkie	wszelkie	WARTOŚĆ NULL	EINVAL	bez zmian

Uwagi

Pliki otwarte przez fopen_s i _wfopen_s nie są udostępnianych.Jeśli wymagane, że można zabezpieczać pliku, należy użyć _fsopen, _wfsopen z odpowiednią stałą tryb udostępniania — na przykład, _SH_DENYNO za udostępnienie odczytu/zapisu.

fopen_s Funkcja otwiera plik, który jest określony przez filename._wfopen_sjest ona szerokich znaków do fopen_s; argumenty w funkcji _wfopen_s są ciągami szerokich znaków._wfopen_si fopen_s zachowują się identycznie inaczej.

fopen_sakceptuje ścieżki, które są dozwolone w systemie plików w punkcie realizacji; Ścieżki UNC i ścieżek, które mogą obejmować w zmapowanych dysków sieciowych są akceptowane przez fopen_s tak długo, jak system, który jest wykonywany kod ma dostęp do udziału lub zmapowanym dysku sieciowym w czasie wykonywania.Kiedy można skonstruować ścieżek dla fopen_s, nie założenia dotyczące dostępności dysków, ścieżek, lub udziałów sieciowych w środowisko wykonawcze.Kreska ułamkowa (/) lub ukośniki odwrotne (\) służy jako separatory katalogu w ścieżce.

Te funkcje sprawdzania poprawności ich parametrów.Jeśli pFile, filename, lub mode jest pusty wskaźnik, funkcje te wygenerowanie wyjątku nieprawidłowy parametr, zgodnie z opisem w Sprawdzanie poprawności parametru.

Zawsze sprawdzaj wartość zwracana, aby zobaczyć, czy funkcja zakończyła się pomyślnie przed wykonaniem wszelkich dalszych operacji na pliku.Jeśli wystąpi błąd, zwracany jest kod błędu i zmienna globalna errno jest ustawiona.Aby uzyskać więcej informacji, zobacz errno, _doserrno, _sys_errlist i _sys_nerr.

Obsługa standardu Unicode

fopen_sobsługuje strumienie plik Unicode.Aby otworzyć nowy lub istniejący plik Unicode, należy przekazać ccs Flaga określająca odpowiednie kodowanie, aby fopen_s:

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

Allowed values of encoding are UNICODE, UTF-8, and UTF-16LE.Jeśli określono żadnej wartości dla encoding, fopen_s używane kodowanie ANSI.

Jeżeli plik już istnieje i jest otwarty do odczytu lub dołączanie, bajt kolejność Mark (BOM), jeśli jest obecna w pliku, określa kodowanie.Kodowanie BOM ma pierwszeństwo nad kodowanie, określonej przez ccs flagi.ccs Używane jest kodowanie tylko wtedy, gdy żaden BOM jest obecnie lub jeśli plik jest nowy plik.

[!UWAGA]

Wykrywanie BOM dotyczy tylko plików, które są otwierane w trybie Unicode; oznacza to, przechodzącą przez ccs flagi.

W następującej tabeli podsumowano trybów dla różnych ccs flagi, które są podane do fopen_s i dla bajt kolejność znaków w pliku.

Standardy kodowania używane na podstawie ccs Flaga i BOM-u

ccsFlaga	Nie BOM-u (lub nowy plik)	BOM-U: UTF-8	BOM-U: 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

Pliki, które są otwarte do pisania w trybie Unicode mają BOM automatycznie zapisywane do nich.

Jeśli mode jest "a, ccs=<encoding>", fopen_s najpierw próbuje otworzyć plik z dostępu do odczytu i zapisu.W przypadku powodzenia funkcja odczytuje BOM, aby określić kodowanie pliku; w przypadku niepowodzenia funkcja używa domyślnego kodowania dla pliku.W obu przypadkach fopen_s ponownie otwiera plik z dostępem tylko do zapisu.(Dotyczy to a nie tylko, tryb a+.)

Tekst rodzajowy rutynowych mapowania

TCHAR.Rozpoczęto wykonywanie procedury h	_UNICODE & _MBCS nie zdefiniowany	_MBCS, definicja	_UNICODE, definicja
_tfopen_s	fopen_s	fopen_s	_wfopen_s

Ciąg znaków mode określa rodzaj dostępu, który jest wymagany dla pliku, następująco.

"r"
Zostanie otwarty do odczytu.Jeśli plik nie istnieje lub nie można znaleźć, fopen_s wywołanie kończy się niepowodzeniem.
"w"
Otwiera pusty plik do zapisu.Jeżeli plik istnieje, jego zawartość są niszczone.
"a"
Zostanie otwarty do zapisu na końcu pliku (dołączanie), bez usuwania znacznik EOF przed zapisaniem nowych danych do pliku.Powoduje utworzenie pliku, jeśli nie istnieje.
"r+"
Otwiera zarówno Odczyt i zapis.(Plik musi istnieć.)
"w+"
Otwiera pusty plik do zarówno odczytu i zapisu.Jeżeli plik istnieje, jego zawartość są niszczone.
"a+"
Zostanie otwarty do odczytu i dołączanie.Dołączając operacja obejmuje usunięcie znacznik EOF, zanim nowe dane są zapisywane do pliku i znacznik EOF zostanie przywrócona po zakończeniu pisania.Powoduje utworzenie pliku, jeśli nie istnieje.

Kiedy plik jest otwarty za pomocą "a" lub "a+" dostęp typu zapis wszystkich operacji występuje na końcu pliku.Wskaźnik pliku może być przeniesiony za pomocą fseek lub rewind, ale jest zawsze przeniesiono go z powrotem na końcu pliku dowolny wpisywanie czynność jest przeprowadzana, tak aby nie można zastąpić istniejące dane.

"a" Trybu nie powoduje usunięcia znacznik EOF zanim dołączy do pliku.Po nastąpieniu dołączenie polecenia systemu MS-DOS TYPE pokazuje tylko dane do oryginalnego znacznik EOF i nie ma żadnych danych, która jest dołączana do pliku."a+" Tryb Usuń znacznik EOF, zanim dołączy do pliku.Po dołączanie, polecenia MS-DOS TYPE pokazuje wszystkie dane w pliku."a+" Tryb jest wymagany dla dołączania do pliku strumienia, który jest zakończone przy użyciu znacznik EOF CTRL + Z.

Gdy "r+","w+", lub "a+" jest określony typ dostępu, są dozwolone zarówno Odczyt i zapis. (Plik nazywa się otwarta do "update".) Po przełączeniu czytanie na pismo wejściowego operacji musi wystąpić znacznik EOF.Jeśli nie ma żadnych EOF, należy użyć wywołania funkcji pozycjonowania pliku.Funkcje pozycjonowania pliku są fsetpos, fseek, i rewind.Po przełączeniu się z zapisu do czytania, należy użyć wywołania albo fflush lub do funkcji pozycjonowania pliku.

Oprócz powyższych wartości, następujące znaki mogą być zawarte w mode Aby określić tryb tłumaczenia na znaki nowego wiersza:

t
Otwórz w tekście (translacji) tryb.W tym trybie CTRL + Z jest interpretowana jako znak końca pliku na wejściu.W przypadku plików otwartych do odczytu/zapisu, z "a+", fopen_s sprawdza, czy CTRL + Z na końcu pliku i usuwa go, jeśli to możliwe.Odbywa się, ponieważ korzysta z fseek i ftell w pliku, który może powodować kończy CTRL + Z, fseek do jego niewłaściwe działanie pod koniec pliku.

Ponadto w trybie tekstowym, karetki ze zmianą wiersza kombinacje są tłumaczone na pojedynczej znaki wysuwu wiersza na wejściu, i znaki wysuwu wiersza są tłumaczone na przewóz kombinacjach ze zmianą wiersza w danych wyjściowych.Kiedy funkcja strumienia i/o Unicode działa w trybie tekstowym (ustawienie domyślne), źródła lub strumień docelowy zakłada się sekwencję znaków wielobajtowych.W związku z tym, funkcji strumień wejściowy Unicode, konwertuje znaki wielobajtowe na szerokości znaków (tak jakby za pomocą wywołania mbtowc funkcji).Z tego samego powodu funkcji strumienia wyjściowego Unicode konwertuje szerokości znaków na znaki wielobajtowe (tak jakby za pomocą wywołania wctomb funkcji).

b
Otwórz w trybie binarnym (niezrozumiały); tłumaczenia udziałem znaki powrotu karetki i wysuwu wiersza są odrzucane.

Jeśli t lub b nie została podana w mode, domyślnie tryb konwersji jest definicją zmiennej globalnej _fmode.Jeśli t lub b jest poprzedzona argument, funkcja kończy się niepowodzeniem i zwraca NULL.

Aby dowiedzieć się więcej na temat używania tekstu i trybów binarne w Unicode i wielobajtowych strumienia i/o, zobacz tekstu i binarny tryb We/Wy pliku i Unicode strumienia wejścia/wyjścia w binarnym trybu tekstowego i.

c
Włączyć flagę zatwierdzanie skojarzonych z nim filename tak, aby zawartość buforu pliku zostanie zapisana bezpośrednio na dysku, jeśli każda fflush lub _flushall nosi nazwę.
n
Resetuj flagę zatwierdzanie skojarzonych z nim filename do "Zatwierdzanie nie." Domyślnie włączone.Zastępuje ona również flagi globalne zatwierdzanie jeśli połączymy nasz program, z COMMODE.OBJ.Domyślnie flaga globalnego commit jest "Zatwierdzanie nie", chyba że zostaną jawnie połączone programu z KOMODA.OBJ (see Opcje łącza).
N
Określa, że plik nie jest dziedziczona przez procesy podrzędne.
S
Określa, że buforowanie jest zoptymalizowany pod kątem, ale nie ogranicza się do dostępu sekwencyjnego z dysku.
R
Określa, że buforowanie jest zoptymalizowany pod kątem, ale nie ogranicza się do dostępie z dysku.
T
Określa plik jako tymczasowy.Jeśli to możliwe, nie jest opróżniany na dysku.
D
Określa plik jako tymczasowy.Skreśla się, gdy ostatni wskaźnik pliku jest zamknięty.
ccs=ENCODING
Określić zestaw znaków zakodowanych w obsłudze (UTF-8, UTF-16LE i UNICODE) dla tego pliku.Pozostaw to nieokreślone, jeśli chcesz kodowanie ANSI.

Prawidłowe znaki mode ciąg używany w fopen_s i _fdopen odpowiadają oflag argumenty użyte w _O i _sopenw następujący.

W trybie ciągu znaków	Równoważne oflag wartość dla _open/_sopen
a	_O_WRONLY \| _O_APPEND(usually _O_WRONLY \| _O_CREAT \|_O_APPEND)
a+	_O_RDWR \| _O_APPEND(usually _O_RDWR \| _O_APPEND \| _O_CREAT )
r	_O_RDONLY
r+	_O_RDWR
w	_O_WRONLY(usually _O_WRONLY \|_O_CREAT \| _O_TRUNC)
w+	_O_RDWR(usually _O_RDWR \| _O_CREAT \| _O_TRUNC)
b	_O_BINARY
t	_O_TEXT
c	Brak
n	Brak
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

Jeśli używasz rb trybie, nie musisz port swój kod i oczekiwać, aby przeczytać dużo pliku i/lub nie dbają o wydajności sieci, plików mapowanych w pamięci systemu Win32 może również stanowić odpowiednie rozwiązanie.

Wymagania

Funkcja	Wymaganego nagłówka
fopen_s	<stdio.h>
_wfopen_s	<stdio.h> lub <wchar.h>

Aby uzyskać dodatkowe informacje o zgodności, zobacz zgodności we wprowadzeniu.

Biblioteki

Wszystkie wersje programu biblioteki uruchomieniowej C.

c, n, I tmode opcje są rozszerzenia Microsoft dla fopen_s i _fdopen i nie powinny być używane gdzie przenoszenia ANSI jest pożądane.

Przykład

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