fchdir()--Change Current Directory by Descriptor
Syntax
#include <unistd.h> int fchdir(int fildes);Service Program Name: QP0LLIB1
Default Public Authority: *USE
Threadsafe: Conditional; see Usage Notes.
The fchdir() function makes the directory named by fildes the new current directory. If the fchdir() function fails, the current directory is unchanged.
Parameters
- fildes
- (Input) The file descriptor of the directory.
Authorities
Note: Adopted authority is not used.
Authorization Required for
fchdir()
Object Referred to | Authority Required | errno |
---|---|---|
The directory named by fildes. | *X | EACCES |
Return Value
- 0
- fchdir() was successful.
- -1
- fchdir() was not successful. The errno global variable is set to indicate the error.
Error Conditions
If fchdir() 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] | |
[EBADF] | |
[EBADFID] | |
[EBUSY] | |
[EDAMAGE] | |
[EINTR] | |
[EINVAL] | |
[EIO] | |
[ENOENT] | |
[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
The fchdir() API operates on two objects: the previous current working directory and the new one. If either of these objects is managed by a file system that is not threadsafe, fchdir() fails with the ENOTSAFE error code.
- Where multiple threads exist in the job.
- Network File System Differences
If the local storage of attributes and names is not suppressed (option noac when the file system is mounted), then one can potentially use the fchdir() API to change to a directory which has been removed. This depends on how often and when the local storage of attributes and names is refreshed.
Related Information
- The <unistd.h> file (see Header Files for UNIX®-Type Functions)
- The <limits.h> file (see Header Files for UNIX-Type Functions)
- chdir()--Change Current Directory
- getcwd()--Get Current Directory
- QlgChdir()--Change Current Directory
- QlgGetcwd()--Get Current Directory
Example
The following example uses fchdir().
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#include <stdio.h> #include <unistd.h> #include <fcntl.h> main() { char dir[]="tempfile"; int file_descriptor; int oflag1 = O_RDONLY | O_CCSID; mode_t mode = S_IRUSR | S_IWUSR | S_IXUSR; unsigned int open_ccsid = 37; if ((file_descriptor = open(dir,oflag1,mode,open_ccsid)) < 0) perror("open() error"); else { if (fchdir(file_descriptor) != 0) perror("fchdir() to tempfile failed"); close(file_descriptor); } }
Output:
fchdir() to tempfile failed: Not a directory.
API introduced: V5R2