man3p/mkfifo.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "MKFIFO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" mkfifo
   4 .SH NAME
   5 mkfifo \- make a FIFO special file
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <sys/stat.h>
   9 .br
  10 .sp
  11 int mkfifo(const char *\fP\fIpath\fP\fB, mode_t\fP \fImode\fP\fB);
  12 .br
  13 \fP
  14 .SH DESCRIPTION
  15 .LP
  16 The \fImkfifo\fP() function shall create a new FIFO special file named
  17 by the pathname pointed to by \fIpath\fP. The file
  18 permission bits of the new FIFO shall be initialized from \fImode\fP.
  19 The file permission bits of the \fImode\fP argument shall
  20 be modified by the process' file creation mask.
  21 .LP
  22 When bits in \fImode\fP other than the file permission bits are set,
  23 the effect is implementation-defined.
  24 .LP
  25 If \fIpath\fP names a symbolic link, \fImkfifo\fP() shall fail and
  26 set \fIerrno\fP to [EEXIST].
  27 .LP
  28 The FIFO's user ID shall be set to the process' effective user ID.
  29 The FIFO's group ID shall be set to the group ID of the
  30 parent directory or to the effective group ID of the process. Implementations
  31 shall provide a way to initialize the FIFO's group ID
  32 to the group ID of the parent directory. Implementations may, but
  33 need not, provide an implementation-defined way to initialize the
  34 FIFO's group ID to the effective group ID of the calling process.
  35 .LP
  36 Upon successful completion, \fImkfifo\fP() shall mark for update the
  37 \fIst_atime\fP, \fIst_ctime\fP, and \fIst_mtime\fP
  38 fields of the file. Also, the \fIst_ctime\fP and \fIst_mtime\fP fields
  39 of the directory that contains the new entry shall be
  40 marked for update.
  41 .SH RETURN VALUE
  42 .LP
  43 Upon successful completion, 0 shall be returned. Otherwise, -1 shall
  44 be returned, no FIFO shall be created, and \fIerrno\fP
  45 shall be set to indicate the error.
  46 .SH ERRORS
  47 .LP
  48 The \fImkfifo\fP() function shall fail if:
  49 .TP 7
  50 .B EACCES
  51 A component of the path prefix denies search permission, or write
  52 permission is denied on the parent directory of the FIFO to
  53 be created.
  54 .TP 7
  55 .B EEXIST
  56 The named file already exists.
  57 .TP 7
  58 .B ELOOP
  59 A loop exists in symbolic links encountered during resolution of the
  60 \fIpath\fP argument.
  61 .TP 7
  62 .B ENAMETOOLONG
  63 The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname
  64 component is longer than {NAME_MAX}.
  65 .TP 7
  66 .B ENOENT
  67 A component of the path prefix specified by \fIpath\fP does not name
  68 an existing directory or \fIpath\fP is an empty
  69 string.
  70 .TP 7
  71 .B ENOSPC
  72 The directory that would contain the new file cannot be extended or
  73 the file system is out of file-allocation resources.
  74 .TP 7
  75 .B ENOTDIR
  76 A component of the path prefix is not a directory.
  77 .TP 7
  78 .B EROFS
  79 The named file resides on a read-only file system.
  80 .sp
  81 .LP
  82 The \fImkfifo\fP() function may fail if:
  83 .TP 7
  84 .B ELOOP
  85 More than {SYMLOOP_MAX} symbolic links were encountered during resolution
  86 of the \fIpath\fP argument.
  87 .TP 7
  88 .B ENAMETOOLONG
  89 As a result of encountering a symbolic link in resolution of the \fIpath\fP
  90 argument, the length of the substituted pathname
  91 string exceeded {PATH_MAX}.
  92 .sp
  93 .LP
  94 \fIThe following sections are informative.\fP
  95 .SH EXAMPLES
  96 .SS Creating a FIFO File
  97 .LP
  98 The following example shows how to create a FIFO file named \fB/home/cnd/mod_done\fP,
  99 with read/write permissions for owner,
 100 and with read permissions for group and others.
 101 .sp
 102 .RS
 103 .nf
 104
 105 \fB#include <sys/types.h>
 106 #include <sys/stat.h>
 107 .sp
 108
 109 int status;
 110 \&...
 111 status = mkfifo("/home/cnd/mod_done", S_IWUSR | S_IRUSR |
 112     S_IRGRP | S_IROTH);
 113 \fP
 114 .fi
 115 .RE
 116 .SH APPLICATION USAGE
 117 .LP
 118 None.
 119 .SH RATIONALE
 120 .LP
 121 The syntax of this function is intended to maintain compatibility
 122 with historical implementations of \fImknod\fP(). The latter function
 123 was included in the 1984 /usr/group standard but only for use in
 124 creating FIFO special files. The \fImknod\fP() function was originally
 125 excluded from the
 126 POSIX.1-1988 standard as implementation-defined and replaced by \fImkdir\fP()
 127 and
 128 \fImkfifo\fP(). The \fImknod\fP() function is now included for alignment
 129 with the Single
 130 UNIX Specification.
 131 .LP
 132 The POSIX.1-1990 standard required that the group ID of a newly created
 133 FIFO be set to the group ID of its parent directory or
 134 to the effective group ID of the creating process. FIPS 151-2 required
 135 that implementations provide a way to have the group ID be
 136 set to the group ID of the containing directory, but did not prohibit
 137 implementations also supporting a way to set the group ID to
 138 the effective group ID of the creating process. Conforming applications
 139 should not assume which group ID will be used. If it
 140 matters, an application can use \fIchown\fP() to set the group ID
 141 after the FIFO is created,
 142 or determine under what conditions the implementation will set the
 143 desired group ID.
 144 .SH FUTURE DIRECTIONS
 145 .LP
 146 None.
 147 .SH SEE ALSO
 148 .LP
 149 \fIumask\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
 150 \fI<sys/stat.h>\fP, \fI<sys/types.h>\fP
 151 .SH COPYRIGHT
 152 Portions of this text are reprinted and reproduced in electronic form
 153 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 154 -- Portable Operating System Interface (POSIX), The Open Group Base
 155 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 156 Electrical and Electronics Engineers, Inc and The Open Group. In the
 157 event of any discrepancy between this version and the original IEEE and
 158 The Open Group Standard, the original IEEE and The Open Group Standard
 159 is the referee document. The original Standard can be obtained online at
 160 http://www.opengroup.org/unix/online.html .