_sopen_s, _wsopen_s

Membuka file untuk berbagi. Versi ini dan _sopen _wsopenmemiliki peningkatan keamanan, seperti yang dijelaskan dalam Fitur keamanan di CRT.

Sintaks

errno_t _sopen_s(
   int* pfh,
   const char *filename,
   int oflag,
   int shflag,
   int pmode
);
errno_t _wsopen_s(
   int* pfh,
   const wchar_t *filename,
   int oflag,
   int shflag,
   int pmode,
);

Parameter

pfh
Handel file, atau -1 jika ada kesalahan.

filename
Nama file.

oflag
Jenis operasi yang diizinkan.

shflag
Jenis berbagi yang diizinkan.

pmode
Pengaturan izin.

Nilai hasil

Nilai pengembalian bukan nol menunjukkan kesalahan; dalam hal errno ini diatur ke salah satu nilai berikut.

errno nilai	Kondisi
EACCES	Jalur yang diberikan adalah direktori, atau file bersifat baca-saja, tetapi operasi buka untuk menulis telah dicoba.
EEXIST	_O_CREAT dan _O_EXCL bendera ditentukan, tetapi filename sudah ada.
EINVAL	Argumen , , atau tidak validoflag, atau pfh atau filename merupakan penunjuk null.pmode shflag
EMFILE	Tidak ada lagi deskriptor file yang tersedia.
ENOENT	File atau jalur tidak ditemukan.

Jika argumen yang tidak valid diteruskan ke fungsi, handler parameter yang tidak valid dipanggil, seperti yang dijelaskan dalam Validasi parameter. Jika eksekusi diizinkan untuk melanjutkan, errno diatur ke EINVAL, dan EINVAL dikembalikan.

Untuk informasi selengkapnya tentang kode pengembalian ini dan lainnya, lihat errno, , _doserrno_sys_errlist, dan _sys_nerr.

Jika ada kesalahan, -1 dikembalikan melalui pfh (kecuali pfh penunjuk null).

Keterangan

Fungsi _sopen_s membuka file yang ditentukan oleh filename dan menyiapkan file untuk pembacaan atau penulisan bersama, seperti yang didefinisikan oleh oflag dan shflag. _wsopen_s adalah versi karakter luas dari _sopen_s; filename argumen ke _wsopen_s adalah string karakter lebar. _wsopen_s dan _sopen_s berulah secara identik jika tidak.

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

Pemetaan rutin teks generik

Tchar.h Rutin	_UNICODE dan _MBCS tidak ditentukan	_MBCS Didefinisikan	_UNICODE Didefinisikan
_tsopen_s	_sopen_s	_sopen_s	_wsopen_s

Ekspresi oflag bilangan bulat dibentuk dengan menggabungkan satu atau beberapa konstanta manifes, yang didefinisikan dalam <fcntl.h>. Ketika dua konstanta atau lebih membentuk argumen oflag, konstanta tersebut dikombinasikan dengan operator bitwise-OR ( | ).

konstanta oflag	Perilaku
_O_APPEND	Memindahkan penunjuk file ke akhir file sebelum setiap operasi tulis.
_O_BINARY	Membuka file dalam mode biner (tidak diterjemahkan). (Lihat fopen untuk deskripsi mode biner.)
_O_CREAT	Membuat file dan membukanya untuk ditulis. Tidak berpengaruh jika file yang ditentukan oleh filename ada. Argumen pmode diperlukan ketika _O_CREAT ditentukan.
_O_CREAT | _O_SHORT_LIVED	Membuat file sebagai sementara dan jika memungkinkan tidak memerah ke disk. Argumen pmode diperlukan ketika _O_CREAT ditentukan.
_O_CREAT | _O_TEMPORARY	Membuat file sebagai sementara; file dihapus ketika pendeskripsi file terakhir ditutup. Argumen pmode diperlukan ketika _O_CREAT ditentukan. Untuk mempertahankan perilaku warisan untuk kompatibilitas aplikasi, proses lain tidak dicegah menghapus file ini.
_O_CREAT | _O_EXCL	Mengembalikan nilai kesalahan jika file yang ditentukan oleh filename ada. Hanya berlaku saat digunakan dengan _O_CREAT.
_O_NOINHERIT	Mencegah pembuatan deskriptor file bersama.
_O_RANDOM	Menentukan bahwa penembolokan dioptimalkan untuk, tetapi tidak dibatasi, akses acak dari disk.
_O_RDONLY	Membuka file untuk dibaca saja. Tidak dapat ditentukan dengan _O_RDWR atau _O_WRONLY.
_O_RDWR	Membuka file untuk membaca dan menulis. Tidak dapat ditentukan dengan _O_RDONLY atau _O_WRONLY.
_O_SEQUENTIAL	Menentukan bahwa penembolokan dioptimalkan untuk, tetapi tidak dibatasi, akses berurutan dari disk.
_O_TEXT	Membuka file dalam mode teks ANSI (diterjemahkan). (Untuk informasi selengkapnya, lihat Teks dan file mode biner I/O dan fopen.)
_O_TRUNC	Membuka file dan memotongnya menjadi panjang nol; file harus memiliki izin tulis. Tidak dapat ditentukan dengan _O_RDONLY. _O_TRUNC digunakan dengan _O_CREAT membuka file yang ada atau membuat file. Catatan: Bendera _O_TRUNC menghancurkan konten file yang ditentukan.
_O_WRONLY	Membuka file hanya untuk menulis. Tidak dapat ditentukan dengan _O_RDONLY atau _O_RDWR.
_O_U16TEXT	Membuka file dalam mode Unicode UTF-16.
_O_U8TEXT	Membuka file dalam mode Unicode UTF-8.
_O_WTEXT	Membuka file dalam mode Unicode.

Untuk menentukan mode akses file, Anda harus menentukan _O_RDONLY, , _O_RDWRatau _O_WRONLY. Tidak ada nilai default untuk mode akses.

Ketika file dibuka dalam mode Unicode dengan menggunakan _O_WTEXTfungsi input , , _O_U8TEXTatau _O_U16TEXT, 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 _sopen_s dipanggil dengan _O_WRONLY | _O_APPEND (mode tambahan) dan _O_WTEXT, , _O_U16TEXTatau _O_U8TEXT, pertama-tama mencoba membuka file untuk membaca dan menulis, baca BOM, lalu buka kembali untuk menulis saja. Jika membuka file untuk membaca dan menulis gagal, file hanya akan terbuka untuk menulis dan menggunakan nilai default untuk pengaturan mode Unicode.

Argumen shflag adalah ekspresi konstanta yang terdiri dari salah satu konstanta manifes berikut, yang didefinisikan dalam <share.h>.

konstanta shflag	Perilaku
_SH_DENYRW	Menolak akses baca dan tulis ke file.
_SH_DENYWR	Menolak akses tulis ke file.
_SH_DENYRD	Menolak akses baca ke file.
_SH_DENYNO	Mengizinkan akses baca dan tulis.

Argumen pmode selalu diperlukan, tidak seperti di _sopen. Saat Anda menentukan _O_CREAT, jika file tidak ada, pmode tentukan pengaturan izin file, yang diatur saat file baru ditutup untuk pertama kalinya. Jika tidak, pmode diabaikan. pmode adalah ekspresi bilangan bulat yang berisi satu atau kedua konstanta _S_IWRITE manifes dan _S_IREAD, yang didefinisikan dalam <sys\stat.h>. Ketika kedua konstanta diberikan, konstanta tersebut dikombinasikan dengan operator bitwise-OR. Artinya pmode adalah sebagai berikut.

pmode	Makna
_S_IREAD	Hanya membaca yang diizinkan.
_S_IWRITE	Penulisan diizinkan. (Berlaku, mengizinkan pembacaan dan penulisan.)
_S_IREAD | _S_IWRITE	Membaca dan menulis diizinkan.

Jika izin tulis tidak diberikan, file bersifat baca-saja. Dalam sistem operasi Windows, semua file dapat dibaca; tidak dimungkinkan untuk memberikan izin tulis-saja. Oleh karena itu, mode _S_IWRITE dan _S_IREAD | _S_IWRITE setara.

_sopen_s menerapkan masker izin file saat ini ke pmode sebelum izin diatur. (Lihat _umask.)

Persyaratan

Fungsi	Header yang diperlukan	Header opsional
_sopen_s	<io.h>	<fcntl.h>, , <sys\types.h><sys\stat.h>,<share.h>
_wsopen_s	<io.h> atau <wchar.h>	<fcntl.h>, , <sys/types.h><sys/stat.h>,<share.h>

_sopen_s dan _wsopen_s merupakan ekstensi Microsoft. Untuk informasi kompatibilitas selengkapnya, lihat Kompatibilitas.

Contoh

Lihat contoh untuk _locking.

Lihat juga

I/O tingkat rendah
_close
_creat, _wcreat
fopen, _wfopen
_fsopen, _wfsopen
_open, _wopen