man2/mknod.2

   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 (date) "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 in Linux 2.6.16;
 246 library support was added in glibc 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)