opendir()--Open Directory
Syntax
#include <sys/types.h> #include <dirent.h> DIR *opendir(const char *dirname);Service Program Name: QP0LLIB1
Default Public Authority: *USE
Threadsafe: Conditional; see Usage Notes.
The opendir() function opens a directory so that it can be read with the readdir() function. The variable dirname is a string giving the name of the directory to open. If the last component of dirname is a symbolic link, opendir() follows the symbolic link. As a result, the directory that the symbolic link refers to is opened. The functions readdir(), rewinddir(), and closedir() can be called after a successful call to opendir(). The first readdir() call reads the first entry in the directory.
Names returned on calls to readdir() are returned in the CCSID (coded character set identifier) in effect for the current job at the time this opendir() function is called. If the CCSID of the job is 65535, the default CCSID of the job is used. See QlgOpendir()--Open Directory for specifying a different CCSID.
Parameters
- dirname
- (Input) A pointer to the null-terminated path name of the directory to be
opened.
This parameter is assumed to be represented in the CCSID currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.
See QlgOpendir()--Open Directory for a description and an example of supplying the dirname in any CCSID.
Authorities
Note: Adopted authority is not used.
Authorization required for opendir()
Object Referred to | Authority Required | errno |
---|---|---|
Each directory in the path name preceding the directory to be opened | *X | EACCES |
The directory to be opened | *R | EACCES |
Return Value
- value
- opendir() was successful. The value returned is a pointer to a DIR, representing an open directory stream. This DIR describes the directory and is used in subsequent operations on the directory using the readdir(), rewinddir(), and closedir() functions.
- NULL pointer
- opendir() was not successful. The errno global variable is set to indicate the error.
Error Conditions
If opendir() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.
Error condition | Additional information |
---|---|
[EACCES] |
If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems. |
[EAGAIN] | |
[EBADFID] | |
[EBADNAME] | |
[EBUSY] | |
[ECONVERT] | |
[EDAMAGE] | |
[EEXIST] | |
[EFAULT] | |
[EFILECVT] | |
[EINTR] | |
[EINVAL] | |
[EIO] | |
[EJRNDAMAGE] | |
[EJRNENTTOOLONG] | |
[EJRNINACTIVE] | |
[EJRNRCVSPC] | |
[ELOOP] | |
[EMFILE] | |
[ENAMETOOLONG] | |
[ENEWJRN] | |
[ENEWJRNRCV] | |
[ENFILE] | |
[ENOENT] | |
[ENOMEM] | |
[ENOSPC] | |
[ENOTAVAIL] | |
[ENOTDIR] | |
[ENOTSAFE] | |
[ENOTSUP] | |
[EROOBJ] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[EUNKNOWN] |
If interaction with a file server is required to access the object, errno could indicate one of the following errors:
Error condition | Additional information |
---|---|
[EADDRNOTAVAIL] | |
[ECONNABORTED] | |
[ECONNREFUSED] | |
[ECONNRESET] | |
[EHOSTDOWN] | |
[EHOSTUNREACH] | |
[ENETDOWN] | |
[ENETRESET] | |
[ENETUNREACH] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[ETIMEDOUT] | |
[EUNATCH] |
Error Messages
The following messages may be sent from this function:
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPFA0D4 E | File system error occurred. Error number &1. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
Usage Notes
- This function will fail with error code [ENOTSAFE] when all the following
conditions are true:
- Where multiple threads exist in the job.
- The object on which this function is operating resides in a file system
that is not threadsafe. Only the following file systems are threadsafe for this
function:
- "Root" (/)
- QOpenSys
- User-defined
- QNTC
- QSYS.LIB
- Independent ASP QSYS.LIB
- QOPT
- Network File System
- QFileSvr.400
- Where multiple threads exist in the job.
- The opendir() function uses a file descriptor for each
open directory. Applications are limited to opening no more than OPEN_MAX files
and directories, and are subject to receiving the [EMFILE] and [ENFILE] errors
when too many file descriptors are in use. See the sysconf()
function for a description of OPEN_MAX.
The file descriptor that is used by opendir() will not be inherited in a child process that is created by the spawn() or spawnp() API.
opendir() may allocate memory from the user's heap.
Files that are added to the directory after the first call to readdir() following an opendir() or rewinddir() may not be returned on calls to readdir(), and files that are removed may still be returned on calls to readdir().
- QDLS File System Differences
QDLS updates the access time on opendir().
- QOPT File System Differences
If the directory exists on a volume formatted in Universal Disk Format (UDF), the authorization that is checked for the directory and preceding directories in the path name follows the rules described in Authorization required for opendir(). If the directory exists on a volume formatted in some other media format, no authorization checks are made on the directory being opened and each directory in the path name. The volume authorization list is checked for *USE authority regardless of the volume media format.
Related Information
- The <sys/types.h> file (see Header Files for UNIX®-Type Functions)
- The <dirent.h> file (see Header Files for UNIX-Type Functions)
- closedir()--Close Directory
- QlgOpendir()--Open Directory
- readdir()--Read Directory Entry
- readdir_r()--Read Directory Entry
- readdir_r_ts64()--Read Directory Entry
- rewinddir()--Reset Directory Stream to Beginning
- spawn()--Spawn Process
- spawnp()--Spawn Process with Path
- sysconf()--Get system configuration variables
Example
The following example opens a directory.
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#include <sys/types.h> #include <dirent.h> #include <sys/stat.h> #include <sys/types.h> #include <errno.h> #include <stdio.h> void traverse(char *fn, int indent) { DIR *dir; struct dirent *entry; int count; char path[1025]; /*** EXTRA STORAGE MAY BE NEEDED ***/ struct stat info; for (count=0; count<indent; count++) printf(" "); printf("%s\n", fn); if ((dir = opendir(fn)) == NULL) perror("opendir() error"); else { while ((entry = readdir(dir)) != NULL) { if (entry->d_name[0] != '.') { strcpy(path, fn); strcat(path, "/"); strcat(path, entry->d_name); if (stat(path, &info) != 0) fprintf(stderr, "stat() error on %s: %s\n", path, strerror(errno)); else if (S_ISDIR(info.st_mode)) traverse(path, indent+1); } } closedir(dir); } } main() { puts("Directory structure:"); traverse("/etc", 0); }
Output:
Directory structure: /etc /etc/samples /etc/samples/IBM /etc/IBM
API introduced: V3R1