diff options
Diffstat (limited to 'man3p/chmod.3p')
| -rw-r--r-- | man3p/chmod.3p | 216 |
1 files changed, 216 insertions, 0 deletions
diff --git a/man3p/chmod.3p b/man3p/chmod.3p new file mode 100644 index 000000000..58280d68f --- /dev/null +++ b/man3p/chmod.3p @@ -0,0 +1,216 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CHMOD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" chmod +.SH NAME +chmod \- change mode of a file +.SH SYNOPSIS +.LP +\fB#include <sys/stat.h> +.br +.sp +int chmod(const char *\fP\fIpath\fP\fB, mode_t\fP \fImode\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIchmod\fP() function shall change S_ISUID, S_ISGID, \ S_ISVTX, +and the file permission bits of the file named by the pathname pointed +to by the \fIpath\fP argument to the +corresponding bits in the \fImode\fP argument. The application shall +ensure that the effective user ID of the process matches the +owner of the file or the process has appropriate privileges in order +to do this. +.LP +S_ISUID, S_ISGID, \ S_ISVTX, and the file permission +bits are described in \fI<sys/stat.h>\fP. +.LP +If the calling process does not have appropriate privileges, and if +the group ID of the file does not match the effective group +ID or one of the supplementary group IDs and if the file is a regular +file, bit S_ISGID (set-group-ID on execution) in the file's +mode shall be cleared upon successful return from \fIchmod\fP(). +.LP +Additional implementation-defined restrictions may cause the S_ISUID +and S_ISGID bits in \fImode\fP to be ignored. +.LP +The effect on file descriptors for files open at the time of a call +to \fIchmod\fP() is implementation-defined. +.LP +Upon successful completion, \fIchmod\fP() shall mark for update the +\fIst_ctime\fP field of the file. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned; otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. If +-1 is returned, no change to the file mode occurs. +.SH ERRORS +.LP +The \fIchmod\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied on a component of the path prefix. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B EPERM +The effective user ID does not match the owner of the file and the +process does not have appropriate privileges. +.TP 7 +.B EROFS +The named file resides on a read-only file system. +.sp +.LP +The \fIchmod\fP() function may fail if: +.TP 7 +.B EINTR +A signal was caught during execution of the function. +.TP 7 +.B EINVAL +The value of the \fImode\fP argument is invalid. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +strings exceeded {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Setting Read Permissions for User, Group, and Others +.LP +The following example sets read permissions for the owner, group, +and others. +.sp +.RS +.nf + +\fB#include <sys/stat.h> +.sp + +const char *path; +\&... +chmod(path, S_IRUSR|S_IRGRP|S_IROTH); +\fP +.fi +.RE +.SS Setting Read, Write, and Execute Permissions for the Owner Only +.LP +The following example sets read, write, and execute permissions for +the owner, and no permissions for group and others. +.sp +.RS +.nf + +\fB#include <sys/stat.h> +.sp + +const char *path; +\&... +chmod(path, S_IRWXU); +\fP +.fi +.RE +.SS Setting Different Permissions for Owner, Group, and Other +.LP +The following example sets owner permissions for CHANGEFILE to read, +write, and execute, group permissions to read and execute, +and other permissions to read. +.sp +.RS +.nf + +\fB#include <sys/stat.h> +.sp + +#define CHANGEFILE "/etc/myfile" +\&... +chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH); +\fP +.fi +.RE +.SS Setting and Checking File Permissions +.LP +The following example sets the file permission bits for a file named +\fB/home/cnd/mod1\fP, then calls the \fIstat\fP() function to verify +the permissions. +.sp +.RS +.nf + +\fB#include <sys/types.h> +#include <sys/stat.h> +.sp + +int status; +struct stat buffer +\&... +chmod("home/cnd/mod1", S_IRWXU|S_IRWXG|S_IROTH|S_IWOTH); +status = stat("home/cnd/mod1", &buffer;); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +In order to ensure that the S_ISUID and S_ISGID bits are set, an application +requiring this should use \fIstat\fP() after a successful \fIchmod\fP() +to verify this. +.LP +Any file descriptors currently open by any process on the file could +possibly become invalid if the mode of the file is changed +to a value which would deny access to that process. One situation +where this could occur is on a stateless file system. This +behavior will not occur in a conforming environment. +.SH RATIONALE +.LP +This volume of IEEE\ Std\ 1003.1-2001 specifies that the S_ISGID bit +is cleared by \fIchmod\fP() on a regular file +under certain conditions. This is specified on the assumption that +regular files may be executed, and the system should prevent +users from making executable \fIsetgid\fP() files perform with privileges +that the caller +does not have. On implementations that support execution of other +file types, the S_ISGID bit should be cleared for those file +types under the same circumstances. +.LP +Implementations that use the S_ISUID bit to indicate some other function +(for example, mandatory record locking) on +non-executable files need not clear this bit on writing. They should +clear the bit for executable files and any other cases where +the bit grants special powers to processes that change the file contents. +Similar comments apply to the S_ISGID bit. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchown\fP() , \fImkdir\fP() , \fImkfifo\fP() , +\fIopen\fP() , \fIstat\fP() , \fIstatvfs\fP() , the +Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<sys/stat.h>\fP, +\fI<sys/types.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. 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.opengroup.org/unix/online.html . |