OSF  —  Environment_Note_Added

NAME

open, creat − Opens a file for reading or writing

SYNOPSIS

#include <fcntl.h>
#include <sys/stat.h>
#include <sys/types.h> int open (
const char ∗path,
int oflag [ ,
mode_t mode ] ); int creat (
const char ∗path,
mode_t mode );

PARAMETERS

pathSpecifies the file to be opened or created.  If the path parameter refers to a symbolic link, the open() function opens the file pointed to by the symbolic link.

oflagSpecifies the type of access, special open processing, the type of update, and the initial state of the open file. The parameter value is constructed by logically ORing special open processing flags. These flags are defined in the fcntl.h header file and are described below. 

modeSpecifies the read, write, and execute permissions of the file to be created (requested by the O_CREAT flag in the open() interface). If the file already exists, this parameter is ignored. This parameter is constructed by logically ORing values described in the sys/mode.h header file. 

DESCRIPTION

The open() and creat() functions establish a connection between the file named by the path parameter and a file descriptor. The opened file descriptor is used by subsequent I/O functions, such as read() and write(), to access that file.

The returned file descriptor is the lowest file descriptor not previously open for that process. No process can have more than OPEN_MAX file descriptors open simultaneously. 

The open() and creat() functions, which suspend the calling process until the request is completed, are redefined so that only the calling thread is suspended.

The file offset, marking the current position within the file, is set to the beginning of the file. The new file descriptor is set to remain open across exec functions. (See the fcntl() function.)

The file status flags and file access flags are designated by the oflag parameter.  The oflag parameter is constructed by bitwise-inclusive ORing exactly one of the file access flags (O_RDONLY, O_WRONLY, or O_RDWR) with one or more of the file status flags. 

File Access Flags

The file access flags are as follows:

O_RDONLYThe file is open for reading only. 

O_WRONLY
The file is open for writing only.

O_RDWRThe file is open for reading and writing. 

Exactly one of the file access values (O_RDONLY, O_WRONLY, or O_RDWR) must be specified.  If none is set, O_RDONLY is assumed. 

File Status Flags

File status flags that specify special open processing are as follows:

O_CREATIf the file exists, this flag has no effect except as noted under O_EXCL. If the file does not exist, a regular file is created with the following characteristics:

       •The owner ID of the file is set to the effective user ID of the process. 

       •The group ID of the file is set to the group ID of its parent directory. 

       •The file permission and attribute bits are set to the value of the mode parameter, modified as follows:

       —
All bits set in the process file mode creation mask are cleared.

       —
The set-user ID attribute (S_ISUID bit) is cleared.

       —
The set-group ID attribute (S_ISGID bit) is cleared.

       —
The S_ISVTX attribute bit is cleared.

The calling process must have write permission to the file’s parent directory with respect to all access control policies to create a new file. 

O_EXCLIf O_EXCL and O_CREAT are set, the open fails if the file exists. 

O_NOCTTY
If the path parameter identifies a terminal device, this flag assures that the terminal device does not become the controlling terminal for the process. 

O_TRUNCIf the file does not exist, this flag has no effect. If the file exists and is a regular file, and if the file is successfully opened O_RDWR or O_WRONLY:

       •The length of the file is truncated to 0 (zero). 

       •The owner and group of the file are unchanged. 

       •The set-user ID attribute of the file mode is cleared. 

       •The set-user ID attribute of the file is cleared. 

The open fails if either of the following conditions are true:

       •The file supports enforced record locks and another process has locked a portion of the file. 

       •The file does not allow write access. 

If the oflag parameter also specifies O_SYNC, the truncation is a synchronous update.  A program can request some control over when updates should be made permanent for a regular file opened for write access.

File status flags that define the initial state of the open file are as follows:

O_SYNCIf set, updates and writes to regular files and block devices are synchronous updates.  File update is performed by:

       •fclear()

       •ftruncate()

       •open() with O_TRUNC

       •write()

On return from a function that performs a synchronous update (any of the above system calls, when O_SYNC is set), the calling process is assured that all data for the file has been written to permanent storage, even if the file is also open for deferred update.

O_APPENDIf set, the file pointer is set to the end of the file prior to each write. 

O_NONBLOCK, O_NDELAY
If set, the call to open() will not block, and subsequent read() or write() operations on the file will be nonblocking.

General Notes on oflag Parameter Flag Values

The effect of O_CREAT is immediate. 

When opening a FIFO with O_RDONLY:

       •If neither O_NDELAY nor O_NONBLOCK is set, the open() function blocks until another process opens the file for writing. If the file is already open for writing (even by the calling process), the open() function returns without delay.

       •If O_NDELAY or O_NONBLOCK is set, the open() function returns immediately.

