| blob | 79f831db9fbcc6fb9c9a6f944b5f11565d90956b |
1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
2 .\" and Copyright (C) 1993 Michael Haardt
3 .\" and Copyright (C) 1993,1994 Ian Jackson
4 .\" and Copyright (C) 2006, 2014, Michael Kerrisk
5 .\"
6 .\" SPDX-License-Identifier: GPL-1.0-or-later
7 .\"
8 .\" Modified 1996-08-18 by urs
9 .\" Modified 2003-04-23 by Michael Kerrisk
10 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
11 .\"
12 .TH MKNOD 2 2022-09-09 "Linux man-pages (unreleased)"
13 .SH NAME
14 mknod, mknodat \- create a special or ordinary file
15 .SH LIBRARY
16 Standard C library
17 .RI ( libc ", " \-lc )
18 .SH SYNOPSIS
19 .nf
20 .B #include <sys/stat.h>
21 .PP
22 .BI "int mknod(const char *" pathname ", mode_t " mode ", dev_t " dev );
23 .PP
24 .BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
25 .B #include <sys/stat.h>
26 .PP
27 .BI "int mknodat(int " dirfd ", const char *" pathname ", mode_t " mode \
28 ", dev_t " dev );
29 .fi
30 .PP
31 .RS -4
32 Feature Test Macro Requirements for glibc (see
33 .BR feature_test_macros (7)):
34 .RE
35 .PP
36 .BR mknod ():
37 .nf
38 _XOPEN_SOURCE >= 500
39 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
40 || /* Since glibc 2.19: */ _DEFAULT_SOURCE
41 || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
42 .fi
43 .SH DESCRIPTION
44 The system call
45 .BR mknod ()
46 creates a filesystem node (file, device special file, or
47 named pipe) named
48 .IR pathname ,
49 with attributes specified by
50 .I mode
51 and
52 .IR dev .
53 .PP
54 The
55 .I mode
56 argument specifies both the file mode to use and the type of node
57 to be created.
58 It should be a combination (using bitwise OR) of one of the file types
59 listed below and zero or more of the file mode bits listed in
60 .BR inode (7).
61 .PP
62 The file mode is modified by the process's
63 .I umask
64 in the usual way: in the absence of a default ACL, the permissions of the
65 created node are
66 .RI ( mode " & \(ti" umask ).
67 .PP
68 The file type must be one of
69 .BR S_IFREG ,
70 .BR S_IFCHR ,
71 .BR S_IFBLK ,
72 .BR S_IFIFO ,
73 or
74 .B S_IFSOCK
75 .\" (S_IFSOCK since Linux 1.2.4)
76 to specify a regular file (which will be created empty), character
77 special file, block special file, FIFO (named pipe), or UNIX domain socket,
78 respectively.
79 (Zero file type is equivalent to type
80 .BR S_IFREG .)
81 .PP
82 If the file type is
83 .B S_IFCHR
84 or
85 .BR S_IFBLK ,
86 then
87 .I dev
88 specifies the major and minor numbers of the newly created device
89 special file
90 .RB ( makedev (3)
91 may be useful to build the value for
92 .IR dev );
93 otherwise it is ignored.
94 .PP
95 If
96 .I pathname
97 already exists, or is a symbolic link, this call fails with an
98 .B EEXIST
99 error.
100 .PP
101 The newly created node will be owned by the effective user ID of the
102 process.
103 If the directory containing the node has the set-group-ID
104 bit set, or if the filesystem is mounted with BSD group semantics, the
105 new node will inherit the group ownership from its parent directory;
106 otherwise it will be owned by the effective group ID of the process.
107 .\"
108 .\"
109 .SS mknodat()
110 The
111 .BR mknodat ()
112 system call operates in exactly the same way as
113 .BR mknod (),
114 except for the differences described here.
115 .PP
116 If the pathname given in
117 .I pathname
118 is relative, then it is interpreted relative to the directory
119 referred to by the file descriptor
120 .I dirfd
121 (rather than relative to the current working directory of
122 the calling process, as is done by
123 .BR mknod ()
124 for a relative pathname).
125 .PP
126 If
127 .I pathname
128 is relative and
129 .I dirfd
130 is the special value
131 .BR AT_FDCWD ,
132 then
133 .I pathname
134 is interpreted relative to the current working
135 directory of the calling process (like
136 .BR mknod ()).
137 .PP
138 If
139 .I pathname
140 is absolute, then
141 .I dirfd
142 is ignored.
143 .PP
144 See
145 .BR openat (2)
146 for an explanation of the need for
147 .BR mknodat ().
148 .SH RETURN VALUE
149 .BR mknod ()
150 and
151 .BR mknodat ()
152 return zero on success.
153 On error, \-1 is returned and
154 .I errno
155 is set to indicate the error.
156 .SH ERRORS
157 .TP
158 .B EACCES
159 The parent directory does not allow write permission to the process,
160 or one of the directories in the path prefix of
161 .I pathname
162 did not allow search permission.
163 (See also
164 .BR path_resolution (7).)
165 .TP
166 .B EBADF
167 .BR ( mknodat ())
168 .I pathname
169 is relative but
170 .I dirfd
171 is neither
172 .B AT_FDCWD
173 nor a valid file descriptor.
174 .TP
175 .B EDQUOT
176 The user's quota of disk blocks or inodes on the filesystem has been
177 exhausted.
178 .TP
179 .B EEXIST
180 .I pathname
181 already exists.
182 This includes the case where
183 .I pathname
184 is a symbolic link, dangling or not.
185 .TP
186 .B EFAULT
187 .IR pathname " points outside your accessible address space."
188 .TP
189 .B EINVAL
190 .I mode
191 requested creation of something other than a regular file, device
192 special file, FIFO or socket.
193 .TP
194 .B ELOOP
195 Too many symbolic links were encountered in resolving
196 .IR pathname .
197 .TP
198 .B ENAMETOOLONG
199 .IR pathname " was too long."
200 .TP
201 .B ENOENT
202 A directory component in
203 .I pathname
204 does not exist or is a dangling symbolic link.
205 .TP
206 .B ENOMEM
207 Insufficient kernel memory was available.
208 .TP
209 .B ENOSPC
210 The device containing
211 .I pathname
212 has no room for the new node.
213 .TP
214 .B ENOTDIR
215 A component used as a directory in
216 .I pathname
217 is not, in fact, a directory.
218 .TP
219 .B ENOTDIR
220 .BR ( mknodat ())
221 .I pathname
222 is relative and
223 .I dirfd
224 is a file descriptor referring to a file other than a directory.
225 .TP
226 .B EPERM
227 .I mode
228 requested creation of something other than a regular file,
229 FIFO (named pipe), or UNIX domain socket, and the caller
230 is not privileged (Linux: does not have the
231 .B CAP_MKNOD
232 capability);
233 .\" For UNIX domain sockets and regular files, EPERM is returned only in
234 .\" Linux 2.2 and earlier; in Linux 2.4 and later, unprivileged can
235 .\" use mknod() to make these files.
236 also returned if the filesystem containing
237 .I pathname
238 does not support the type of node requested.
239 .TP
240 .B EROFS
241 .I pathname
242 refers to a file on a read-only filesystem.
243 .SH VERSIONS
244 .BR mknodat ()
245 was added to Linux in kernel 2.6.16;
246 library support was added to glibc in version 2.4.
247 .SH STANDARDS
248 .BR mknod ():
249 SVr4, 4.4BSD, POSIX.1-2001 (but see below), POSIX.1-2008.
250 .\" The Linux version differs from the SVr4 version in that it
251 .\" does not require root permission to create pipes, also in that no
252 .\" EMULTIHOP, ENOLINK, or EINTR error is documented.
253 .PP
254 .BR mknodat ():
255 POSIX.1-2008.
256 .SH NOTES
257 POSIX.1-2001 says: "The only portable use of
258 .BR mknod ()
259 is to create a FIFO-special file.
260 If
261 .I mode
262 is not
263 .B S_IFIFO
264 or
265 .I dev
266 is not 0, the behavior of
267 .BR mknod ()
268 is unspecified."
269 However, nowadays one should never use
270 .BR mknod ()
271 for this purpose; one should use
272 .BR mkfifo (3),
273 a function especially defined for this purpose.
274 .PP
275 Under Linux,
276 .BR mknod ()
277 cannot be used to create directories.
278 One should make directories with
279 .BR mkdir (2).
280 .\" and one should make UNIX domain sockets with socket(2) and bind(2).
281 .PP
282 There are many infelicities in the protocol underlying NFS.
283 Some of these affect
284 .BR mknod ()
285 and
286 .BR mknodat ().
287 .SH SEE ALSO
288 .BR mknod (1),
289 .BR chmod (2),
290 .BR chown (2),
291 .BR fcntl (2),
292 .BR mkdir (2),
293 .BR mount (2),
294 .BR socket (2),
295 .BR stat (2),
296 .BR umask (2),
297 .BR unlink (2),
298 .BR makedev (3),
299 .BR mkfifo (3),
300 .BR acl (5),
301 .BR path_resolution (7)