Opens a file. These functions are deprecated because more-secure versions are available; see_sopen_s,_wsopen_s.

Syntax

int _open(   const char *filename,   int oflag [,   int pmode]);int _wopen(   const wchar_t *filename,   int oflag [,   int pmode]);

Parameters

filename
File name.

oflag
The kind of operations allowed.

pmode
Permission mode.

Return value

Each of these functions returns a file descriptor for the opened file. A return value of -1 indicates an error; in that caseerrno is set to one of the following values.

For more information about these and other return codes, seeerrno,_doserrno,_sys_errlist, and_sys_nerr.

Remarks

The_open function opens the file specified byfilename and prepares it for reading or writing, as specified byoflag._wopen is a wide-character version of_open; thefilename argument to_wopen is a wide-character string._wopen and_open behave identically otherwise.

Generic-text routine mappings

oflag is an integer expression formed from one or more of the following manifest constants or constant combinations, which are defined in<fcntl.h>.

To specify the file access mode, you must specify either_O_RDONLY,_O_RDWR, or_O_WRONLY. There's no default value for the access mode.

If_O_WTEXT is used to open a file for reading,_open reads the beginning of the file and checks for a byte order mark (BOM). If there's a BOM, the file is treated as UTF-8 or UTF-16LE, depending on the BOM. If no BOM is present, the file is treated as ANSI. When a file is opened for writing by using_O_WTEXT, UTF-16 is used. Regardless of any previous setting or byte order mark, if_O_U8TEXT is used, the file is always opened as UTF-8; if_O_U16TEXT is used, the file is always opened as UTF-16.

When a file is opened in Unicode mode by using_O_WTEXT,_O_U8TEXT, or_O_U16TEXT, input functions translate the data that's read from the file into UTF-16 data stored as typewchar_t. Functions that write to a file opened in Unicode mode expect buffers that contain UTF-16 data stored as typewchar_t. If the file is encoded as UTF-8, then UTF-16 data is translated into UTF-8 when it's written. The file's UTF-8-encoded content is translated into UTF-16 when it's read. An attempt to read or write an odd number of bytes in Unicode mode causes a parameter validation error. To read or write data that's stored in your program as UTF-8, use a text or binary file mode instead of a Unicode mode. You're responsible for any required encoding translation.

If_open is called with_O_WRONLY | _O_APPEND (append mode) and_O_WTEXT,_O_U16TEXT, or_O_U8TEXT, it first tries to open the file for reading and writing, read the BOM, then reopen it for writing only. If opening the file for reading and writing fails, it opens the file for writing only and uses the default value for the Unicode mode setting.

When two or more manifest constants are used to form theoflag argument, the constants are combined with the bitwise-OR operator (| ). For a discussion of binary and text modes, seeText and binary mode file I/O.

Thepmode argument is required only when_O_CREAT is specified. If the file already exists,pmode is ignored. Otherwise,pmode specifies the file permission settings, which are set when the new file is closed the first time._open applies the current file-permission mask topmode before the permissions are set. For more information, see_umask.pmode is an integer expression that contains one or both of the following manifest constants, which are defined in<sys\stat.h>.

When both constants are given, they're joined with the bitwise-OR operator (| ). In Windows, all files are readable; write-only permission isn't available. Therefore, the modes_S_IWRITE and_S_IREAD |_S_IWRITE are equivalent.

If a value other than some combination of_S_IREAD and_S_IWRITE is specified forpmode—even if it would specify a validpmode in another operating system—or if any value other than the allowedoflag values is specified, the function generates an assertion in Debug mode and invokes the invalid parameter handler, as described inParameter validation. If execution is allowed to continue, the function returns -1 and setserrno toEINVAL.

Requirements

_open and_wopen are Microsoft extensions. For more compatibility information, seeCompatibility.

Libraries

All versions of theC run-time libraries.

Example

// crt_open.c// compile with: /W3/* This program uses _open to open a file* named CRT_OPEN.C for input and a file named CRT_OPEN.OUT* for output. The files are then closed.*/#include <fcntl.h>#include <sys/types.h>#include <sys/stat.h>#include <io.h>#include <stdio.h>int main( void ){   int fh1, fh2;   fh1 = _open( "CRT_OPEN.C", _O_RDONLY ); // C4996   // Note: _open is deprecated; consider using _sopen_s instead   if( fh1 == -1 )      perror( "Open failed on input file" );   else   {      printf( "Open succeeded on input file\n" );      _close( fh1 );   }   fh2 = _open( "CRT_OPEN.OUT",                _O_WRONLY | _O_CREAT,                _S_IREAD | _S_IWRITE ); // C4996   if( fh2 == -1 )      perror( "Open failed on output file" );   else   {      printf( "Open succeeded on output file\n" );      _close( fh2 );   }}

Output

Open succeeded on input fileOpen succeeded on output file

See also

Low-level I/O
_chmod,_wchmod
_close
_creat,_wcreat
_dup,_dup2
fopen,_wfopen
_sopen,_wsopen