 |
» |
|
|
|
Opens a file and returns its file descriptor. Syntax | |
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int open (const char *pathname, int oflag, ...);
|
Parameters | |
- pathname
A pointer to a string containing a pathname of a file to be opened. The pathname must be terminated by a null character.
- oflag
A value specifying the file status and file access modes of the file to be opened. If O_CREAT is specified, the mode of the file must be passed in a third parameter, modes.
The value of oflag is the bitwise inclusive OR of flags from the following two lists (defined in <fcntl.h>).
Only one of the following three flags must be specified in oflag:
- O_RDONLY
Open for reading only.
- O_WRONLY
Open for writing only.
- O_RDWR
Open for both reading and writing.
If the file is opened O_WRONLY or O_RDWR, the st_mtime file time field is marked for update. If the file is opened O_RDONLY or O_RDWR, the st_atime file time field is marked for update.
Any combination of the following optional flags may also be specified in oflag:
- O_APPEND
The file offset is set to the end of the file prior to each write.
- O_CREAT
This option requires a third parameter, mode, which is of type mode_t. If the optional third parameter is not passed when O_CREAT is specified, open() attempts to read invalid data off the stack, and the results are indeterminate. If the file exists, this flag has no effect, except as noted under O_EXCL, below.
If the file is created, the following occurs:
The file offset is set to the beginning of the file (where the offset position is 0).
The file's UID is set to the effective UID of the calling process.
The file's GID is set to the GID of the directory in which the file is being created.
The access permission bits of the file are set to mode and modified by the file mode creation mask of the calling process.
The following file time fields are marked for update: The file's st_atime, st_ctime and st_mtime time fields.
The parent directory's st_ctime and st_mtime time fields.
- O_EXCL
The file is opened for exclusive access by the calling process. An error results if both O_EXCL and O_CREAT are specified for an existing file.
An existing file can be opened with O_EXCL and without O_CREAT only if the file is not currently open by another process (otherwise, an error results).
- O_TRUNC
If the file exists and opened O_TRUNC and either O_RDWR or O_WRONLY, it is truncated to zero length and the mode and owner remain unchanged. The file offset is set to the beginning of the file (where the offset position is 0).
An error results if the file is opened O_TRUNC and O_RDONLY.
If O_TRUNC is specified for an existing file, the st_ctime and st_mtime time fields of the file are marked for update.
If oflag specifies O_CREAT, mode, a structure of type mode_t, must be passed to specify the access permission bits that the file is to be created with. Access permission bits are set by ORing any combination of the following macros:
- S_IRWXU
Set file owner class read, write, and execute (if a file) or search (if a directory) permission bits.
- S_IRUSR
Set file owner class read permission bit.
- S_IWUSR
Set file owner class write permission bit.
- S_IXUSR
Set file owner class execute (if a file) or search (if a directory) permission bit.
- S_IRWXG
Set file group class read, write, and execute (if a file) or search (if a directory) permission bits.
- S_IRGRP
Set file group class read permission bit.
- S_IWGRP
Set file group class write permission bit.
- S_IXGRP
Set file group class execute (if a file) or search (if a directory) permission bit.
- S_IRWXO
Set file other class read, write, and execute (if a file), or search (if a directory) permission bits.
- S_IROTH
Set file other class read permission bit.
- S_IWOTH
Set file other class write permission bit.
- S_IXOTH
Set file other class execute (if a file) or search (if a directory) permission bit.
Bits that are not access permission bits must contain zeros, or an error is returned.
Return Values | |
- >=0
Success. A nonnegative integer is returned representing the lowest numbered file descriptor not open by the calling process.
- -1
An error occurred. The file is not opened, and errno is set to indicate the error condition.
Description | |
The open() function establishes the connection between a file specified by pathname and a file descriptor. It creates an open file description that refers to the file and a file descriptor that refers to that open file description. The file descriptor is used by other I/O functions to refer to the file. The open() function returns a file descriptor for the specified file, which is the lowest file descriptor not currently open for the calling process. The open file description is new; therefore, the file descriptor does not share it with any other process in the system. Implementation Considerations | |
Refer to the EACCES, EMFILE, EEXCL, EFAULT, EIMPL, EINVAL, and ESYSERR error descriptions below. Pipes (or FIFOs), device special files, and read-only file systems are not supported through POSIX/iX interfaces and cannot be opened by open(). Device files are inherited from the parent process, which has them opened as STDIN_FILENO, STDOUT_FILENO, and STDERR_FILENO. The GID of a newly created file is set to the GID of the directory in which the file is created. MPE/iX file equations are ignored by open(). The calling process must have the correct access permissions as defined by either an attached ACD or by the MPE/iX file
security matrix. For example, a file opened O_RDONLY must have either ACD read access or MPE/iX read access. A file opened O_WRONLY or O_RDWR must have either ACD write access and append access or MPE/iX write access and append access. Signals generated for the calling process during execution of open() are deferred from delivery until completion of this function. Errors | |
If an error occurs, errno is set to one of the following values: | EACCES | CAUSE | One of the following: The calling process does not have search permission to a component of the pathname.
The file does not exist and the calling process does not have write permission to the parent directory of the file to be created.
The file exists and the permissions specified by oflag are denied.
Both O_TRUNC and O_RDONLY were specified.
Both O_APPEND and O_RDONLY were specified.
An MPE/iX lockword is associated with the file.
| | ACTION | One of the following: Make sure that the calling process has search permission to all directory components of the pathname.
Make sure that the calling process has write permission to the parent directory of the file to be created.
Specify valid and compatible flags in oflag.
Remove the MPE/iX lockword.
| | | EEXCL | CAUSE | Attempt to open an existing file exclusively failed because file
is already opened. | | | ACTION | Check for ownership of previously opened file. Check file's permission
bits. | | EEXIST | CAUSE | O_CREAT and O_EXCL are set, and the named file exists. | | | ACTION | Open the file a different way, or remove the file. | | EFAULT | CAUSE | The system detected a NULL or bad address in attempting to use
the pathname parameter, or the pathname was not terminated by a null character. | | | ACTION | Make sure that the pointer is correctly initialized. | | EIMPL | CAUSE | One of the following: The specified file is not a byte-stream file.
The pathname began with two slash characters (//).
Bits in mode that are not file permission bits did not contain zeros.
An attempt was made to create a file in an MPE/iX account.
An attempt was made to create a file with a name that exceeds 16 characters in the root directory or an MPE/iX group.
| | | ACTION | One of the following: Open only byte-stream files.
Do not begin a pathname with two slash characters (//).
Set bits in mode that are not file permission bits to zero.
Do not create files in an MPE/iX account.
Do not attempt to create a file with a name which exceeds 16 characters in the root directory or an MPE/iX group.
| | EINVAL | CAUSE | More than one of the following three open flags were specified in oflag: O_WRONLY, O_RDONLY, and O_RDWR. | | | ACTION | Specify only one of the open flags in oflag. | | EISDIR | CAUSE | The pathname specifies a directory to be opened. | | | ACTION | Use opendir() to open a directory file. | | EMFILE | CAUSE | The number of open files and directories would exceed {OPEN_MAX}, the limit of opened files per process. | | | ACTION | Reduce the number of files and directories opened by the calling process. | | ENAMETOOLONG | CAUSE | One of the following: The length of the pathname exceeds the {PATH_MAX} limit (defined in the file <limits.h>).
A component of the pathname is longer than {NAME_MAX} (defined in <limits.h>), and {_POSIX_NO_TRUNC} is in effect for that directory.
| | | ACTION | Make sure that both the component's length and the full pathname
length do not exceed the {NAME_MAX} or {PATH_MAX} limits. | | ENOENT | CAUSE | The O_CREAT option is not set, and the named file does not exist; or the O_CREAT option is set, and the pathname does not exist; or pathname points to an empty string. | | | ACTION | Specify a valid pathname. | | ENOSPC | CAUSE | Creation of the file would exceed the disk space limits imposed by the MPE/iX accounting facility, or there is not enough free disk space to create the file. | | | ACTION | Extend accounting limits for the directory in which the file is located, or free up disk space. | | ENOTDIR | CAUSE | A component of the pathname is not a directory. | | | ACTION | Specify a valid pathname. | | ESYSERR | CAUSE | An operating system error has occurred that does not map directly to any of the above errors. | | | ACTION | Examine the MPE/iX error stack for the type of system error. |
See Also | |
close(), creat(), dup(), execl(), execv(), <fcntl.h>, lseek(), read(), <signal.h>, fstat(), stat(), <stat.h>, write(), umask(), POSIX.1 (Section 5.3.1) |
