__open_stat() — Open a file and get file status information
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.