1CHMOD(2)                   Linux Programmer's Manual                  CHMOD(2)
2
3
4

NAME

6       chmod, fchmod, fchmodat - change permissions of a file
7

SYNOPSIS

9       #include <sys/stat.h>
10
11       int chmod(const char *pathname, mode_t mode);
12       int fchmod(int fd, mode_t mode);
13
14       #include <fcntl.h>           /* Definition of AT_* constants */
15       #include <sys/stat.h>
16
17       int fchmodat(int dirfd, const char *pathname, mode_t mode, int flags);
18
19   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
20
21       fchmod():
22           Since glibc 2.24:
23               _POSIX_C_SOURCE >= 199309L
24           Glibc 2.19 to 2.23
25               _POSIX_C_SOURCE
26           Glibc 2.16 to 2.19:
27               _BSD_SOURCE || _POSIX_C_SOURCE
28           Glibc 2.12 to 2.16:
29               _BSD_SOURCE || _XOPEN_SOURCE >= 500
30                   || _POSIX_C_SOURCE >= 200809L
31           Glibc 2.11 and earlier:
32               _BSD_SOURCE || _XOPEN_SOURCE >= 500
33
34       fchmodat():
35           Since glibc 2.10:
36               _POSIX_C_SOURCE >= 200809L
37           Before glibc 2.10:
38               _ATFILE_SOURCE
39

DESCRIPTION

41       The  chmod() and fchmod() system calls change a file's mode bits.  (The
42       file mode consists of the file permission bits  plus  the  set-user-ID,
43       set-group-ID,  and sticky bits.)  These system calls differ only in how
44       the file is specified:
45
46       * chmod() changes the mode of the  file  specified  whose  pathname  is
47         given in pathname, which is dereferenced if it is a symbolic link.
48
49       * fchmod()  changes  the  mode of the file referred to by the open file
50         descriptor fd.
51
52       The new file mode is specified in mode, which is a bit mask created  by
53       ORing together zero or more of the following:
54
55       S_ISUID  (04000)  set-user-ID  (set  process  effective  user ID on ex‐
56                         ecve(2))
57
58       S_ISGID  (02000)  set-group-ID (set process effective group ID  on  ex‐
59                         ecve(2); mandatory locking, as described in fcntl(2);
60                         take a new file's group from parent directory, as de‐
61                         scribed in chown(2) and mkdir(2))
62
63       S_ISVTX  (01000)  sticky bit (restricted deletion flag, as described in
64                         unlink(2))
65
66       S_IRUSR  (00400)  read by owner
67
68       S_IWUSR  (00200)  write by owner
69
70       S_IXUSR  (00100)  execute/search by owner ("search" applies for  direc‐
71                         tories,  and  means that entries within the directory
72                         can be accessed)
73
74       S_IRGRP  (00040)  read by group
75
76       S_IWGRP  (00020)  write by group
77
78       S_IXGRP  (00010)  execute/search by group
79
80       S_IROTH  (00004)  read by others
81
82       S_IWOTH  (00002)  write by others
83
84       S_IXOTH  (00001)  execute/search by others
85
86       The effective UID of the calling process must match the  owner  of  the
87       file,  or  the  process  must  be  privileged  (Linux: it must have the
88       CAP_FOWNER capability).
89
90       If the calling process is not privileged  (Linux:  does  not  have  the
91       CAP_FSETID  capability),  and  the group of the file does not match the
92       effective group ID of the process or one  of  its  supplementary  group
93       IDs, the S_ISGID bit will be turned off, but this will not cause an er‐
94       ror to be returned.
95
96       As a security measure, depending on the filesystem, the set-user-ID and
97       set-group-ID  execution  bits  may  be turned off if a file is written.
98       (On Linux, this occurs  if  the  writing  process  does  not  have  the
99       CAP_FSETID  capability.)   On  some filesystems, only the superuser can
100       set the sticky bit, which may have a special meaning.  For  the  sticky
101       bit,  and for set-user-ID and set-group-ID bits on directories, see in‐
102       ode(7).
103
104       On NFS filesystems, restricting the permissions will immediately influ‐
105       ence  already  open  files,  because  the access control is done on the
106       server, but open files are maintained by the client.  Widening the per‐
107       missions  may  be delayed for other clients if attribute caching is en‐
108       abled on them.
109
110   fchmodat()
111       The fchmodat() system call operates in exactly the same way as chmod(),
112       except for the differences described here.
113
114       If  the  pathname given in pathname is relative, then it is interpreted
115       relative to the directory referred to  by  the  file  descriptor  dirfd
116       (rather  than  relative to the current working directory of the calling
117       process, as is done by chmod() for a relative pathname).
118
119       If pathname is relative and dirfd is the special value  AT_FDCWD,  then
120       pathname  is  interpreted  relative to the current working directory of
121       the calling process (like chmod()).
122
123       If pathname is absolute, then dirfd is ignored.
124
125       flags can either be 0, or include the following flag:
126
127       AT_SYMLINK_NOFOLLOW
128              If pathname is a symbolic link, do not dereference  it:  instead
129              operate  on  the link itself.  This flag is not currently imple‐
130              mented.
131
132       See openat(2) for an explanation of the need for fchmodat().
133