When opening a FIFO with O_WRONLY:

       •If neither O_NDELAY nor O_NONBLOCK is set, the open() function blocks until another process opens the file for reading. If the file is already open for reading (even by the calling process), the open() function returns without delay.

       •If O_NDELAY or O_NONBLOCK is set, the open() function returns an error if no process currently has the file open for reading.

When opening a block special or character special file that supports nonblocking opens, such as a terminal device:

       •If neither O_NDELAY nor O_NONBLOCK is set, the open() function blocks until the device is ready or available.

       •If O_NDELAY or O_NONBLOCK is set, the open() function returns without waiting for the device to be ready or available. Subsequent behavior of the device is device-specific.

When opening a STREAMS file, oflag may be constructed from O_NDELAY or O_NONBLOCK or-ed with either O_RDONLY, O_WRONLY or O_RDWR.  Other flag values are not applicable to STREAMS devices and have no effect on them.  The value of O_NDELAY or NON_BLOCK affects the operation of STREAMS drivers and certain system calls [see read(), getmsg(), putmsg() and write()].  For drivers, the implementation of O_NDELAY or NON_BLOCK is device-specific.  Each STREAMS device driver may treat this option differently. 

NOTES

AES Support Level:
Full use

RETURN VALUES

Upon successful completion, the open() and creat() functions return the file descriptor, a nonnegative integer. Otherwise, a value of -1 is returned and errno is set to indicate the error. 

ERRORS

If the open() or creat() function fails, errno may be set to one of the following values:

[ENXIO]A STREAMS module or driver open routine failed. 

[EIO]A hangup or error occurred during a STREAMS open(). 

[EMULTIHOP]
Components of path require hopping to multiple remote machines. 

[ENOLINK]Path points to a remote machine, and the link to that machine is no longer active. 

[ENOMEM]The system is unable to allocate a send descriptor. 

[ENOSR]Unable to allocate a stream. 

[EACCES]Search permission is denied on a component of the path prefix, or the type of access specified by the oflag parameter is denied for the named file, or the file does not exist and write permission is denied for the parent directory, or O_TRUNC is specified and write permission is denied. 

[EAGAIN]The O_TRUNC flag is set, the named file exists with enforced record locking enabled, and there are record locks on the file. 

[EDQUOT]The directory in which the entry for the new link is being placed cannot be extended because the quota of disk blocks or i-nodes defined for the user on the file system containing the directory has been exhausted. 

[EEXIST]The O_CREAT and O_EXCL flags are set and the named file exists. 

[EFAULT]The path parameter is an invalid address. 

[EINTR]A signal was caught during the open() function.

[EISDIR]The named file is a directory and write access is requested. 

[ELOOP]Too many links were encountered in translating path. 

[EMFILE]The system limit for open file descriptors per process has already reached OPEN_MAX. 

[ENAMETOOLONG]
The length of the path string exceeds PATH_MAX, or a pathname component is longer than NAME_MAX. 

[ENFILE]The system file table is full. 

[ENOENT]The O_CREAT flag is not set and the named file does not exist, or O_CREAT is set and the path prefix does not exist, or the path parameter points to the empty string. 

[ENOSPC]The directory that would contain the new file cannot be extended, the file does not exist, and O_CREAT is requested. 

[ENOTDIR]A component of the path prefix is not a directory. 

[ENXIO]The named file is a character special or block special file, and the device associated with this special file does not exist.  The named file is a multiplexed special file and either the channel number is outside of the valid range or no more channels are available. The O_NONBLOCK flag is set, the named file is a FIFO, O_WRONLY is set, and no process has the file open for reading.

EOPNOTSUPP
The named file is a socket bound to the file system (a UNIX domain socket) and cannot be opened.

[EROFS]The named file resides on a read-only file system and write access is required. 

[ETXTBSY]The file is being executed and oflag is O_WRONLY or O_RDWR. 

ENVIRONMENT NOTES

This section describes system features that are not generic to OSF/1 but that are provided in this OSF/1 implementation. 

Digital Extensions

Description

The returned file descriptor is the lowest file descriptor not previously open for that process. Processes have a fixed limit on the number of file descriptors they can have open simultaneously.  Use getdtablesize(2) to find this system defined limit. 

Errors

If the open() or creat() function fails, errno may be set to one of the following values:

[EMFILE]The system limit for open file descriptors has already been reached. 

[ENOMEM]The system was unable to allocate kernel memory for more file descriptors. 

RELATED INFORMATION

Functions: getdtablesize(2)
 

RELATED INFORMATION

Functions: chmod(2), close(2), fcntl(2), getmsg(2), lseek(2), putmsg(2) read(2), stat(2), truncate(2), umask(2), write(2), lockf(3)