fopen, _wfopen

Membuka file. Versi yang lebih aman dari fungsi-fungsi ini yang melakukan lebih banyak validasi parameter dan kode kesalahan pengembalian tersedia; lihat fopen_s, _wfopen_s.

Sintaks

FILE *fopen(
   const char *filename,
   const char *mode
);
FILE *_wfopen(
   const wchar_t *filename,
   const wchar_t *mode
);

Parameter

filename
Nama file.

mode
Jenis akses yang diaktifkan.

Nilai hasil

Masing-masing fungsi ini mengembalikan penunjuk ke file yang terbuka. Nilai penunjuk null menunjukkan kesalahan. Jika filename atau mode adalah NULL atau string kosong, fungsi-fungsi ini memicu handler parameter yang tidak valid, yang dijelaskan dalam Validasi parameter. Jika eksekusi diizinkan untuk melanjutkan, fungsi-fungsi ini kembali NULL dan diatur errno ke EINVAL.

Untuk informasi selengkapnya, lihat errno, _doserrno, _sys_errlist, dan _sys_nerr.

Keterangan

Fungsi fopen membuka file yang ditentukan oleh filename. Secara default, string sempit filename ditafsirkan menggunakan halaman kode ANSI (CP_ACP). Di aplikasi Windows Desktop, aplikasi dapat diubah ke halaman kode OEM (CP_OEMCP) dengan menggunakan SetFileApisToOEM fungsi . Anda dapat menggunakan AreFileApisANSI fungsi untuk menentukan apakah filename ditafsirkan menggunakan ANSI atau halaman kode OEM default sistem. _wfopen adalah versi fopenkarakter lebar ; _wfopen argumen adalah string karakter lebar. Jika tidak, _wfopen dan fopen berulah identik. Hanya menggunakan _wfopen tidak memengaruhi kumpulan karakter berkode yang digunakan dalam aliran file.

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

Selalu periksa nilai yang dikembalikan untuk melihat apakah pointer adalah NULL sebelum Anda melakukan operasi lain pada file. Jika terjadi kesalahan, variabel errno global diatur, dan dapat digunakan untuk mendapatkan informasi kesalahan tertentu. 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 mendukung aliran file Unicode. Untuk membuka file Unicode, berikan ccs=encoding bendera yang menentukan pengodean yang diinginkan ke fopen, sebagai berikut.

FILE *fp = fopen("newfile.txt", "rt+, ccs=UTF-8");

Nilai yang diizinkan untuk ccs pengodean adalah UNICODE, UTF-8, dan UTF-16LE.

Saat file dibuka dalam mode Unicode, fungsi input menerjemahkan data yang dibaca dari file ke dalam data UTF-16 yang disimpan sebagai jenis wchar_t. Fungsi yang menulis ke file yang dibuka dalam mode Unicode mengharapkan buffer yang berisi data UTF-16 yang disimpan sebagai jenis wchar_t. Jika file dikodekan sebagai UTF-8, maka data UTF-16 diterjemahkan ke dalam UTF-8 saat ditulis. Konten yang dikodekan UTF-8 file diterjemahkan ke dalam UTF-16 saat dibaca. Upaya untuk membaca atau menulis jumlah byte ganjil dalam mode Unicode menyebabkan kesalahan validasi parameter. Untuk membaca atau menulis data yang disimpan dalam program Anda sebagai UTF-8, gunakan mode teks atau file biner alih-alih mode Unicode. Anda bertanggung jawab atas terjemahan pengodean yang diperlukan.

Jika file sudah ada dan dibuka untuk dibaca atau ditambahkan, maka tanda urutan byte (BOM) apa pun 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 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 yang digunakan untuk berbagai ccs bendera yang diberikan ke fopen dan Tanda Urutan Byte dalam file.

Pengodean yang digunakan berdasarkan bendera ccs dan BOM

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

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

Jika mode untuk a, ccs=encoding beberapa encoding nilai, fopen pertama-tama mencoba membuka file dengan menggunakan akses baca dan tulis. Jika tindakan ini berhasil, fungsi membaca BOM untuk menentukan pengodean untuk file. Jika gagal, fungsi menggunakan pengodean default untuk file. Dalam kedua kasus, fopen buka kembali file menggunakan akses tulis-saja. (Perilaku ini hanya berlaku untuk "a" mode, bukan untuk "a+" mode.)

Pemetaan rutin teks generik

TCHAR.H Rutin	_UNICODE dan _MBCS tidak ditentukan	_MBCS Didefinisikan	_UNICODE Didefinisikan
_tfopen	fopen	fopen	_wfopen

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

mode	Access
"r"	Buka untuk membaca. Jika file tidak ada atau tidak dapat ditemukan, fopen 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 akses atau "a+" jenis 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. Oleh karena itu, data yang ada tidak dapat ditimpa.

"a" Mode tidak menghapus penanda EOF sebelum ditambahkan 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. Sebelum ditambahkan ke file, "a+" mode menghapus penanda EOF. Setelah menambahkan, perintah MS-DOS TYPE menunjukkan 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, pembacaan dan penulisan diaktifkan (file dikatakan terbuka untuk "pembaruan"). Namun, ketika Anda beralih dari membaca ke menulis, operasi input harus menemukan penanda EOF. Jika tidak ada EOF, Anda harus menggunakan panggilan intervensi ke fungsi pemosisian file. Fungsi penempatan file adalah fsetpos, , fseekdan rewind. Ketika Anda beralih dari menulis ke membaca, Anda harus menggunakan panggilan intervensi ke atau fflush ke fungsi penempatan file.

