ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/mkfifo.htm

766 lines
17 KiB
HTML

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>mkfifo()--Make FIFO Special File</title>
<!-- Begin Header Records -->
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- Created by Jerry Von Berge for V5R1-->
<!-- 010314 JTROUS Change due to S_ISGID change, V5R2, DCR 98686 -->
<!-- 011022 JTROUS Changes from API Review 1, V5R2 -->
<!-- 0205?? JET This file has undergone html cleanup -->
<!-- 020719 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 -->
<!-- 020918 Rosckes: Add ENOTAVAIL errno description, V5R3 -->
<!-- 050404 JTROUS: fix enums, no change flag, V5R4 -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body><!--Java sync-link-->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<a name="Top_Of_Page"></a>
<h2>mkfifo()--Make FIFO Special File</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;sys/types.h&gt;
#include &lt;sys/stat.h&gt;
int mkfifo(const char <em>*path</em>, mode_t <em>mode</em>);
</pre>
&nbsp;&nbsp;Service Program Name: QP0LLIB1<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Conditional; see <a href="#USAGE_NOTES">Usage Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>mkfifo()</strong> function creates a new FIFO special file
(FIFO) whose name is defined by <em>path</em>. A FIFO special file is a type of
file with the property that data written to the file is read on a
first-in-first-out basis. See the <strong>open()</strong>, <strong>
read()</strong>, <strong>write()</strong>, <strong>lseek</strong>, and <strong>
close</strong> functions for more characteristics of a FIFO special file.</p>
<p>A FIFO may be opened for reading only or writing only for a uni-directional
I/O. It also may be opened for reading and writing access to provide a
bi-directional FIFO descriptor.</p>
<p>The file permission bits in <em>mode</em> are modified by the file creation
mask of the job and then used to set the file permission bits of the FIFO being
created.</p>
<p>For more information on the permission bits in <em>mode</em>, see <a href=
"chmod.htm">chmod()</a>--Change File Authorizations. For more information on
the file creation mask, see <a href="umask.htm">umask()</a>--Set Authorization
Mask for Job.</p>
<p>The owner ID of the new FIFO is set to the effective user ID (UID) of the
thread. If the object is being created in the "root" (/), QOpenSys, and
user-defined file systems, the following applies. If the S_ISGID bit of the
parent directory is off, the group ID (GID) is set to the effective GID of the
thread creating the object. If the S_ISGID bit of the parent directory is on,
the group ID (GID) of the new object is set to the GID of the parent directory.
For all other file systems, the group ID (GID) of the new FIFO is set to the
GID of the parent directory.</p>
<p>Upon successful completion, <strong>mkfifo()</strong> sets the access,
change, modification, and creation times for the new FIFO. It also sets the
change and modification times for the directory that contains the new FIFO
(parent directory).</p>
<p>If <em>path</em> contains a symbolic link, the symbolic link is
followed.</p>
<p>If <em>path</em> names a symbolic link, the symbolic link is not followed,
and <strong>mkfifo()</strong> fails with the [EEXIST] error.</p>
<p>If bits in <em>mode</em> other than the file permission bits are set,
<strong>mkfifo()</strong> fails with the [EINVAL] error.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>path</em></strong></dt>
<dd>(Input) A pointer to the null-terminated path name of the FIFO special file
to be created.<br>
<p>This parameter is assumed to be represented in the CCSID (coded character
set identifier) currently in effect for the job. If the CCSID of the job is
65535, this parameter is assumed to be represented in the default CCSID of the
job.</p>
<p>The name of the new FIFO is assumed to be represented in the language and
country or region currently in effect for the process.</p>
<p>See <a href="mkfifou.htm">QlgMkfifo()</a>--Make FIFO Special File (using
NLS-enabled path name) for a description and an example of supplying the <em>
path</em> in any CCSID.</p>
</dd>
<dt><strong><em>mode</em></strong></dt>
<dd>(Input) Permission bits for the new FIFO.</dd>
</dl>
<br>
<h3>Authorities</h3>
<p>Adopted authority is not used.</p>
<p><strong><a name="TBLAMKFIFO">Authorization Required for
mkfifo()</a></strong></p>
<table border cellpadding="5" width="80%">
<tr>
<th align="left" valign="bottom">Object Referred to</th>
<th align="center" valign="bottom">Authority<br>
Required</th>
<th align="left" valign="bottom">errno</th>
</tr>
<tr>
<td align="left" valign="top" width="70%">Each directory in the path name
preceding the FIFO to be created.</td>
<td align="center" valign="top" width="15%">*X</td>
<td align="left" valign="top" width="15%">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Parent directory of FIFO to be created</td>
<td align="center" valign="top">*WX</td>
<td align="left" valign="top">EACCES</td>
</tr>
</table>
<br>
<br>
<h3>Return Value</h3>
<table>
<tr>
<td align="left" valign="top" width="5%"><em>0</em></td>
<td align="left" valign="top" width="95%"><strong>mkfifo()</strong> was
successful. The FIFO was created.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top"><strong>mkfifo()</strong> was not successful. The
FIFO was not created. The <em>errno</em> global variable is set to indicate the
error.</td>
</tr>
</table>
<br>
<br>
<h3>Error Conditions</h3>
<p>If <strong>mkfifo()</strong> is not successful, <em>errno</em> usually
indicates one of the following errors. Under some conditions, <em>errno</em>
could indicate an error other than those listed here.</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<th align="left" valign="bottom">Error condition</th>
<th align="left" valign="bottom">Additional information</th>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EACCES">EACCES</a>]</em></td>
<td align="left" valign="top">
<p>If you are accessing a remote file through the Network File System, update
operations to file permissions at the server are not reflected at the client
until updates to data that is stored locally by the Network File System take
place. (Several options on the Add Mounted File System (ADDMFS) command
determine the time between refresh operations of local data.) Access to a
remote file also may fail due to different mappings of user IDs (UID) or group
IDs (GID) on the local and remote systems.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EAGAIN">EAGAIN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBADFID">EBADFID</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBADNAME">EBADNAME</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBUSY">EBUSY</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONVERT">ECONVERT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EDAMAGE">EDAMAGE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EEXIST">EEXIST</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EFAULT">EFAULT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EFILECVT">EFILECVT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EINTR">EINTR</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EINVAL">EINVAL</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EIO">EIO</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ELOOP">ELOOP</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EMLINK">EMLINK</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENAMETOOLONG">ENAMETOOLONG</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOENT">ENOENT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOMEM">ENOMEM</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOSPC">ENOSPC</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOSYS">ENOSYS</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTAVAIL">ENOTAVAIL</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTDIR">ENOTDIR</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTSAFE">ENOTSAFE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTSUP">ENOTSUP</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EPERM">EPERM</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EROFS">EROFS</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EROOBJ">EROOBJ</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ESTALE">ESTALE</a>]</em></td>
<td align="left" valign="top">
<p>If you are accessing a remote file through the Network File System, the file
may have been deleted at the server.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EUNKNOWN">EUNKNOWN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
</table>
<p>If interaction with a file server is required to access the object, <em>
errno</em> could indicate one of the following errors:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<th align="left" valign="bottom">Error condition</th>
<th align="left" valign="bottom">Additional information</th>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EADDRNOTAVAIL">EADDRNOTAVAIL</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONNABORTED">ECONNABORTED</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONNREFUSED">ECONNREFUSED</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECONNRESET">ECONNRESET</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EHOSTDOWN">EHOSTDOWN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EHOSTUNREACH">EHOSTUNREACH</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETDOWN">ENETDOWN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETRESET">ENETRESET</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENETUNREACH">ENETUNREACH</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ESTALE">ESTALE</a>]</em></td>
<td align="left" valign="top">
<p>If you are accessing a remote file through the Network File System, the file
may have been deleted at the server.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ETIMEDOUT">ETIMEDOUT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EUNATCH">EUNATCH</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
</table>
<br>
<br>
<h3>Error Messages</h3>
<p>The following messages may be sent from this function:</p>
<table width="100%">
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPE3418 E</td>
<td width="85%" valign="top">Possible APAR condition or hardware failure.</td>
</tr>
<tr>
<td valign="top">CPFA0D4 E</td>
<td valign="top">File system error occurred. Error number &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF3CF2 E</td>
<td valign="top">Error(s) occurred during running of &amp;1 API.</td>
</tr>
<tr>
<td valign="top">CPF9872 E</td>
<td valign="top">Program or service program &amp;1 in library &amp;2 ended.
Reason code &amp;3.</td>
</tr>
</table>
<br>
<h3><a name="usage_notes">Usage Notes</a></h3>
<ol type="1">
<li>This function will fail with error code [ENOTSAFE] when all the following
conditions are true:<br>
<br>
<ul>
<li>Where multiple threads exist in the job.</li>
<li>The object on which this function is operating resides in a file system
that is not threadsafe. Only the following file systems are threadsafe for this
function:<br>
<br>
<ul>
<li>"Root" (/)</li>
<li>QOpenSys</li>
<li>User-defined</li>
<li>QNTC</li>
<li>QSYS.LIB</li>
<li>Independent ASP QSYS.LIB</li>
<li>QOPT</li>
<li>QFileSvr.400</li>
</ul>
</li>
</ul>
<br>
</li>
<li>The following file systems support <strong>mkfifo()</strong>:</p>
<ul>
<li>"Root" (/)</li>
<li>QOpenSys</li>
<li>User-defined</li>
</ul>
<br>
</li>
<li>There are some restrictions when opening a FIFO for text conversion and the
CCSIDs involved are not strictly single-byte:<br>
<br>
<ul>
<li>Opening a FIFO for reading or reading and writing is not allowed.</li>
<li>Any conversion between CCSIDs that are not strictly single-byte must be
done by an open instance that has write-only access.</li>
</ul>
<br>
</li>
<li>The owner, primary group, and public object authorities (*OBJEXIST,
*OBJMGT, *OBJALTER, and *OBJREF) are copied from the parent directory's owner,
primary group, and public object authorities. This occurs even when the new
FIFO has a different owner than the parent directory. The owner, primary group,
and public data authorities (*R, *W, and *X) are derived from the permissions
specified in the mode (except for those permissions that are also set in the
file mode creation mask). The new FIFO does not have any private authorities or
authorization list. It only has authorities for the owner, primary group, and
public.</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>sys/stat.h</strong>&gt; file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)
</li>
<li>The &lt;<strong>sys/types.h</strong>&gt; file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)
</li>
<li><a href="chmod.htm">chmod()</a>--Change File Authorizations
</li>
<li><a href="umask.htm">umask()</a>--Set Authorization Mask for Job
</li>
<li><a href="mkfifou.htm">QlgMkfifo()</a>--Make FIFO Special File (using
NLS-enabled path name)</li>
</ul>
<br>
<h3>Example</h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<p>The following example creates a new FIFO:</p>
<pre>
#include &lt;sys/types.h&gt;
#include &lt;sys/stat.h&gt;
#include &lt;stdio.h&gt;
void main() {
char *mypath = "/newFIFO";
if (mkfifo(mypath, S_IRWXU|S_IRWXO) != 0)
perror("mkfifo() error");
else
puts("success!");
return;
}
</pre>
<hr>
API introduced: V5R1
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>