### open -- Open File

Format

>     #include <io.h>
>     #include <fcntl.h>
>     #include <sys\stat.h>
>     int open(char *pathname, int oflag, int pmode);

Language Level: XPG4, Extension
open opens the file specified by pathname and prepares the file for subsequent reading or writing as defined by oflag. open can also prepare the file for reading and writing.

The oflag is an integer expression formed by combining one or more of the following constants, defined in <fcntl.h>. To specify more than one constant, join the constants with the bitwise OR operator (|); for example, O_CREAT | O_TEXT.

Oflag | Meaning
O_APPEND | Reposition the file pointer to the end of the file before every write operation.
O_CREAT | Create and open a new file. This flag has no effect if the file specified by pathname exists.
O_EXCL | Return an error value if the file specified by pathname exists. This flag applies only when used with O_CREAT.
O_RDONLY | Open the file for reading only. If this flag is given, neither O_RDWR nor O_WRONLY can be given.
O_RDWR | Open the file for reading and writing. If this flag is given, neither O_RDONLY nor O_WRONLY can be given.
O_TRUNC | Open and truncate an existing file to 0 length. The file must have write permission. The contents of the file are destroyed, and O_TRUNC cannot be specified with O_RDONLY.
O_WRONLY | Open the file for writing only. If this flag is given, neither O_RDONLY nor O_RDWR can be given.
O_BINARY | Open the file in binary (untranslated) mode.
O_TEXT | Open the file in text (translated) mode.

If neither O_BINARY or O_TEXT is specified, the default will be O_TEXT; it is an error to specify both O_BINARY and O_TEXT. You must specify one of the access mode flags, O_RDONLY, O_WRONLY, or O_RDWR. There is no default.

Warning! Use O_TRUNC with care; it destroys the complete contents of an existing file.

The pmode argument is an integer expression containing one or both of the constants S_IWRITE and S_IREAD, defined in <sys\stat.h>. The pmode is required only when O_CREAT is specified. If the file exists, pmode is ignored. Otherwise, pmode specifies the permission settings for the file. These are set when the new file is closed for the first time. The meaning of the pmode argument is as follows:

Value | Meaning
S_IWRITE | Writing permitted
S_IREAD | Reading permitted
S_IREAD | S_IWRITE | Reading and writing permitted.

If write permission is not given, the file is read-only.

All files are readable; you cannot give write-only permission. The modes S_IWRITE and S_IREAD | S_IWRITE are equivalent.

open applies the current file permission mask to pmode before setting the permissions.

Note: In earlier releases of the C/C++ run-time library, open began with an underscore (_open). Because it is defined by the X/Open standard, the underscore has been removed. For compatibility, IBM C and C++ Compilers will map _open to open for you.

Return Value
open returns a file handle for the opened file. A return value of -1 indicates an error, and errno is set to one of the following values:

Value | Meaning
EACCESS | The given pathname is a directory; or the file is read-only but an open for writing was attempted; or a sharing violation occurred.
EEXIST | The O_CREAT and O_EXCL flags are specified, but the named file already exists.
EMFILE | No more file handles are available.
EINVAL | An incorrect argument was passed.
ENOENT | The file or pathname were not found.
EOS2ERR | The call to the operating system was not successful.

Example
This example opens the file edopen.dat by creating it as a new file, truncating it if it exists, and opening it so it can be read and written to. The open command issued also grants permission to read from and write to the file.

    #include <io.h>
    #include <stdio.h>
    #include <fcntl.h>
    #include <sys\stat.h>
    #include <stdlib.h>

    int main(void)
    {
       int fh;

       if (-1 == (fh = open("edopen.dat", O_CREAT|O_TRUNC|O_RDWR,
                             S_IREAD|S_IWRITE))) {
          perror("Unable to open edopen.dat");
          return EXIT_FAILURE;
       }
       printf("File was successfully opened.\n");
       if (-1 == close(fh)) {
          perror("close error");
          return EXIT_FAILURE;
       }
       return 0;

       /**********************************************************
          The output should be:

          File was successfully opened.
       **********************************************************/
    }

Stream Processing

close -- Close File Associated with Handle
creat -- Create New File
fdopen -- Associates Input Or Output With File
fopen -- Open Files
_sopen -- Open Shared File
umask -- Sets File Mask of Current Process
<fcntl.h>
<io.h>
<sys\stat.h>