Selain nilai sebelumnya, karakter berikut dapat ditambahkan 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. Selain itu, 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 teks, CTRL+Z ditafsirkan sebagai karakter EOF pada input. Dalam file yang dibuka untuk membaca/menulis dengan menggunakan "a+", fopen 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 perilaku salah di dekat akhir file.

Dalam mode teks, kombinasi umpan baris kembali pengangkutan (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. Oleh karena itu, 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 cara menggunakan mode teks dan biner di Unicode dan multibyte stream-I/O, lihat Teks dan file mode biner I/O dan I/O aliran Unicode dalam mode teks dan biner.

Opsi berikut dapat ditambahkan untuk mode menentukan lebih banyak perilaku.

mode Pengubah	Perilaku
x	Memaksa fungsi gagal jika filename sudah ada. Hanya dapat digunakan dengan penentu "w" atau "w+".
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=encoding	Menentukan set karakter yang dikodekan untuk digunakan (salah satu dari UTF-8, UTF-16LE, atau UNICODE) untuk file ini. Biarkan tidak ditentukan jika Anda ingin pengodean ANSI. Bendera ini dipisahkan dari bendera yang mendahuluinya dengan koma (,). Misalnya: FILE *f = fopen("newfile.txt", "rt+, ccs=UTF-8");

Karakter yang valid untuk mode string yang digunakan dan fopen _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)
x	_O_EXCL
c	Tidak
n	Tidak
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

Jika Anda menggunakan rb mode, Anda tidak perlu mem-port kode Anda, dan jika Anda berharap untuk membaca sebagian besar file besar atau tidak khawatir tentang performa jaringan, Anda mungkin juga mempertimbangkan apakah akan menggunakan file Win32 yang dipetakan memori sebagai opsi.

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.

Opsi c, , Rn, St, , T, dan D mode adalah ekstensi Microsoft untuk fopen dan _wfopen tidak boleh digunakan saat Anda menginginkan portabilitas ANSI.

Persyaratan

Fungsi	Header yang diperlukan
fopen	<stdio.h>
_wfopen	<stdio.h> atau <wchar.h>

_wfopen adalah ekstensi Microsoft. Untuk informasi selengkapnya tentang kompatibilitas, lihat Kompatibilitas.

Opsi c, , tn, SR, , T, dan D mode adalah ekstensi Microsoft untuk fopen dan _fdopen tidak boleh digunakan di mana portabilitas ANSI diinginkan.

Contoh 1

Program berikut membuka dua file. Ini menggunakan fclose untuk menutup file pertama dan _fcloseall untuk menutup semua file yang tersisa.

// crt_fopen.c
// compile with: /W3
// 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 )
{
   int numclosed;

   // Open for read (will fail if file "crt_fopen.c" does not exist)
   if( (stream  = fopen( "crt_fopen.c", "r" )) == NULL ) // C4996
   // Note: fopen is deprecated; consider using fopen_s instead
      printf( "The file 'crt_fopen.c' was not opened\n" );
   else
      printf( "The file 'crt_fopen.c' was opened\n" );

   // Open for write
   if( (stream2 = fopen( "data2", "w+" )) == NULL ) // C4996
      printf( "The file 'data2' was not opened\n" );
   else
      printf( "The file 'data2' was opened\n" );

   // Close stream if it is not NULL
   if( stream)
   {
      if ( fclose( stream ) )
      {
         printf( "The file 'crt_fopen.c' was not closed\n" );
      }
   }

   // All other files are closed:
   numclosed = _fcloseall( );
   printf( "Number of files closed by _fcloseall: %u\n", numclosed );
}

The file 'crt_fopen.c' was opened
The file 'data2' was opened
Number of files closed by _fcloseall: 1

Contoh 2

Program berikut membuat file (atau menimpa file jika ada), dalam mode teks yang memiliki pengodean Unicode. Kemudian menulis dua string ke dalam file dan menutup file. Output adalah file bernama _wfopen_test.xml, yang berisi data dari bagian output.

// crt__wfopen.c
// compile with: /W3
// This program creates a file (or overwrites one if
// it exists), in text mode using Unicode encoding.
// It then writes two strings into the file
// and then closes the file.

#include <stdio.h>
#include <stddef.h>
#include <stdlib.h>
#include <wchar.h>

#define BUFFER_SIZE 50

int main(int argc, char** argv)
{
    wchar_t str[BUFFER_SIZE];
    size_t  strSize;
    FILE*   fileHandle;

    // Create an the xml file in text and Unicode encoding mode.
    if ((fileHandle = _wfopen( L"_wfopen_test.xml",L"wt+,ccs=UNICODE")) == NULL) // C4996
    // Note: _wfopen is deprecated; consider using _wfopen_s instead
    {
        wprintf(L"_wfopen failed!\n");
        return(0);
    }

    // Write a string into the file.
    wcscpy_s(str, sizeof(str)/sizeof(wchar_t), L"<xmlTag>\n");
    strSize = wcslen(str);
    if (fwrite(str, sizeof(wchar_t), strSize, fileHandle) != strSize)
    {
        wprintf(L"fwrite failed!\n");
    }

    // Write a string into the file.
    wcscpy_s(str, sizeof(str)/sizeof(wchar_t), L"</xmlTag>");
    strSize = wcslen(str);
    if (fwrite(str, sizeof(wchar_t), strSize, fileHandle) != strSize)
    {
        wprintf(L"fwrite failed!\n");
    }

    // Close the file.
    if (fclose(fileHandle))
    {
        wprintf(L"fclose failed!\n");
    }
    return 0;
}

Lihat juga

Streaming I/O
Interpretasi urutan karakter multibyte
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode
_sopen, _wsopen