gtpc2m57C/C++ Language Support User's Guide

open-Open a File

This function opens a file and returns an integer called a file descriptor.

You can use this file descriptor to refer to the file in subsequent input/output (I/O) operations; for example, in read or write functions. Each file opened by a process gets the lowest file descriptor not currently open for the process.

Format

#include <fcntl.h>
int open(const char *pathname, int options, ...);

pathname
The pathname argument is a string giving the name of the file you want to open.

options
The integer options specifies options for the open operation by taking the bitwise inclusive OR of symbols defined in the fcntl.h header file. The options indicate whether the file should be accessed for reading, writing, reading and writing, and so on. Most open operations position a file offset (an indicator showing where the next read or write will take place in the file) at the beginning of the file; however, there are options that can change this position.

One of the following open options must be specified in the options argument.

O_RDONLY
Open for reading only.

O_WRONLY
Open for writing only.

O_RDWR
Open for both reading and writing.

One of the following can also be specified in the options parameter:

O_APPEND
Positions the file offset at the end of the file before each write operation.

O_CREAT
Indicates that the call to open has a mode argument.

If the file being opened already exists, O_CREAT has no effect except when O_EXCL is also specified; see the O_EXCL option, which follows.

The user ID of the file is set to the user ID of the process. If the parent directory of the file has its mode bit S_OSGID set OFF, the group ID of the file is set to the group ID of the process; otherwise, the group ID of the file is set to the group ID of its parent directory.

If O_CREAT is specified and the file did not previously exist, a successful open sets the modification time for the file. It also updates the modification time field in the parent directory.

TPF deviation from POSIX

The TPF system does not support the atime (access time) or ctime (change time) time stamp.

O_EXCL
If both O_EXCL and O_CREAT are specified, open fails if the file already exists. If both O_EXCL and O_CREAT are specified and pathname names a symbolic link, open fails regardless of the contents of the symbolic link.

O_NONBLOCK
When you are opening a character special file that supports a nonblocking open, O_NONBLOCK controls whether subsequent reads and writes can block.

When you are opening a FIFO special file for reading only, if O_NONBLOCK is not set (which is the default), the open function blocks the calling process until a process opens the file for writing. If O_NONBLOCK is set the open function returns without delay.

When you are opening a FIFO special file for writing only, if O_NONBLOCK is not set (which is the default), the open function blocks the calling process until a process opens the file for reading. If O_NONBLOCK is set the open function returns an error if no process currently has the file open for reading.

O_TRUNC
Truncates the file to zero length under these conditions: (a) the file exists (b) the file is a regular file (c) the file is otherwise successfully opened with O_RDWR or O_WRONLY.
TPF deviation from POSIX

The TPF system does not support the ctime (change time) time stamp. The mtime (modification time) time stamp is updated only when a file that is opened with write access, or read and write access is closed.

If O_TRUNC is specified and the file previously existed, a successful open updates the modification time for the file.

....
An additional argument (...) is required if the O_CREAT option is specified in options. This argument may be called the mode and has the mode_t type. It specifies file permission bits to be used when a file is created. All the file permission bits are set to the bits of mode except for those set in the file-mode creation mask of the process. The following is a list of symbols that can be used for a mode.

S_ISUID
Privilege to set the user ID (UID) to run. When this file is run through the tpf_fork function, the effective user ID of the process is set to the owner of the file. The process then has the same authority as the file owner rather than the authority of the actual caller.

S_ISGID
Privilege to set the group ID (GID) to run. When this file is run through the tpf_fork function, the effective group ID of the process is set to the group of the file. The process then has the same authority as the file group rather than the authority of the actual caller.

S_IRUSR
Read permission for the file owner.

S_IWUSR
Write permission for the file owner.

S_IXUSR
Search permission (for a directory) for the file owner.

S_IRWXU
Read, write, and search for the file owner; S_IRWXU is the bitwise inclusive OR of S_IRUSR, S_IWUSR, and S_IXUSR.

S_IRGRP
Read permission for the file group.

S_IWGRP
Write permission for the file group.

S_IXGRP
Search permission (for a directory) for the file group.

S_IRWXG
Read, write, and search permission for the file group. S_IRWXG is the bitwise inclusive OR of S_IRGRP, S_IWGRP, and S_IXGRP.

S_IROTH
Read permission for users other than the file owner.

S_IWOTH
Write permission for users other than the file owner.

S_IXOTH
Search permission for a directory for users other than the file owner.

S_IRWXO
Read, write, and search permission for users other than the file owner. S_IRWXO is the bitwise inclusive OR of S_IROTH, S_IWOTH, and S_IXOTH.

Normal Return

If successful, open returns a file descriptor greater than or equal to zero.

Error Return

If unsuccessful, open returns a -1 value and sets errno to one of the following:

EACCES
Access is denied. Possible reasons include:

EEXIST
O_CREAT and O_EXCL were specified and either the named file refers to a symbolic link or the named file already exists.

EINVAL
The options parameter does not specify a valid combination of the O_RDONLY, O_WRONLY, and O_TRUNC bits.

EISDIR
pathname is a directory.

ELOOP
A loop exists in symbolic links. This error is issued if the number of symbolic links found while resolving the pathname argument is greater than POSIX_SYMLOOP.

EMFILE
The process has reached the maximum number of file descriptors it can have open.

ENAMETOOLONG
pathname is longer than PATH_MAX characters, or some component of pathname is longer than NAME_MAX characters. For symbolic links, the length of the path name string substituted for a symbolic link exceeds PATH_MAX.

ENFILE
The system has reached the maximum number of file descriptors that it can have open.

ENOENT
Typical causes:

ENOSPC
The directory or file system intended to hold a new file does not have enough space.

ENOTDIR
A component of pathname is not a directory.

ETPFNPIPWSYS
In a loosely coupled environment, there was an attempt to access a FIFO special file (or named pipe) from a processor other than the processor on which the file was created.

Programming Considerations

 The TPF system does not support creating, updating, or deleting files in 1052 or UTIL state. Special files may or may not be writable in 1052 or UTIL state depending on the device driver implementation. 

 When a new regular file is created, if the TPF_REGFILE_RECORD_ID environment variable is set to a 2-character string, its value is used as the record ID for all pool file records that are allocated to store the contents of the file. 

Examples

The following example opens an output file for appending.

int fd;
fd = open("outfile",O_WRONLY | O_APPEND);

The following statement creates a new file with read, write, and execute permissions for the creating user. If the file already exists, open fails.

fd = open("newfile",O_WRONLY|O_CREAT|O_EXCL,S_IRWXU);

Related Information

See Appendix E, Programming Support for the TPF File System for more information about TPF File System C Functions.