fchmodat(2)

1chmod(2)                      System Calls Manual                     chmod(2)
2
3
4

NAME

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

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

138       On success, zero is returned.  On error, -1 is returned, and  errno  is
139       set to indicate the error.
140

ERRORS

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

VERSIONS

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

STANDARDS

204       POSIX.1-2008.
205

HISTORY

207       chmod()
208       fchmod()
209              4.4BSD, SVr4, POSIX.1-2001.
210
211       fchmodat()
212              POSIX.1-2008.  Linux 2.6.16, glibc 2.4.
213