Subject: faccessat(2) - determine accessibility of a file using file descriptors [PSARC/2009/284 Self Review] To: PSARC-ext@Sun.Com Cc: Sumanth.Naropanth@Sun.COM Bcc: one-pager-list@sac.sfbay one-pager-log@sac.sfbay sac-bar@sac.sfbay Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI This information is Copyright 2009 Sun Microsystems 1. Introduction 1.1. Project/Component Working Name: faccessat(2) - determine accessibility of a file using file descriptors 1.2. Name of Document Author/Supplier: Author: Sumanth Naropanth 1.3 Date of This Document: 06 May, 2009 4. Technical Description faccessat(2) - determine accessibility of a file using file descriptors AUTHOR: Sumanth Naropanth SUMMARY: Promotion of the private __accessat() function in OpenSolaris to public visibility as faccessat(2) PROBLEM: RFE 6478917 introduced a new extended attribute system interface: int __accessat(int fd, const char *path, int amode); This function is equivalent to the access(2) system call, except in the case where the "path" variable specifies a relative path. In this case the file whose accessibility is to be determined shall be located relative to the directory associated with the file descriptor "fd" instead of the current working directory. If "__accessat()" is passed the special value AT_FDCWD in the "fd" parameter, the current working directory is used and the behavior shall be identical to a call to access(). This function was kept private at the time of writing since there had been discussions among the standards body on the name for this function. Recent publications of the Open Group Technical Standards, including [IEEE P1003.1 Draft 5.1, 15 May 2008] has confirmed that this interface shall be named 'faccessat' and shall have the following prototype: int faccessat(int fd, const char *path, int amode, int flag); The 'accessat' function in OpenSolaris is rewritten to conform to the new specifications and is renamed as 'faccessat'. The function should promoted to be a public interface, with an updated access(2) man page. PROPOSED SOLUTION: Promoting the '__accessat()' interface to public status and modifying the function to include the 'int flag' variable. ISSUES: NONE BINDING: This case seeks a Minor Release binding. COMMITMENT LEVEL: ------------------------------------------------------- | Interface | Commitment Level | ------------------------------------------------------- | faccessat() | Committed | ------------------------------------------------------- REFERENCE DOCUMENTS: See the updated man page for access(2) below. ------------------------------------------------------------------------------ System Calls access(2) NAME access, faccessat - determine accessibility of a file SYNOPSIS #include #include int access(const char *path, int amode); int faccessat(int fd, const char *path, int amode, int flag); DESCRIPTION The access() function checks the file named by the pathname pointed to by the _path_ argument for accessibility according to the bit pattern contained in _amode_, using the real user ID in place of the effective user ID and the real group ID in place of the effective group ID. This allows a setuid process to verify that the user running it would have had permission to access this file. The value of _amode_ is either the bitwise inclusive OR of the access permissions to be checked (R_OK, W_OK, X_OK) or the existence test, F_OK. These constants are defined in as follows: R_OK Test for read permission. W_OK Test for write permission. X_OK Test for execute or search permission. F_OK Check existence of file See Intro(2) for additional information about "File Access Permission". If any access permissions are to be checked, each will be checked individually, as described in Intro(2). If the pro- cess has appropriate privileges, an implementation may indi- cate success for X_OK even if none of the execute file per- mission bits are set. The faccessat() function is equivalent to the access() function, except in the case where _path_ specifies a relative path. In this case the file whose accessibility is to be determined should be located relative to the directory associated with the file descriptor _fd_ instead of the current working directory. If faccessat() is passed the special value AT_FDCWD in the _fd_ parameter, the current working directory is used and the behavior is identical to a call to access(). Values for _flag_ are constructed by a bitwise-inclusive OR of flags from the following list, defined in : AT_EACCESS The checks for accessibility are performed using the effective user and group IDs instead of the real user and group ID as required in a call to access(). RETURN VALUES If the requested access is permitted, access() and faccessat() succeed and return 0. Otherwise, -1 is returned and errno is set to indicate the error. ERRORS These functions will fail if: EACCES Permission bits of the file mode do not per- mit the requested access, or search permis- sion is denied on a component of the path prefix. EFAULT _path_ points to an illegal address. EINTR A signal was caught during the access() function. ELOOP Too many symbolic links were encountered in resolving _path_. ELOOP A loop exists in symbolic links encountered during resolution of the _path_ argument. ENAMETOOLONG The length of the _path_ argument exceeds {PATH_MAX}, or a pathname component is longer than {NAME_MAX} while _POSIX_NO_TRUNC is in effect. ENOENT A component of _path_ does not name an exist- ing file or _path_ is an empty string. ENOLINK _path_ points to a remote machine and the link to that machine is no longer active. ENOTDIR A component of the path prefix is not a directory. ENXIO The _path_ argument points to a character or block device special file and the corresponding device has been retired by the fault management framework. EROFS Write access is requested for a file on a read-only file system. The faccessat() function will fail if 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 or searching. These functions function may fail if: EINVAL The value of the _amode_ argument is invalid. ENAMETOOLONG Pathname resolution of a symbolic link pro- duced an intermediate result whose length exceeds {PATH_MAX}. ETXTBSY Write access is requested for a pure pro- cedure (shared text) file that is being exe- cuted. The faccessat() function may fail if: EINVAL The value of the flag argument is not valid. ENOTDIR The _path_ argument is not an absolute path and _fd_ is neither AT_FDCWD nor a file descriptor associated with a directory. USAGE Additional values of _amode_ other than the set defined in the description might be valid, for example, if a system has extended access controls. The purpose of the faccessat() function is to enable the checking of the accessibility of files in directories other than the current working directory without exposure to race conditions. Any part of the path of a file could be changed in parallel to a call to access(), resulting in unspecified behavior. By opening a file descriptor for the target directory and using the faccessat() function it can be guaranteed that the file tested for accessibility is located relative to the desired directory. ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Interface Stability | Committed | |_____________________________|_____________________________| | MT-Level | Async-Signal-Safe | |_____________________________|_____________________________| | Standard | See standards(5). | |_____________________________|_____________________________| SEE ALSO Intro(2), chmod(2), stat(2), attributes(5), standards(5), fsattr(5), fstatat(2) 6. Resources and Schedule 6.4. Steering Committee requested information 6.4.1. Consolidation C-team Name: ON 6.5. ARC review type: Automatic 6.6. ARC Exposure: open