open, open64, openat, openat64 - open file

Syntax

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>

int open (const char *path, int oflag , .../* mode_t mode*/);
int open64 (const char *path, int oflag , .../* mode_t mode*/);
int openat (int fd, const char *path, int oflag , ...);
int openat64 (int fd, const char *path, int oflag , ...); 

Description

If POSIX files are executed, the behavior of this function conforms to the XPG4 standard as described below:

The open() function establishes the connection between a file and a file descriptor. It creates an open file description that refers to a 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 that file. The path argument points to a pathname naming the file.

open() will return a file descriptor for the named file that is the lowest file descriptor not currently open for that process. The open file description is new, and therefore the file descriptor does not share it with any other process in the system. The FD_CLOEXEC file descriptor flag associated with the new file descriptor will be cleared (see fcntl()).

The file position indicator is set to the beginning of the file.

The file status byte and file access modes of the open file description will be set according to the value of oflag.

Values for oflag are constructed by a bitwise-inclusive-OR of flags from the following list, defined in fcntl.h. Applications must specify exactly one of the first four values (file access modes) below in the value of oflag:

O_RDONLY	Open for reading only.
O_WRONLY	Open for writing only.
O_RDWR	Open for reading and writing. The result is undefined if this flag is applied to a FIFO file.
O_SEARCH	Open directory for searching. The result is undefined if this flag is not applied to a directory.

Any combination of the following flags may be used:

O_APPEND	The file position indicator is set to the end of the file prior to each write.
O_CREAT	If the file exists, this flag has no effect, except under the conditions noted under O_EXCL below. Otherwise, the file is created; the user ID of the file is set to the effective user ID of the process, and the group ID of the file is set to to the effective group ID of the process or the group ID of the file ́s parent directory. The access permission bits (see sys/stat.h) of the file mode are set to the value of mode and then modified as follows: a bitwise-AND is performed on the individual file-mode bits and the corresponding bits in the complement of the process ́ file mode creation mask (see umask()). Thus, all bits in the file mode for which a corresponding bit is set in the file mode creation mask are cleared. When bits other than the file permission bits are set, the effect is unspecified. The mode argument does not affect whether the file is opened for reading, writing or for both.
O_EXCL	open() will fail if O_CREAT and O_EXCL are set and the file exists. If the file does not exist, the two actions, i.e. the check for the existence of the file and the creation of the file, are treated as a single action that it is shielded from intervention by other processes executing open() for the same file name in the same directory with O_EXCL and O_CREAT set. If O_CREAT is not set, the effect is undefined.
O_NOCTTY	If this flag is set and path identifies a terminal device, open() will not cause the terminal device to become the controlling terminal for the process.
O_NONBLOCK	When opening a FIFO for reading or writing (O_RDONLY or O_WRONLY): If O_NONBLOCK is set: An open() for reading only will return without delay. An open() for writing only will return an error if no process currently has the file open for reading. If O_NONBLOCK is clear: An open() for reading only will block (i.e. wait) until a process opens the file for writing. An open() for writing only will block until a process opens the file for reading. When opening a block special or character special file that supports non-blocking opens: If O_NONBLOCK is set: open() will return without blocking for the device to be ready or available. Subsequent behavior of the device is device-specific. If O_NONBLOCK is clear: The open() function will block until the device is ready or available before returning. Otherwise, the behavior of O_NONBLOCK is undefined.
O_SYNC	If O_SYNC is set on a regular file, writes to that file will cause the process to block until the data is delivered to the underlying hardware.
O_TRUNC	If the file exists and is a regular file, and the file is successfully opened O_RDWR or O_WRONLY, its length is truncated to 0 and the mode and owner are unchanged. This has no effect on FIFO special files or terminal device files. The effect on other file types is implementation-dependent. The result of using O_TRUNC with O_RDONLY is undefined.
O_LARGEFILE	If specified, the offset maximum specified in the internal description of the open file is the highest value that can be correctly represented in an object of type off64_t .

