diff options
Diffstat (limited to 'man-pages-posix-2013/man3p/chown.3p')
| -rw-r--r-- | man-pages-posix-2013/man3p/chown.3p | 323 |
1 files changed, 323 insertions, 0 deletions
diff --git a/man-pages-posix-2013/man3p/chown.3p b/man-pages-posix-2013/man3p/chown.3p new file mode 100644 index 0000000..5dc8ed6 --- /dev/null +++ b/man-pages-posix-2013/man3p/chown.3p @@ -0,0 +1,323 @@ +'\" et +.TH CHOWN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +chown, fchownat +\(em change owner and group of a file relative to directory +file descriptor +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> +.P +int chown(const char *\fIpath\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP); +int fchownat(int \fIfd\fP, const char *\fIpath\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP, + int \fIflag\fP); +.fi +.SH DESCRIPTION +The +\fIchown\fR() +function shall change the user and group ownership of a file. +.P +The +.IR path +argument points to a pathname naming a file. The user ID and group ID +of the named file shall be set to the numeric values contained in +.IR owner +and +.IR group , +respectively. +.P +Only processes with an effective user ID equal to the user ID of the +file or with appropriate privileges may change the ownership of a +file. If _POSIX_CHOWN_RESTRICTED is in effect for +.IR path : +.IP " *" 4 +Changing the user ID is restricted to processes with appropriate +privileges. +.IP " *" 4 +Changing the group ID is permitted to a process with an effective user +ID equal to the user ID of the file, but without appropriate +privileges, if and only if +.IR owner +is equal to the file's user ID or (\c +.BR uid_t )\(mi1 +and +.IR group +is equal either to the calling process' effective group ID or to one of +its supplementary group IDs. +.P +If the specified file is a regular file, one or more of the S_IXUSR, +S_IXGRP, or S_IXOTH bits of the file mode are set, and the process does +not have appropriate privileges, the set-user-ID (S_ISUID) and +set-group-ID (S_ISGID) bits of the file mode shall be cleared upon +successful return from +\fIchown\fR(). +If the specified file is a regular file, one or more of the S_IXUSR, +S_IXGRP, or S_IXOTH bits of the file mode are set, and the process has +appropriate privileges, it is implementation-defined whether the +set-user-ID and set-group-ID bits are altered. If the +\fIchown\fR() +function is successfully invoked on a file that is not a regular file +and one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of the file +mode are set, the set-user-ID and set-group-ID bits may be cleared. +.P +If +.IR owner +or +.IR group +is specified as (\c +.BR uid_t )\(mi1 +or (\c +.BR gid_t )\(mi1, +respectively, the corresponding ID of the file shall not be changed. +If both owner and group are \(mi1, the times need not be updated. +.P +Upon successful completion, +\fIchown\fR() +shall mark for update the last file status change timestamp of the file. +.P +The +\fIfchownat\fR() +function shall be equivalent to the +\fIchown\fR() +and +\fIlchown\fR() +functions except in the case where +.IR path +specifies a relative path. In this case the file to be changed is +determined relative to the directory associated with the file +descriptor +.IR fd +instead of the current working directory. If the file descriptor was +opened without O_SEARCH, the function shall check whether directory +searches are permitted using the current permissions of the directory +underlying the file descriptor. If the file descriptor was opened with +O_SEARCH, the function shall not perform the check. +.P +Values for +.IR flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR <fcntl.h> : +.IP AT_SYMLINK_NOFOLLOW 6 +.br +If +.IR path +names a symbolic link, ownership of the symbolic link is changed. +.P +If +\fIfchownat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fIchown\fR() +or +\fIlchown\fR() +respectively, depending on whether or not the AT_SYMLINK_NOFOLLOW bit +is set in the +.IR flag +argument. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \(mi1 and set +.IR errno +to indicate the error. If \(mi1 is returned, no changes are +made in the user ID and group ID of the file. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c +<slash> +character and ends with one or more trailing +<slash> +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EPERM +The effective user ID does not match the owner of the file, or the +calling process does not have appropriate privileges and +_POSIX_CHOWN_RESTRICTED indicates that such privilege is required. +.TP +.BR EROFS +The named file resides on a read-only file system. +.P +The +\fIfchownat\fR() +function shall fail if: +.TP +.BR EACCES +.IR fd +was not opened with O_SEARCH and the permissions of the directory +underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR EIO +An I/O error occurred while reading or writing to the file system. +.TP +.BR EINTR +The +\fIchown\fR() +function was interrupted by a signal which was caught. +.TP +.BR EINVAL +The owner or group ID supplied is not a value supported by the +implementation. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.br +.P +The +\fIfchownat\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR flag +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Although +\fIchown\fR() +can be used on some implementations by the file owner to change the owner +and group to any desired values, the only portable use of this function +is to change the group of a file to the effective GID of the calling +process or to a member of its group set. +.SH RATIONALE +System III and System V allow a user to give away files; +that is, the owner of a file may change its user ID to anything. This +is a serious problem for implementations that are intended to meet +government security regulations. +Version 7 and 4.3 BSD permit only the superuser +to change the user ID of a file. Some government agencies (usually not +ones concerned directly with security) find this limitation too +confining. This volume of POSIX.1\(hy2008 uses \fImay\fP to permit secure implementations +while not disallowing System V. +.P +System III and System V allow the owner of a file to change the +group ID to anything. Version 7 permits only the superuser to change +the group ID of a file. +4.3 BSD permits the owner to change the group ID of a file +to its effective group ID +or to any of the groups in the list of supplementary group IDs, but to +no others. +.P +The POSIX.1\(hy1990 standard requires that the +\fIchown\fR() +function invoked by a non-appropriate privileged process clear the +S_ISGID and the S_ISUID bits for regular files, and permits them to be +cleared for other types of files. This is so that changes in +accessibility do not accidentally cause files to become security holes. +Unfortunately, requiring these bits to be cleared on non-executable +data files also clears the mandatory file locking bit (shared with +S_ISGID), which is an extension on many implementations (it first +appeared in System V). These bits should only be required to be +cleared on regular files that have one or more of their execute bits +set. +.P +The purpose of the +\fIfchownat\fR() +function is to enable changing ownership 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 +\fIchown\fR() +or +\fIlchown\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIfchownat\fR() +function it can be guaranteed that the changed file is located relative +to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIfpathconf\fR\^(\|)", +.IR "\fIlchown\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB<fcntl.h>\fP", +.IR "\fB<sys_types.h>\fP", +.IR "\fB<unistd.h>\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.unix.org/online.html . + +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |