1MKNOD(3P)                  POSIX Programmer's Manual                 MKNOD(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       mknod, mknodat — make directory, special file, or regular file
14

SYNOPSIS

16       #include <sys/stat.h>
17
18       int mknod(const char *path, mode_t mode, dev_t dev);
19       int mknodat(int fd, const char *path, mode_t mode, dev_t dev);
20

DESCRIPTION

22       The mknod() function shall create a new file named by the  pathname  to
23       which the argument path points.
24
25       The  file type for path is OR'ed into the mode argument, and the appli‐
26       cation shall select one of the following symbolic constants:
27
28                   ┌───────────┬──────────────────────────────────┐
29Name    Description            
30                   ├───────────┼──────────────────────────────────┤
31                   │S_IFIFO    │ FIFO-special                     │
32                   │S_IFCHR    │ Character-special (non-portable) │
33                   │S_IFDIR    │ Directory (non-portable)         │
34                   │S_IFBLK    │ Block-special (non-portable)     │
35                   │S_IFREG    │ Regular (non-portable)           │
36                   └───────────┴──────────────────────────────────┘
37       The only portable use of mknod() is to create a FIFO-special  file.  If
38       mode is not S_IFIFO or dev is not 0, the behavior of mknod() is unspec‐
39       ified.
40
41       The permissions for the new file are OR'ed into the mode argument,  and
42       may  be  selected  from  any combination of the following symbolic con‐
43       stants:
44
45             ┌───────────┬─────────────────────────────────────────────┐
46Name    Description                 
47             ├───────────┼─────────────────────────────────────────────┤
48             │S_ISUID    │ Set user ID on execution.                   │
49             │S_ISGID    │ Set group ID on execution.                  │
50             │S_IRWXU    │ Read, write, or execute (search) by owner.  │
51             │S_IRUSR    │ Read by owner.                              │
52             │S_IWUSR    │ Write by owner.                             │
53             │S_IXUSR    │ Execute (search) by owner.                  │
54             │S_IRWXG    │ Read, write, or execute (search) by group.  │
55             │S_IRGRP    │ Read by group.                              │
56             │S_IWGRP    │ Write by group.                             │
57             │S_IXGRP    │ Execute (search) by group.                  │
58             │S_IRWXO    │ Read, write, or execute (search) by others. │
59             │S_IROTH    │ Read by others.                             │
60             │S_IWOTH    │ Write by others.                            │
61             │S_IXOTH    │ Execute (search) by others.                 │
62             │S_ISVTX    │ On directories, restricted deletion flag.   │
63             └───────────┴─────────────────────────────────────────────┘
64       The user ID of the file shall be initialized to the effective  user  ID
65       of the process. The group ID of the file shall be initialized to either
66       the effective group ID of the process or the group  ID  of  the  parent
67       directory. Implementations shall provide a way to initialize the file's
68       group ID to the group ID of the parent directory. Implementations  may,
69       but  need  not, provide an implementation-defined way to initialize the
70       file's group ID to the effective group ID of the calling  process.  The
71       owner,  group,  and  other permission bits of mode shall be modified by
72       the file mode creation mask of the process. The mknod() function  shall
73       clear  each  bit whose corresponding bit in the file mode creation mask
74       of the process is set.
75
76       If path names a symbolic link, mknod() shall  fail  and  set  errno  to
77       [EEXIST].
78
79       Upon successful completion, mknod() shall mark for update the last data
80       access, last data modification, and last file status change  timestamps
81       of  the  file.  Also,  the  last data modification and last file status
82       change timestamps of the directory that contains the new entry shall be
83       marked for update.
84
85       Only  a process with appropriate privileges may invoke mknod() for file
86       types other than FIFO-special.
87
88       The mknodat() function shall be  equivalent  to  the  mknod()  function
89       except  in  the case where path specifies a relative path. In this case
90       the newly created directory, special file, or regular file  is  located
91       relative  to  the  directory  associated  with  the  file descriptor fd
92       instead of the current working directory. If the  file  descriptor  was
93       opened  without  O_SEARCH,  the  function shall check whether directory
94       searches are permitted using the current permissions of  the  directory
95       underlying  the file descriptor. If the file descriptor was opened with
96       O_SEARCH, the function shall not perform the check.
97
98       If mknodat() is passed the special value AT_FDCWD in the fd  parameter,
99       the  current  working directory shall be used and the behavior shall be
100       identical to a call to mknod().
101

RETURN VALUE

103       Upon successful completion, these functions shall return 0.  Otherwise,
104       these functions shall return −1 and set errno to indicate the error. If
105       −1 is returned, the new file shall not be created.
106

ERRORS

108       These functions shall fail if:
109
110       EACCES A component of the path  prefix  denies  search  permission,  or
111              write permission is denied on the parent directory.
112
113       EEXIST The named file exists.
114
115       EINVAL An invalid argument exists.
116
117       EIO    An I/O error occurred while accessing the file system.
118
119       ELOOP  A loop exists in symbolic links encountered during resolution of
120              the path argument.
121
122       ENAMETOOLONG
123              The  length  of  a  component  of  a  pathname  is  longer  than
124              {NAME_MAX}.
125
126       ENOENT A component of the path prefix of path does not name an existing
127              file or path is an empty string.
128
129       ENOENT or ENOTDIR
130              The path argument contains at least  one  non-<slash>  character
131              and  ends  with one or more trailing <slash> characters. If path
132              names an existing file, an [ENOENT] error shall not occur.
133
134       ENOSPC The directory that would contain the new file cannot be extended
135              or the file system is out of file allocation resources.
136
137       ENOTDIR
138              A  component  of  the path prefix names an existing file that is
139              neither a directory nor a symbolic link to a directory.
140
141       EPERM  The invoking process does not have  appropriate  privileges  and
142              the file type is not FIFO-special.
143
144       EROFS  The directory in which the file is to be created is located on a
145              read-only file system.
146
147       The mknodat() function shall fail if:
148
149       EACCES fd was not opened with  O_SEARCH  and  the  permissions  of  the
150              directory underlying fd do not permit directory searches.
151
152       EBADF  The  path  argument does not specify an absolute path and the fd
153              argument is neither AT_FDCWD nor a valid  file  descriptor  open
154              for reading or searching.
155
156       ENOTDIR
157              The  path  argument  is  not  an  absolute path and fd is a file
158              descriptor associated with a non-directory file.
159
160       These functions may fail if:
161
162       ELOOP  More than {SYMLOOP_MAX} symbolic links were  encountered  during
163              resolution of the path argument.
164
165       ENAMETOOLONG
166              The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
167              tion of a symbolic link produced an intermediate result  with  a
168              length that exceeds {PATH_MAX}.
169
170       The following sections are informative.
171

EXAMPLES

173   Creating a FIFO Special File
174       The  following  example  shows  how to create a FIFO special file named
175       /home/cnd/mod_done, with read/write permissions  for  owner,  and  with
176       read permissions for group and others.
177
178           #include <sys/types.h>
179           #include <sys/stat.h>
180
181           dev_t dev;
182           int   status;
183           ...
184           status  = mknod("/home/cnd/mod_done", S_IFIFO | S_IWUSR |
185               S_IRUSR | S_IRGRP | S_IROTH, dev);
186

APPLICATION USAGE

188       The  mkfifo()  function is preferred over this function for making FIFO
189       special files.
190

RATIONALE

192       The POSIX.1‐1990 standard required that the group ID of a newly created
193       file be set to the group ID of its parent directory or to the effective
194       group ID of the creating process. FIPS 151‐2 required that  implementa‐
195       tions  provide a way to have the group ID be set to the group ID of the
196       containing directory, but did not prohibit  implementations  also  sup‐
197       porting a way to set the group ID to the effective group ID of the cre‐
198       ating process.  Conforming applications should not assume  which  group
199       ID  will  be used. If it matters, an application can use chown() to set
200       the group ID after the file is created, or determine under what  condi‐
201       tions the implementation will set the desired group ID.
202
203       The purpose of the mknodat() function is to create directories, special
204       files, or regular files in directories other than the  current  working
205       directory  without exposure to race conditions. Any part of the path of
206       a file could be changed in parallel to a call to mknod(), resulting  in
207       unspecified  behavior.  By  opening  a  file  descriptor for the target
208       directory and using the mknodat() function it can  be  guaranteed  that
209       the  newly  created directory, special file, or regular file is located
210       relative to the desired directory.
211

FUTURE DIRECTIONS

213       None.
214

SEE ALSO

216       chmod(), creat(), exec, fstatat(), mkdir(), mkfifo(), open(), umask()
217
218       The Base Definitions volume of POSIX.1‐2008, <sys_stat.h>
219
221       Portions of this text are reprinted and reproduced in  electronic  form
222       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
223       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
224       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
225       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
226       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
227       event of any discrepancy between this version and the original IEEE and
228       The  Open Group Standard, the original IEEE and The Open Group Standard
229       is the referee document. The original Standard can be  obtained  online
230       at http://www.unix.org/online.html .
231
232       Any  typographical  or  formatting  errors that appear in this page are
233       most likely to have been introduced during the conversion of the source
234       files  to  man page format. To report such errors, see https://www.ker
235       nel.org/doc/man-pages/reporting_bugs.html .
236
237
238
239IEEE/The Open Group                  2013                            MKNOD(3P)
Impressum