fchownat()
Change the user ID and group ID of a file at a given location
Synopsis:
#include <unistd.h>
int fchownat( int fd,
const char* const path,
const uid_t uid,
const gid_t gid,
const int flags );
Arguments:
- fd
- A file descriptor that indicates the base directory for relative filepaths.
The pathname given in path is resolved by appending it to the directory associated with fd.
You can set this argument to AT_FDCWD to use the current working directory as the base directory.
Note:The QNX OS implementation of the *at() functions differ from the POSIX standards. You must use a file descriptor obtained from an open() or openat() call with the O_DIRECTORY flag set, rather than the O_SEARCH flag on POSIX. Otherwise, the function fails and sets errno to ENOTDIR.
If path specifies an absolute path, fd has no effect.
- path
- The pathname of the file whose ownership you want to change. This can be absolute or relative; for details of how relative pathname resolution is done, see above.
- uid
- The new user ID for the file.
- gid
- The new group ID for the file.
- flags
- A bitfield of the following flags:
- AT_SYMLINK_NOFOLLOW — if path names a symbolic link, change the ownership of the symbolic link instead of the ownership of the file.
Library:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
Description:
The fchownat() function changes the user ID and group ID of the file specified by path to be the numeric values given in uid and gid. The path argument can contain an absolute or relative path. In the latter case, the fd argument is used to resolve the pathname, as explained in this argument's description (above).
The function checks if directory searches are permitted using the current permissions of the directory underlying the file descriptor.
When the flags field is 0, this function is equivalent to chown() when fd is AT_FDCWD. For details about other possible flags settings, see this argument's description (above).
QNX OS has no concept of a path operation (open(), readlink(), etc.) that references a path relative to an already open file descriptor (for a directory), as far as the filesystem resource manager is concerned. Therefore, it's not possible to eliminate the race inherent in looking up a pathname with multiple intervening directories or symbolic links. However, fchownat() can still be used for maintaining a per-thread current working directory, using file descriptors maintained by the application.
Only processes with an effective user ID equal to the file's user ID or with the IOFUNC_ABILITYID_CHOWN ability (see iofunc_ability_check()) may change the ownership of a file.
- Only a process with the IOFUNC_ABILITYID_CHOWN ability may change the ownership of a file.
- Changing the group ID is permitted to a process with an effective user ID equal to the file's user ID but without the IOFUNC_ABILITYID_CHOWN ability, if and only if uid is equal to the file's user ID or -1, and gid is equal either to the calling process's effective group ID or to one of its supplementary group IDs.
Returns:
- 0
- Success.
- -1
- An error occurred (errno is set).
Errors:
- EACCES
- Search permission is denied on a component of the path prefix, or you don't have permission to search the directory underlying fd.
- EBADF
- The path argument does not specify an absolute path and the fd argument is neither AT_FDCWD nor a valid file descriptor open for reading.
- EIO
- An I/O error occurred while reading from or writing to the filesystem.
- EINTR
- A signal interrupted the operation.
- EINVAL
- The given owner (uid) or group (gid) isn't supported, or an invalid value was specified for flags.
- ELOOP
- During resolution of the path argument, a loop was found in the symbolic links or more than SYMLOOP_MAX symbolic links were encountered.
- ENAMETOOLONG
- The length of the entire pathname exceeds PATH_MAX, or the path component generated from a symbolic link resolution has a length exceeding PATH_MAX.
- ENOENT
- A component of the specified path doesn't name an existing file, or path is an empty string.
- ENOTDIR
- One of the following conditions is true:
- A component of the path prefix names an existing file that is neither a directory nor a symbolic link to one.
- The path argument contains at least one non-slash character, ends with at least one slash character (/), and the last component names an existing file that is neither a directory nor a symbolic link to one.
- The path argument is not an absolute path and dirfd is associated with a non-directory file.
- The file descriptor in fd was created without O_DIRECTORY set.
- EPERM
- The effective user ID doesn't match the file's owner, or the process doesn't have appropriate privileges.
- EROFS
- The named file resides on a read-only filesystem.
Classification:
| Safety: | |
|---|---|
| Cancellation point | No |
| Signal handler | Yes |
| Thread | Yes |