man3/mkfifo.3

   1 '\" t
   2 .\" This manpage is Copyright (C) 1995 James R. Van Zandt <jrv@vanzandt.mv.com>
   3 .\" and Copyright (C) 2006, 2014 Michael Kerrisk
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .\" changed section from 2 to 3, aeb, 950919
   8 .\"
   9 .TH mkfifo 3 (date) "Linux man-pages (unreleased)"
  10 .SH NAME
  11 mkfifo, mkfifoat \- make a FIFO special file (a named pipe)
  12 .SH LIBRARY
  13 Standard C library
  14 .RI ( libc ", " \-lc )
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <sys/types.h>
  18 .B #include <sys/stat.h>
  19 .PP
  20 .BI "int mkfifo(const char *" pathname ", mode_t " mode );
  21 .PP
  22 .BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
  23 .B #include <sys/stat.h>
  24 .PP
  25 .BI "int mkfifoat(int " dirfd ", const char *" pathname ", mode_t " mode );
  26 .fi
  27 .PP
  28 .RS -4
  29 Feature Test Macro Requirements for glibc (see
  30 .BR feature_test_macros (7)):
  31 .RE
  32 .PP
  33 .BR mkfifoat ():
  34 .nf
  35     Since glibc 2.10:
  36         _POSIX_C_SOURCE >= 200809L
  37     Before glibc 2.10:
  38         _ATFILE_SOURCE
  39 .fi
  40 .SH DESCRIPTION
  41 .BR mkfifo ()
  42 makes a FIFO special file with name \fIpathname\fP.
  43 \fImode\fP specifies the FIFO's permissions.
  44 It is modified by the
  45 process's \fBumask\fP in the usual way: the permissions of the created
  46 file are \fB(\fP\fImode\fP\fB & \[ti]umask)\fP.
  47 .PP
  48 A FIFO special file is similar to a pipe, except that it is created
  49 in a different way.
  50 Instead of being an anonymous communications
  51 channel, a FIFO special file is entered into the filesystem by
  52 calling
  53 .BR mkfifo ().
  54 .PP
  55 Once you have created a FIFO special file in this way, any process can
  56 open it for reading or writing, in the same way as an ordinary file.
  57 However, it has to be open at both ends simultaneously before you can
  58 proceed to do any input or output operations on it.
  59 Opening a FIFO for reading normally blocks until some
  60 other process opens the same FIFO for writing, and vice versa.
  61 See
  62 .BR fifo (7)
  63 for nonblocking handling of FIFO special files.
  64 .SS mkfifoat()
  65 The
  66 .BR mkfifoat ()
  67 function operates in exactly the same way as
  68 .BR mkfifo (),
  69 except for the differences described here.
  70 .PP
  71 If the pathname given in
  72 .I pathname
  73 is relative, then it is interpreted relative to the directory
  74 referred to by the file descriptor
  75 .I dirfd
  76 (rather than relative to the current working directory of
  77 the calling process, as is done by
  78 .BR mkfifo ()
  79 for a relative pathname).
  80 .PP
  81 If
  82 .I pathname
  83 is relative and
  84 .I dirfd
  85 is the special value
  86 .BR AT_FDCWD ,
  87 then
  88 .I pathname
  89 is interpreted relative to the current working
  90 directory of the calling process (like
  91 .BR mkfifo ()).
  92 .PP
  93 If
  94 .I pathname
  95 is absolute, then
  96 .I dirfd
  97 is ignored.
  98 .PP
  99 See
 100 .BR openat (2)
 101 for an explanation of the need for
 102 .BR mkfifoat ().
 103 .SH RETURN VALUE
 104 On success
 105 .BR mkfifo ()
 106 and
 107 .BR mkfifoat ()
 108 return 0.
 109 On error, \-1 is returned and
 110 .I errno
 111 is set to indicate the error.
 112 .SH ERRORS
 113 .TP
 114 .B EACCES
 115 One of the directories in \fIpathname\fP did not allow search
 116 (execute) permission.
 117 .TP
 118 .B EBADF
 119 .RB ( mkfifoat ())
 120 .I pathname
 121 is relative but
 122 .I dirfd
 123 is neither
 124 .B AT_FDCWD
 125 nor a valid file descriptor.
 126 .TP
 127 .B EDQUOT
 128 The user's quota of disk blocks or inodes on the filesystem has been
 129 exhausted.
 130 .TP
 131 .B EEXIST
 132 \fIpathname\fP already exists.
 133 This includes the case where
 134 .I pathname
 135 is a symbolic link, dangling or not.
 136 .TP
 137 .B ENAMETOOLONG
 138 Either the total length of \fIpathname\fP is greater than
 139 \fBPATH_MAX\fP, or an individual filename component has a length
 140 greater than \fBNAME_MAX\fP.
 141 In the GNU system, there is no imposed
 142 limit on overall filename length, but some filesystems may place
 143 limits on the length of a component.
 144 .TP
 145 .B ENOENT
 146 A directory component in \fIpathname\fP does not exist or is a
 147 dangling symbolic link.
 148 .TP
 149 .B ENOSPC
 150 The directory or filesystem has no room for the new file.
 151 .TP
 152 .B ENOTDIR
 153 A component used as a directory in \fIpathname\fP is not, in fact, a
 154 directory.
 155 .TP
 156 .B ENOTDIR
 157 .RB ( mkfifoat ())
 158 .I pathname
 159 is a relative pathname and
 160 .I dirfd
 161 is a file descriptor referring to a file other than a directory.
 162 .TP
 163 .B EROFS
 164 \fIpathname\fP refers to a read-only filesystem.
 165 .SH ATTRIBUTES
 166 For an explanation of the terms used in this section, see
 167 .BR attributes (7).
 168 .TS
 169 allbox;
 170 lbx lb lb
 171 l l l.
 172 Interface       Attribute       Value
 173 T{
 174 .na
 175 .nh
 176 .BR mkfifo (),
 177 .BR mkfifoat ()
 178 T}      Thread safety   MT-Safe
 179 .TE
 180 .sp 1
 181 .SH VERSIONS
 182 It is implemented using
 183 .BR mknodat (2).
 184 .SH STANDARDS
 185 POSIX.1-2008.
 186 .SH HISTORY
 187 .TP
 188 .BR mkfifo ()
 189 POSIX.1-2001.
 190 .TP
 191 .BR mkfifoat ()
 192 glibc 2.4.
 193 POSIX.1-2008.
 194 .SH SEE ALSO
 195 .BR mkfifo (1),
 196 .BR close (2),
 197 .BR open (2),
 198 .BR read (2),
 199 .BR stat (2),
 200 .BR umask (2),
 201 .BR write (2),
 202 .BR fifo (7)