If O_CREAT is set and the file did not previously exist, upon successful completion, open() will mark for update the st_atime, st_ctime and st_mtime fields of the file and the st_ctime and st_mtime fields of the parent directory.

If O_TRUNC is set and the file did previously exist, upon successful completion, open() will mark for update the st_ctime and st_mtime fields of the file.

There is no difference in functionality between open() and open64() except that open64() implicitly sets the O_LARGEFILE bit of the file status flag. The function open64() corresponds to using the function open() when O_LARGEFILE is set in oflag.

If threads are used, then the function affects the process or a thread in the following manner:

Opening a file; If O_NONBLOCK is not set in the parameter oflag, the following applies to FIFO: an open() for reading blocks the calling thread until a thread opens the file for writing. An open() for writing blocks the thread until a thread opens the file for reading. If a block-oriented or character-oriented device file is opened that supports non-waiting opens, the following applies: the open() function blocks the calling thread until the device has finished or is available.

Extension
If O_CREAT and O_EXCL are set and path is a symbolic link, the link is not followed.
(End)

BS2000
The following must be noted when executing BS2000 files:

const char *path is a string specifying the file to be opened. path can be any valid BS2000 file name.

• link=linkname linkname designates a BS2000 link name.

• (SYSDTA), (SYSOUT), (SYSLST), the corresponding system file

• (SYSTERM), terminal I/O

• (INCORE), temporary binary file that is created in virtual memory only.

oflag is a constant defined in the <stdio.h> header which specifies the desired access mode (or the corresponding octal value), namely:

O_RDONLY

0000

Open for reading. The file must already exist.

O_WRONLY

0001

Open for writing. The file must already exist. The previous contents are retained.

O_TRUNC|O_WRONLY

01001

Open for writing. If the file exists, the previous contents are deleted. If the file does not exist, it is created.

O_RDWR

0002

Open for reading and writing. The file must already exist. The previous contents are retained.

O_TRUNC|O_RDWR

01002

Open for reading and writing. If the file exists, the previous contents are deleted. If the file does not exist, it is created.

O_WRRD

0003

Open for writing and reading. If the file exists, the previous contents are deleted. If the file does not exist, it is created.

O_APPEND_OLD|O_TRUNC|O_WRONLY

0401

Open for appending to the end of the file. The file must already exist. The file is positioned to end of file, i.e. the previous contents are preserved and the new text is appended to the end of the file.

O_APPEND_OLD|O_RDWR

0402

Open for appending to the end of the file and for reading. The file must already exist. The old contents are preserved and the new text is appended to the end of the file. After it is opened, the file is positioned to the end of the file when KR functionality is being used (applies to C/C++ versions prior to V3.0 only), with ANSI functionality to the start of the file.

lbp switch

The lbp switch controls handling of the Last Byte Pointer (LBP). It is only relevant for binary files with PAM access mode and can be combined with all specifications permissible for open. If O_LBP is specified as the lbp switch, a check is made to see whether LBP support is possible. If this is not the case, the creat(), creat64() function will fail and errno is set to ENOSYS. The switch has further effects only when the file is closed.

When an existing file is opened and read, the LBP is always taken into account independently of the lbp switch:

• • • If the file's LBP is not equal to 0, it is evaluated. Any marker which is present is ignored.

    • When LBP = 0, a marker is searched for, and the file length is determined from this. If no marker is found, the end of the last complete block is regarded as the end of file.

O_LBP

When a file which has been modified or newly created is closed, no marker is written (even if one was present), and a valid LBP is set. In this way files with a marker can be converted to LBP without a marker. In the case of NK files the last logical block is padded with binary zeros, in the case of K files the file is padded to the physical end of file.

O_NOLBP

When a file which has been modified or newly created is closed, the LBP is set to zero (=invalid). A marker is written. In the case of NK files the last logical block is padded with binary zeros, in the case of K files the file is padded to the physical end of file.

When a file which has been modified or newly created is closed, the LBP is set to zero (=invalid). If the file had a valid LBP when it was opened, no marker is written as in this case it is assumed that no marker exists. In the case of NK files the last logical block is padded with binary zeros, in the case of K files the file is padded to the physical end of file.

If the lbp switch is specified in both variants (O_LBP and O_NOLBP), the creat(), creat64() function fails and errno is set to EINVAL.

If the lbp switch is not specified, the behavior depends on the environment variable LAST_BYTE_POINTER (see also section “Environment variables”):

LAST_BYTE_POINTER=YES

The function behaves as if O_LBP were specified.

LAST_BYTE_POINTER=NO

The function behaves as if O_NOLBP were specified.

Nosplit switch

This switch controls the processing of text files with SAM access mode and variable record length when a maximum record length is also specified. It can be combined with any of the other constants.

O_NOSPLIT

When reading with read, records of maximum length are not concatenated with the following record. When writing with write, records which are longer than the maximum record length are truncated to the maximum record length.

If the switch is not specified, the following applies:

• • • When writing
      A record which is longer than the maximum record length will be split into multiple records. If a record has precisely the maximum record length, a record of the length zero is written after it.

    • When reading
      If a record has the maximum record length, it is assumed that the following record is the continuation of this record and the records are concatenated.

The constant O_RECORD can be specified in the modus parameter to open files with recordoriented input/output (record I/O). It can always be combined with every other constant except O_LBP. Only in the case of ISAM files is adding to the end of the file not permitted, i.e. the combination with 0401 and 0402. With ISAM files the position is determined from the key in the record.

O_RECORD

This switch functions as follows:

• • • • • In the case of record I/O the read() function reads a record (or block) from the current file position. If the number n of the characters to be read is greater than the current record length, nevertheless only this record is read. If n is less than the current record length, only the first n characters are read. The data of the next record is read when the next read access takes place.

        • The write() function writes a record to the file. In the case of SAM and PAM files the record is written to the current file position. In the case of ISAM files the record is written to the position which corresponds to the key value in the record. If the number n of the characters to be written is greater than the maximum record length, only a record with the maximum record length is written. The remaining data is lost. In the case of ISAM files a record is written only if it contains at least a complete key. If in the case of files with a fixed record length n is less than the record length, binary zeros are used for padding. When a record is updated in a SAM or PAM file, the length of the record may not be modified. The write() function returns the number of actually written characters also in the case of record I/O.

(End)

The openat() and openat64() functions are equivalent to the open() and open64() functions except when the path parameter specifies a relative path. In this case the file to be opened is not opened in the current directory, but in the directory connected with the file descriptor fd. If the file descriptor was opened without O_SEARCH, the functions check whether a search is permitted in the connected directory with the authorizations applicable for the directory. If the file descriptor was opened with O_SEARCH, the check is not performed.

The oflag parameter and the optional fourth parameter fmode correspond exactly to the parameters of open() / open64().

When the value AT_FDCWD is transferred to the openat() / openat64() function for the fd parameter, the current directory is used.  

Return val.

Non-negative integer

indicating the the lowest numbered unused file descriptor, if successful.

 

-1

if an error occurs. No file is created or updated. errno is set to indicate the
error.

Errors

open(), open64(), openat() and openat64() fail if: 

 

EACCES

Search permission is denied on a component of the path.

The file does not exist, and the access permissions specified by oflag are denied.

The file does not exist, and write permission is denied by the parent directory of the file to be created.

O_TRUNC is set, and write permission is denied for the file.

 

Extension

 

EAGAIN

The file exists, mandatory file/record locking is set, and there are outstanding record locks on the file (see chmod()).

 

EEXIST

O_CREAT and O_EXCL are set, and the named file exists.

 

EFAULT

