fopen_s, _wfopen_s

Membuka file. Versi fopen, _wfopen ini memiliki peningkatan keamanan, seperti yang dijelaskan dalam Fitur keamanan di CRT.

Sintaks

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

Parameter

pFile
Penunjuk ke penunjuk file yang menerima penunjuk ke file yang dibuka.

filename
Nama file yang akan dibuka.

mode
Jenis akses yang diizinkan.

Nilai hasil

Nol jika berhasil; kode kesalahan pada kegagalan. Untuk informasi selengkapnya tentang kode kesalahan ini, lihat errno, , _doserrno_sys_errlist, dan _sys_nerr.

Kondisi kesalahan

pFile filename mode Tampilkan Nilai Isi dari pFile
NULL apa pun apa pun EINVAL Berubah
apa pun NULL apa pun EINVAL Berubah
apa pun apa pun NULL EINVAL Berubah

Keterangan

Fungsi fopen_s dan _wfopen_s tidak dapat membuka file untuk berbagi. Jika Anda perlu berbagi file, gunakan _fsopen atau _wfsopen dengan konstanta mode berbagi yang sesuai—misalnya, gunakan _SH_DENYNO untuk berbagi baca/tulis.

Fungsi fopen_s membuka file yang ditentukan oleh filename. _wfopen_s adalah versi fopen_s karakter lebar dan argumen untuk _wfopen_s adalah string karakter lebar. _wfopen_s dan fopen_s bertempur secara identik, jika tidak.

fopen_s menerima jalur yang valid pada sistem file pada titik eksekusi; Jalur dan jalur UNC yang melibatkan drive jaringan yang dipetakan fopen_s diterima selama sistem yang menjalankan kode memiliki akses ke drive jaringan yang dibagikan atau dipetakan pada saat eksekusi. Saat Anda membuat jalur untuk fopen_s, jangan membuat asumsi tentang ketersediaan drive, jalur, atau berbagi jaringan di lingkungan eksekusi. Anda dapat menggunakan garis miring (/) atau garis miring terbalik (\) sebagai pemisah direktori di jalur.

Fungsi-fungsi ini memvalidasi parameternya. Jika pFile, filename, atau mode adalah penunjuk null, fungsi-fungsi ini menghasilkan pengecualian parameter yang tidak valid, seperti yang dijelaskan dalam Validasi parameter.

Selalu periksa nilai pengembalian untuk melihat apakah fungsi berhasil sebelum Anda melakukan operasi lebih lanjut pada file. Jika terjadi kesalahan, kode kesalahan dikembalikan, dan variabel errno global diatur. Untuk informasi selengkapnya, lihat errno, _doserrno, _sys_errlist, dan _sys_nerr.

Secara default, status global fungsi ini dicakup ke aplikasi. Untuk mengubahnya, lihat Status global di CRT.

Dukungan Unicode

fopen_s mendukung aliran file Unicode. Untuk membuka file Unicode baru atau yang sudah ada, teruskan ccs bendera yang menentukan pengodean yang diinginkan ke fopen_s, misalnya:

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

Nilai bendera yang diizinkan ccs adalah UNICODE, UTF-8, dan UTF-16LE. Jika tidak ada nilai yang ditentukan untuk ccs, fopen_s menggunakan pengodean ANSI.

Jika file sudah ada dan dibuka untuk dibaca atau ditambahkan, tanda urutan byte (BOM), jika ada dalam file, menentukan pengodean. Pengodean BOM lebih diutamakan daripada pengodean yang ditentukan oleh ccs bendera. Pengodean ccs hanya digunakan ketika tidak ada BOM yang ada atau jika file adalah file baru.

Catatan

Deteksi BOM hanya berlaku untuk file yang dibuka dalam mode Unicode; yaitu, dengan meneruskan ccs bendera.

Tabel berikut ini meringkas mode untuk berbagai ccs nilai bendera yang diberikan kepada fopen_s dan untuk BOM dalam file.

Pengodean yang digunakan berdasarkan ccs bendera dan BOM

ccs bendera Tidak ada BOM (atau file baru) 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

File yang dibuka untuk ditulis dalam mode Unicode memiliki BOM yang ditulis kepada mereka secara otomatis.

Jika mode adalah "a, ccs=UNICODE", , "a, ccs=UTF-8"atau "a, ccs=UTF-16LE", fopen_s pertama-tama mencoba membuka file dengan akses baca dan akses tulis. Jika berhasil, fungsi membaca BOM untuk menentukan pengodean untuk file; jika tidak berhasil, fungsi menggunakan pengodean default untuk file. Dalam kedua kasus, fopen_s kemudian buka kembali file dengan akses tulis-saja. (Perilaku ini hanya berlaku untuk a mode, bukan a+.)

String mode karakter menentukan jenis akses yang diminta untuk file, sebagai berikut.

mode Akses
"r" Buka untuk membaca. Jika file tidak ada atau tidak dapat ditemukan, fopen_s panggilan gagal.
"w" Membuka file kosong untuk ditulis. Jika file yang diberikan ada, isinya akan dihancurkan.
"a" Terbuka untuk menulis di akhir file (menambahkan) tanpa menghapus penanda end-of-file (EOF) sebelum data baru ditulis ke file. Membuat file jika tidak ada.
"r+" Terbuka untuk membaca dan menulis. File harus ada.
"w+" Membuka file kosong untuk membaca dan menulis. Jika file ada, isinya akan dihancurkan.
"a+" Terbuka untuk membaca dan menambahkan. Operasi penampingan mencakup penghapusan penanda EOF sebelum data baru ditulis ke file. Penanda EOF tidak dipulihkan setelah penulisan selesai. Membuat file jika tidak ada.

Ketika file dibuka dengan menggunakan "a" jenis atau "a+" akses, semua operasi tulis terjadi di akhir file. Penunjuk file dapat diposisikan ulang dengan menggunakan fseek atau rewind, tetapi selalu dipindahkan kembali ke akhir file sebelum operasi tulis dilakukan sehingga data yang ada tidak dapat ditimpa.

"a" Mode tidak menghapus penanda EOF sebelum menambahkan ke file. Setelah penambahan terjadi, perintah MS-DOS TYPE hanya menampilkan data hingga penanda EOF asli dan bukan data apa pun yang ditambahkan ke file. "a+" Mode ini menghapus penanda EOF sebelum menambahkan ke file. Setelah menambahkan, perintah MS-DOS TYPE menampilkan semua data dalam file. "a+" Mode ini diperlukan untuk menambahkan ke file stream yang dihentikan denganCTRL+ penanda Z EOF.

"r+"Ketika jenis akses , , "w+"atau "a+" ditentukan, baik membaca dan menulis diizinkan. (File dikatakan terbuka untuk "pembaruan".) Namun, ketika Anda beralih dari membaca ke menulis, operasi input harus menemukan penanda EOF. Jika tidak ada penanda EOF, Anda harus menggunakan panggilan intervensi ke fungsi pemosisian file. Fungsi pemosisian file adalah fsetpos, , fseekdan rewind. Ketika Anda beralih dari menulis ke membaca, Anda harus menggunakan panggilan intervensi ke atau fflush ke fungsi posisi file.

Mulai dari C11, Anda dapat menambahkan "x" ke "w" atau "w+" menyebabkan fungsi gagal jika file ada, alih-alih menimpanya.

Selain nilai sebelumnya, karakter berikut dapat disertakan untuk mode menentukan mode terjemahan untuk karakter baris baru:

mode Pengubah Mode terjemahan
t Buka dalam mode teks (diterjemahkan). Kombinasi umpan baris kembali pengangkutan (CR-LF) diterjemahkan ke dalam umpan baris tunggal (LF) pada karakter input dan LF diterjemahkan ke kombinasi CR-LF pada output. CTRL+Z ditafsirkan sebagai karakter akhir file pada input.
b Buka dalam mode biner (tidak diterjemahkan) ; terjemahan yang melibatkan karakter carriage-return dan line feed ditekan.

Dalam mode CTRL+teks (diterjemahkan), Z ditafsirkan sebagai karakter akhir file pada input. Untuk file yang dibuka untuk membaca/menulis dengan "a+", fopen_s periksaCTRL+ Z di akhir file dan menghapusnya, jika memungkinkan. Ini dihapus karena menggunakan fseek dan ftell untuk berpindah dalam file yang berakhir denganCTRL+ Z, dapat menyebabkan fseek berperilaku tidak benar di dekat akhir file.

Selain itu, dalam mode teks, kombinasi pengembalian pengangkutan/umpan baris (CRLF) diterjemahkan ke dalam karakter umpan baris tunggal (LF) pada input, dan karakter LF diterjemahkan ke kombinasi CRLF pada output. Ketika fungsi Stream-I/O Unicode beroperasi dalam mode teks (default), aliran sumber atau tujuan diasumsikan sebagai urutan karakter multibyte. Fungsi stream-input Unicode mengonversi karakter multibyte menjadi karakter lebar (seolah-olah dengan panggilan ke mbtowc fungsi). Untuk alasan yang sama, fungsi stream-output Unicode mengonversi karakter lebar menjadi karakter multibyte (seolah-olah dengan panggilan ke wctomb fungsi).

