gtpc2m57 | C/C++ Language Support User's Guide |
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:
- The process does not have search permission on a component in
pathname.
- The file exists, but the process does not have permission to open the file
in the way specified by the flags.
- The file does not exist and the process does not have write permission on
the directory where the file is to be created.
- O_TRUNC was specified, but the process does not have write permission on
the file.
- 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:
- O_CREAT is not specified and the named file does not exist.
- O_CREAT is specified and either the prefix of pathname does not
exist or the pathname argument is an empty string.
- 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.