path points beyond the assigned address space of the process.

 

EINTR

A signal was caught during the open() system call.

 

EINVAL

The value of the oflag argument is invalid.

 

EIO

A connection was cleared or an error occurred while opening a stream-oriented device.

EISDIR

The named file is a directory and oflag includes O_WRONLY or O_RDWR.

EMFILE

{OPEN_MAX} file descriptors are currently open in the calling process.

EMULTIHOP

Components of path require hops to several remote computers, but the file system does not permit this.

ENAMETOOLONG

The length of the path argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.

ENFILE

The maximum allowable number of files is currently open in the system.

ENOENT

O_CREAT is not set and the named file does not exist, or

O_CREAT is set and either the path prefix does not exist or path points to an empty string.

ENOLINK

path refers to a remote computer to which there is no active connection.

ENOSPC

The file does not exist, and O_CREAT is specified or the directory or file system that would contain the new file cannot be expanded.

ENOSR

A stream cannot be assigned.

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, or
O_NONBLOCK is set, the named file is a FIFO, O_WRONLY is set and no process has the file open for reading.

EROFS

The named file resides on a read-only file system and either O_WRONLY,  O_RDWR, O_CREAT (if file does not exist) or O_TRUNC is set in the oflag argument.

EOVERFLOW

O_LARGEFILE is not set for a file and the size of the file cannot be represented correctly in an object of type off_t.

In addition, openat() and openat64() fail when the following applies:

EACCES

The fd parameter was not opened with O_SEARCH, and the authorizations applicable for the directory do not permit the directory to be searched.

EBADF

The path parameter does not specify an absolute pathname, and the fd parameter does not have the value AT_FDCWD, nor does it contain a valid file descriptor opened for reading or searching.

ENOTDIR

The path parameter does not specify an absolute pathname, and the file descriptor fd is not connected with a directory.

EINVAL

The implementation does not support O_SEARCH for the POSIX file system  bs2fs.

Notes

The program environment determines whether open() is executed for a BS2000 or POSIX file.

BS2000
The BS2000 file name or link name can be written in both uppercase and lowercase. It is automatically converted to uppercase.

Non-existent files are created by default with the following attributes: for KR functionality (only available with C/C++ versions lower than V3), as a SAM file with variable record length and standard block length; for ANSI functionality, as an ISAM file with variable record length and standard block length. SAM files are always opened as text files by open().

If a link name is used, the following file attributes may be changed with the SET-FILE-LINK command: the access method, record length, record format, block length and block format. When the old contents of an existing file are deleted (0003, 01001), the catalog attributes of the file are preserved.

Location of the file position indicator in append mode:

If the file-position indicator of a file opened in append mode (0401, 0402) has been explicitly moved from the end of the file (lseek()), it is handled differently for KR and ANSI functionality as described below. KR functionality (only available with C/C++ versions lower than V3): the current file-position indicator is ignored only when writing with the elementary function write(), and the file is automatically positioned to end of the file. ANSI functionality: the current file-position indicator is ignored for all write functions, and the file is automatically positioned to end of the file.

An attempt to open a non-existent file in the read (0000, 0002), update (0001), or append (0401, 0402) mode will result in an error. A file may be opened for different access modes simultaneously, provided these modes are mutually compatible within the BS2000 data management system. (INCORE) files can only be opened for writing (01001) or for writing and reading (0003). Data must first be written. To read in the written data again, the file must be positioned to beginning of file with the lseek() function.

When a program starts, the standard files for input, output, and error output are automatically opened with the following file descriptors:

stdin:	0
stdout:	1
stderr:	2

(End)

A maximum of _NFILE files may be open simultaneously. _NFILE is defined as 2048 in stdio.h.

See also

chmod(), close(), creat(), creat64(), dup(), fcntl(), fdopen(), lseek(), lseek64(), read(), umask(), write(), fcntl.h, sys/types.h, sys/stat.h.