Standards
Standards / Extensions |
C or C++ |
Dependencies |
z/OS® UNIX |
both |
OS/390 V2R6 |
Format
#define _POSIX_SOURCE
#include <fcntl.h>
#include <sys/stat.h>
int __open_stat(const char *pathname, int options, mode_t mode,
struct stat *info);
General description
Opens a file and returns a number called a file descriptor.
__open_stat() also returns information about the opened file. __open_stat()
is a combination of open() and fstat().
The parameters are:
- Parameters
- Description
- pathname
- This parameter is a NULL-terminated character string containing
the hierarchical file system (HFS) pathname of the file to be opened.
pathname can
begin with or without a slash.
- A pathname beginning with a slash is an absolute pathname. The
slash refers to the root directory, and the search for the file starts
at the root directory.
- A pathname not beginning with a slash is a relative pathname.
The search for the file begins at the working directory.
See open() — Open a file for more information about the pathname parameter
and the types of files that can be opened.
- options
- An integer containing option bits for the open operation. These
options are the same as those in the options parameter passed
to open(). These bits are defined in fcntl.h. For a list
of these option bits and their meaning, see open() — Open a file.
- mode
- mode is the same as the optional third parameter for
open(), which is used when a new file is being created. For __open_stat(),
the mode parameter is always required. If a new file is
not being created, mode is ignored, and may be set to 0.
When __open_stat() creates a file, the flag bits in mode specify
the file permissions and other characteristics for the new file. The
flag bits in mode are defined in sys/modes.h.
For more information about the mode parameter, see open() — Open a file.
- info
- The info parameter points to an area of memory where
the system will store information about the file that is opened. This
parameter is the same as the info parameter in fstat() or
stat(). If the file is successfully opened, the system returns file
status information in a stat structure, as defined in sys/stat.h.
The elements of this structure are described in stat() — Get file information.
Returned value
If successful, __open_stat() returns a file descriptor.
If unsuccessful, __open_stat() returns -1 and sets errno
to one of the following values:
- Error Code
- Description
- EACCESS
- Access to the file was denied. One of the following errors
occurred:
- The calling process does not have permission to search one of
the directories specified in the pathname parameter.
- The calling process does not have permission to open the file
in the way specified by the options parameter.
- The file does not exist, and the calling process does not have
permission to write into files in the directory the file would have
been created in.
- The truncate option was specified, but the process does not have
write permission for the file.
- EAGAIN
- Resources were temporarily unavailable.
- EBUSY
- pathname specifies a master pseudoterminal that is
either already in use or for which the corresponding slave is open.
- EEXIST
- The exclusive create option was specified, but the file already
exists.
Use __errno2() to determine the exact reason the error
occurred.
- EFBIG
- A request to create a new file is prohibited because the file
size limit for the process is set to 0.
- EINTR
- The __open_stat() operation was interrupted by a signal.
- EINVAL
- The options parameter does not specify a valid combination
of the O_RDONLY, O_WRONLY and O_TRUNC bits,
or the file type specified in the mode parameter is not valid.
Use
__errno2() to determine the exact reason the error occurred.
- EISDIR
- The file specified by pathname is a directory and the options parameter
specifies write or read/write access.
Use __errno2() to determine
the exact reason the error occurred.
- ELOOP
- A loop exists in symbolic links encountered during resolution
of the pathname parameter. This error is issued if more
than 8 symbolic links are detected in the resolution of pathname.
- EMFILE
- The process has reached the maximum number of file descriptors
it can have open.
- ENAMETOOLONG
- pathname is longer than 1023 characters, or a component
of pathname is longer than 255 characters. (The system does
not support filename truncation.)
- ENODEV
- Typical causes of this error are:
- An attempt was made to open a character special file for a device
not supported by the system.
- An attempt was made to open a character special file for a device
that is not yet initialized.
Use __errno2() to determine the exact reason the error occurred.
- ENOENT
- Typical causes of this error are:
- The request did not specify that the file was to be created, but
the file named by pathname was not found.
- The request asked for the file to be created, but some component
of pathname was not found, or the pathname parameter
was blank.
Use __errno2() to determine the exact reason the error occurred.
- ENOSPC
- The directory or file system intended to hold a new file has
insufficient space.
- ENOTDIR
- A component of pathname is not a directory.
- ENXIO
- The __open_stat() request specified write-only and nonblock
for a FIFO special file, but no process has the file open for reading.
For pseudoterminals, this errno can mean that the minor number associated
with pathname is too big.
- EPERM
- The caller is not permitted to open the specified slave pseudoterminal
or the corresponding master is not yet open. EPERM is
also returned if the slave is closed with HUPCL set and
an attempt is made to reopen it.
- EROFS
- The pathname parameter names a file on a read-only
file system, but options that would allow the file to be altered were
specified: write-only, read/write, truncate, or -- for a new file
-- create.
Use __errno2() to determine the exact reason the error
occurred.