_open, _wopen

Open a file.

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

Parameters

filename

Filename.

oflag

Type 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 which case errno is set to one of the following values:

EACCES

Tried to open read-only file for writing, or file's sharing mode does not allow specified operations, or given path is directory.

EEXIST

_O_CREAT and _O_EXCL flags specified, but filename already exists.

EINVAL

Invalid oflag or pmode argument.

EMFILE

No more file descriptors available (too many open files).

ENOENT

File or path not found.

See _doserrno, errno, _sys_errlist, and _sys_nerr for more information on these, and other, return codes.

Remarks

The _open function opens the file specified by filename and prepares the file for reading or writing, as specified by oflag. _wopen is a wide-character version of _open; the filename 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 defined in FCNTL.H:

_O_APPEND

Moves file pointer to end of file before every write operation.

_O_BINARY

Opens file in binary (untranslated) mode. (See fopen for a description of binary mode.)

_O_CREAT

Creates and opens new file for writing. Has no effect if file specified by filename exists. pmode argument is required when _O_CREAT is specified.

_O_CREAT | _O_SHORT_LIVED

Create file as temporary and if possible do not flush to disk. pmode argument is required when _O_CREAT is specified.

_O_CREAT | _O_TEMPORARY

Create file as temporary; file is deleted when last file descriptor is closed. pmode argument is required when _O_CREAT is specified.

_O_CREAT | _O_EXCL

Returns error value if file specified by filename exists. Applies only when used with _O_CREAT.

_O_RANDOM

Specifies that caching is optimized for, but not restricted to, random access from disk.

_O_RDONLY

Opens file for reading only; cannot be specified with _O_RDWR or _O_WRONLY.

_O_RDWR

Opens file for both reading and writing; you cannot specify this flag with _O_RDONLY or _O_WRONLY.

_O_SEQUENTIAL

Specifies that caching is optimized for, but not restricted to, sequential access from disk.

_O_TEXT

Opens file in text (translated) mode. (For more information, see Text and Binary Mode File I/O and fopen.)

_O_TRUNC

Opens file and truncates it to zero length; file must have write permission. You cannot specify this flag with _O_RDONLY. _O_TRUNC used with _O_CREAT opens an existing file or creates a new file.

Note   The _O_TRUNC flag destroys the contents of the specified file.

_O_WRONLY

Opens file for writing only; cannot be specified with _O_RDONLY or _O_RDWR.

To specify the file access mode, you must specify either _O_RDONLY, _O_RDWR, or _O_WRONLY. There is no default value for the access mode.

When two or more manifest constants are used to form the oflag argument, the constants are combined with the bitwise-OR operator ( | ). See Text and Binary Mode File I/O for a discussion of binary and text modes.

The pmode 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 to pmode before setting the permissions (for more information, see _umask). pmode is an integer expression containing one or both of the following manifest constants, defined in SYS\STAT.H:

_S_IREAD

Reading only permitted.

_S_IWRITE

Writing permitted (effectively permits reading and writing).

_S_IREAD | _S_IWRITE

Reading and writing permitted.

When both constants are given, they are joined with the bitwise-OR operator ( | ). In Windows NT, all files are readable, so write-only permission is not available; thus the modes _S_IWRITE and _S_IREAD | _S_IWRITE are equivalent.

Requirements

For additional compatibility information, see Compatibility in the Introduction.

Libraries

All versions of the C run-time libraries.

Example

// crt_open.c
/* 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 );
   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 );
   if( fh2 == -1 )
      perror( "Open failed on output file" );
   else
   {
      printf( "Open succeeded on output file\n" );
      _close( fh2 );
   }
}

Output

Open succeeded on input file
Open succeeded on output file

See Also

Low-Level I/O Routines | _chmod | _close | _creat | _dup | fopen | _sopen | Run-Time Routines and .NET Framework Equivalents