RETURN VALUE

135       On success, zero is returned.  On error, -1 is returned, and  errno  is
136       set to indicate the error.
137

ERRORS

139       Depending  on  the filesystem, errors other than those listed below can
140       be returned.
141
142       The more general errors for chmod() are listed below:
143
144       EACCES Search permission is denied on a component of the  path  prefix.
145              (See also path_resolution(7).)
146
147       EBADF  (fchmod()) The file descriptor fd is not valid.
148
149       EBADF  (fchmodat())  pathname is relative but dirfd is neither AT_FDCWD
150              nor a valid file descriptor.
151
152       EFAULT pathname points outside your accessible address space.
153
154       EINVAL (fchmodat()) Invalid flag specified in flags.
155
156       EIO    An I/O error occurred.
157
158       ELOOP  Too many symbolic links were encountered in resolving pathname.
159
160       ENAMETOOLONG
161              pathname is too long.
162
163       ENOENT The file does not exist.
164
165       ENOMEM Insufficient kernel memory was available.
166
167       ENOTDIR
168              A component of the path prefix is not a directory.
169
170       ENOTDIR
171              (fchmodat()) pathname is relative and dirfd is a file descriptor
172              referring to a file other than a directory.
173
174       ENOTSUP
175              (fchmodat())  flags  specified AT_SYMLINK_NOFOLLOW, which is not
176              supported.
177
178       EPERM  The effective UID does not match the owner of the file, and  the
179              process   is  not  privileged  (Linux:  it  does  not  have  the
180              CAP_FOWNER capability).
181
182       EPERM  The   file   is   marked   immutable   or   append-only.    (See
183              ioctl_iflags(2).)
184
185       EROFS  The named file resides on a read-only filesystem.
186

VERSIONS

188       fchmodat()  was  added  to  Linux in kernel 2.6.16; library support was
189       added to glibc in version 2.4.
190

CONFORMING TO

192       chmod(), fchmod(): 4.4BSD, SVr4, POSIX.1-2001i, POSIX.1-2008.
193
194       fchmodat(): POSIX.1-2008.
195

NOTES

197   C library/kernel differences
198       The GNU C library fchmodat() wrapper  function  implements  the  POSIX-
199       specified  interface  described  in  this page.  This interface differs
200       from the underlying Linux system call, which does not have a flags  ar‐
201       gument.
202
203   Glibc notes
204       On  older  kernels  where  fchmodat() is unavailable, the glibc wrapper
205       function falls back to the use of chmod().  When pathname is a relative
206       pathname,  glibc  constructs  a  pathname based on the symbolic link in
207       /proc/self/fd that corresponds to the dirfd argument.
208

SEE ALSO

210       chmod(1), chown(2), execve(2), open(2), stat(2), inode(7), path_resolu‐
211       tion(7), symlink(7)
212

COLOPHON

214       This  page  is  part of release 5.13 of the Linux man-pages project.  A
215       description of the project, information about reporting bugs,  and  the
216       latest     version     of     this    page,    can    be    found    at
217       https://www.kernel.org/doc/man-pages/.
218
219
220
221Linux                             2021-08-27                          CHMOD(2)
Impressum