Jika t atau b tidak diberikan dalam mode, mode terjemahan default ditentukan oleh variabel _fmodeglobal . Jika t atau b diawali ke argumen, fungsi gagal dan mengembalikan NULL.

Untuk informasi selengkapnya tentang menggunakan mode teks dan biner di Unicode dan multibyte stream-I/O, lihat Teks dan mode biner file I/O dan Unicode stream I/O dalam mode teks dan biner.

mode Pengubah Perilaku
c Aktifkan bendera penerapan untuk yang terkait filename sehingga konten buffer file ditulis langsung ke disk jika atau fflush_flushall dipanggil.
n Reset bendera penerapan untuk yang terkait filename dengan "tanpa penerapan." Bendera ini adalah default. Ini juga mengambil alih bendera penerapan global jika Anda menautkan program Anda dengan COMMODE.OBJ. Default bendera penerapan global adalah "tanpa penerapan" kecuali Anda secara eksplisit menautkan program Anda dengan COMMODE.OBJ (lihat Opsi tautan).
N Menentukan bahwa file tidak diwariskan oleh proses turunan.
S Menentukan bahwa penembolokan dioptimalkan untuk, tetapi tidak dibatasi, akses berurutan dari disk.
R Menentukan bahwa penembolokan dioptimalkan untuk, tetapi tidak dibatasi, akses acak dari disk.
T Menentukan file yang tidak ditulis ke disk kecuali tekanan memori memerlukannya.
D Menentukan file sementara yang dihapus ketika penunjuk file terakhir ditutup.
ccs=UNICODE Menentukan UNICODE sebagai set karakter yang dikodekan yang akan digunakan untuk file ini. Biarkan tidak ditentukan jika Anda ingin pengodean ANSI.
ccs=UTF-8 Menentukan UTF-8 sebagai set karakter yang dikodekan yang akan digunakan untuk file ini. Biarkan tidak ditentukan jika Anda ingin pengodean ANSI.
ccs=UTF-16LE Menentukan UTF-16LE sebagai set karakter yang dikodekan yang akan digunakan untuk file ini. Biarkan tidak ditentukan jika Anda ingin pengodean ANSI.

Karakter yang valid untuk string yang mode digunakan dalam fopen_s dan _fdopen sesuai dengan oflag argumen yang digunakan di _open dan _sopen, sebagai berikut.

Karakter dalam mode string Nilai yang setara oflag untuk _open/_sopen
a _O_WRONLY | _O_APPEND (biasanya _O_WRONLY | _O_CREAT | _O_APPEND)
a+ _O_RDWR | _O_APPEND (biasanya _O_RDWR | _O_APPEND | _O_CREAT)
R _O_RDONLY
r+ _O_RDWR
w _O_WRONLY (biasanya _O_WRONLY | _O_CREAT | _O_TRUNC)
w+ _O_RDWR (biasanya **_O_RDWR | _O_CREAT | _O_TRUNC)
b _O_BINARY
t _O_TEXT (Diterjemahkan)
c Tidak
n Tidak
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

Opsi c, , nR, St, , T, dan Dmode adalah ekstensi Microsoft untuk fopen_s dan _wfopen_s tidak boleh digunakan saat Anda menginginkan portabilitas ANSI.

Jika Anda menggunakan rb mode, file Win32 yang dipetakan memori mungkin juga menjadi opsi jika Anda tidak perlu mem-port kode Anda, Anda berharap untuk membaca banyak file, atau Anda tidak peduli tentang performa jaringan.

Mengenai T dan D:

  • T menghindari penulisan file ke disk selama tekanan memori tidak memerlukannya. Untuk informasi selengkapnya, lihat FILE_ATTRIBUTE_TEMPORARY di Konstanta atribut file, dan juga posting blog ini Hanya sementara.
  • D menentukan file reguler yang ditulis ke disk. Perbedaannya adalah dihapus secara otomatis saat ditutup. Anda dapat menggabungkan TD untuk mendapatkan kedua semantik.

Persyaratan

Fungsi Header yang diperlukan Header C++
fopen_s <stdio.h> <cstdio>
_wfopen_s <stdio.h> atau <wchar.h> <cstdio>

Untuk informasi selengkapnya tentang kesesuaian standar dan konvensi penamaan di pustaka runtime C, lihat Kompatibilitas.

Pemetaan rutin teks generik

<tchar.h> Rutin _UNICODE dan _MBCS tidak ditentukan _MBCS Didefinisikan _UNICODE Didefinisikan
_tfopen_s fopen_s fopen_s _wfopen_s

Pustaka

Semua versi pustaka run-time C.

Contoh

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

Lihat juga

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

  • Last updated on