diff options
Diffstat (limited to 'upstream/archlinux/man3p/mknod.3p')
| -rw-r--r-- | upstream/archlinux/man3p/mknod.3p | 345 |
1 files changed, 345 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/mknod.3p b/upstream/archlinux/man3p/mknod.3p new file mode 100644 index 00000000..3f4d4454 --- /dev/null +++ b/upstream/archlinux/man3p/mknod.3p @@ -0,0 +1,345 @@ +'\" et +.TH MKNOD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mknod, mknodat +\(em make directory, special file, or regular file +.SH SYNOPSIS +.LP +.nf +#include <sys/stat.h> +.P +int mknod(const char *\fIpath\fP, mode_t \fImode\fP, dev_t \fIdev\fP); +.P +#include <fcntl.h> +.P +int mknodat(int \fIfd\fP, const char *\fIpath\fP, mode_t \fImode\fP, dev_t \fIdev\fP); +.fi +.SH DESCRIPTION +The +\fImknod\fR() +function shall create a new file named by the pathname to which the +argument +.IR path +points. +.P +The file type for +.IR path +is OR'ed into the +.IR mode +argument, and the application shall select one of the following +symbolic constants: +.TS +tab(!) box center; +cB | cB +lw(1i) | lw(3i). +Name!Description +_ +S_IFIFO!FIFO-special +S_IFCHR!Character-special (non-portable) +S_IFDIR!Directory (non-portable) +S_IFBLK!Block-special (non-portable) +S_IFREG!Regular (non-portable) +.TE +.P +The only portable use of +\fImknod\fR() +is to create a FIFO-special file. If +.IR mode +is not S_IFIFO or +.IR dev +is not 0, the behavior of +\fImknod\fR() +is unspecified. +.P +The permissions for the new file are OR'ed into the +.IR mode +argument, and may be selected from any combination of the following +symbolic constants: +.TS +tab(!) box center; +cB | cB +lw(1i) | lw(3i). +Name!Description +_ +S_ISUID!Set user ID on execution. +S_ISGID!Set group ID on execution. +S_IRWXU!Read, write, or execute (search) by owner. +S_IRUSR!Read by owner. +S_IWUSR!Write by owner. +S_IXUSR!Execute (search) by owner. +S_IRWXG!Read, write, or execute (search) by group. +S_IRGRP!Read by group. +S_IWGRP!Write by group. +S_IXGRP!Execute (search) by group. +S_IRWXO!Read, write, or execute (search) by others. +S_IROTH!Read by others. +S_IWOTH!Write by others. +S_IXOTH!Execute (search) by others. +S_ISVTX!On directories, restricted deletion flag. +.TE +.P +The user ID of the file shall be initialized to the effective user ID +of the process. The group ID of the file shall be initialized to either +the effective group ID of the process or the group ID of the parent +directory. Implementations shall provide a way to initialize the file's +group ID to the group ID of the parent directory. Implementations may, +but need not, provide an implementation-defined way to initialize the +file's group ID to the effective group ID of the calling process. The +owner, group, and other permission bits of +.IR mode +shall be modified by the file mode creation mask of the process. The +\fImknod\fR() +function shall clear each bit whose corresponding bit in the file mode +creation mask of the process is set. +.P +If +.IR path +names a symbolic link, +\fImknod\fR() +shall fail and set +.IR errno +to +.BR [EEXIST] . +.P +Upon successful completion, +\fImknod\fR() +shall mark for update the last data access, last data modification, +and last file status change timestamps of the file. Also, the last +data modification and last file status change timestamps of the directory +that contains the new entry shall be marked for update. +.P +Only a process with appropriate privileges may invoke +\fImknod\fR() +for file types other than FIFO-special. +.P +The +\fImknodat\fR() +function shall be equivalent to the +\fImknod\fR() +function except in the case where +.IR path +specifies a relative path. In this case the newly created +directory, special file, or regular file is located relative to the +directory associated with the file descriptor +.IR fd +instead of the current working directory. If the access mode of the +open file description associated with the file descriptor is not +O_SEARCH, the function shall check whether directory searches are +permitted using the current permissions of the directory underlying +the file descriptor. If the access mode is O_SEARCH, the function +shall not perform the check. +.P +If +\fImknodat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fImknod\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \-1 and set +.IR errno +to indicate the error. If \-1 is returned, the new file shall +not be created. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +A component of the path prefix denies search permission, or write +permission is denied on the parent directory. +.TP +.BR EEXIST +The named file exists. +.TP +.BR EINVAL +An invalid argument exists. +.TP +.BR EIO +An I/O error occurred while accessing the file system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the path prefix of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOENT " or " ENOTDIR +.br +The +.IR path +argument contains at least one non-\c +<slash> +character and ends with one or more trailing +<slash> +characters. If +.IR path +without the trailing +<slash> +characters would name an existing file, an +.BR [ENOENT] +error shall not occur. +.TP +.BR ENOSPC +The directory that would contain the new file cannot be extended or the +file system is out of file allocation resources. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory. +.TP +.BR EPERM +The invoking process does not have appropriate privileges and the +file type is not FIFO-special. +.TP +.BR EROFS +The directory in which the file is to be created is located on a +read-only file system. +.br +.P +The +\fImknodat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR fd +is not O_SEARCH and the permissions of the directory underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating a FIFO Special File" +.P +The following example shows how to create a FIFO special file named +.BR /home/cnd/mod_done , +with read/write permissions for owner, and with read permissions for +group and others. +.sp +.RS 4 +.nf + +#include <sys/types.h> +#include <sys/stat.h> +.P +dev_t dev; +int status; +\&... +status = mknod("/home/cnd/mod_done", S_IFIFO | S_IWUSR | + S_IRUSR | S_IRGRP | S_IROTH, dev); +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fImkfifo\fR() +function is preferred over this function for making FIFO special files. +.SH RATIONALE +The POSIX.1\(hy1990 standard required that the group ID of a newly created file be +set to the group ID of its parent directory or to the effective group +ID of the creating process. FIPS 151\(hy2 required that implementations provide +a way to have the group ID be set to the group ID of the containing +directory, but did not prohibit implementations also supporting a way +to set the group ID to the effective group ID of the creating process. +Conforming applications should not assume which group ID will be used. If +it matters, an application can use +\fIchown\fR() +to set the group ID after the file is created, or determine under +what conditions the implementation will set the desired group ID. +.P +The purpose of the +\fImknodat\fR() +function is to create directories, special files, or regular files in +directories other than the current working directory without exposure +to race conditions. Any part of the path of a file could be changed in +parallel to a call to +\fImknod\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fImknodat\fR() +function it can be guaranteed that the newly created directory, special +file, or regular file is located relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fImkdir\fR\^(\|)", +.IR "\fImkfifo\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<fcntl.h>\fP", +.IR "\fB<sys_stat.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |