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

382 lines
9.4 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>dup()--Duplicate Open File Descriptor</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 -->
<!-- Unix2 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Change History: -->
<!-- 011022 JTROUS Changes from API Review 1, V5R2 -->
<!-- 020313 JTROUS Changes for scan processing, V5R3, DCR 98680 -->
<!-- 0206?? JET This file has undergone html cleanup -->
<!-- 050323 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>dup()--Duplicate Open File Descriptor</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;unistd.h&gt;
int dup(int <em>fildes</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: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>dup()</strong> function returns a new open file descriptor. The
new descriptor refers to the same open file as <em>fildes</em> and shares any
locks.</p>
<p>If the original file descriptor was opened in text mode, data conversion is
also done on the duplicated file descriptor.</p>
<p>The FD_CLOEXEC flag that is associated with the new file descriptor is
cleared. Refer to <a href="fcntl.htm">fcntl()</a>--Perform File Control Command
for additional information about the FD_CLOEXEC flag.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>fildes</em></strong></dt>
<dd>(Input) A descriptor to be duplicated.</dd>
</dl>
<p>The following operations are equivalent:</p>
<pre>
fd = dup(fildes);
fd = fcntl(fildes,F_DUPFD,0);
</pre>
<p>For further information, see <a href="fcntl.htm">fcntl()--Perform File
Control Command</a>.</p>
<br>
<h3>Authorities</h3>
<p>No authorization is required.</p>
<br>
<h3>Return Value</h3>
<dl compact>
<dt><em>value</em></dt>
<dd><strong>dup()</strong> was successful. The value returned is the new
descriptor.</dd>
<dt><em>-1</em></dt>
<dd><strong>dup()</strong> was not successful. The <em>errno</em> global
variable is set to indicate the error.</dd>
</dl>
<br>
<h3>Error Conditions</h3>
<p>If <strong>dup()</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 may also 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#EBADF">EBADF</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#EBUSY">EBUSY</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ECANCEL">ECANCEL</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#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#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>
<br>
<br>
<h3>Error Messages</h3>
<p>The following messages may be sent from this function:</p>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<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>
<br>
<h3><a name="USAGE_NOTES">Usage Notes</a></h3>
<!-- It is deliberate that this API does not have thread conditional -->
<!-- usage note. dup won't go into any file system code and -->
<!-- since LFS is threadsafe, dup is always threadsafe. -->
<ol>
<li>This function will fail with
error code [EBADF] when <em>fildes</em> is a scan descriptor that was passed to
one of the scan-related exit programs. See <a href="ifsopenexit.htm">Integrated
File System Scan on Open Exit Programs</a> and <a href="ifscloseexit.htm">
Integrated File System Scan on Close Exit Programs</a> for more information.
<br>
<br>
</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>unistd.h</strong>&gt; file (see <a href="unix13.htm">Header
Files for UNIX-Type Functions</a>)<br>
</li>
<li><a href="close.htm">close()</a>--Close File or Socket Descriptor<br>
</li>
<li><a href="creat.htm">creat()</a>--Create or Rewrite File<br>
</li>
<li><a href="dup2.htm">dup2()</a>--Duplicate Open File Descriptor to Another
Descriptor<br>
</li>
<li><a href="fcntl.htm">fcntl()</a>--Perform File Control Command<br>
</li>
<li><a href="open.htm">open()</a>--Open File</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 duplicates an open descriptor:</p>
<pre>
#include &lt;fcntl.h&gt;
#include &lt;unistd.h&gt;
#include &lt;sys/types.h&gt;
#include &lt;sys/stat.h&gt;
#include &lt;stdio.h&gt;
#include &lt;errno.h&gt;
void print_file_id(int file_descriptor) {
struct stat info;
if (fstat(file_descriptor, &amp;info) != 0)
fprintf(stderr, "stat() error for file_descriptor %d: %s\n",
strerror(errno));
else
printf("The file id of file_descriptor %d is %d\n",
file_descriptor,(int) info.st_ino);
}
main() {
int file_descriptor, file_descriptor2;
char fn[]="original.file";
/* create original file */
if((file_descriptor = creat(fn,S_IRUSR | S_IWUSR)) &lt; 0)
perror("creat() error");
/* generate a duplicate file descriptor of file_descriptor */
else {
if ((file_descriptor2 = dup(file_descriptor)) &lt; 0)
perror("dup() error");
/* print resulting information */
else {
print_file_id(file_descriptor);
print_file_id(file_descriptor2);
puts("The file descriptors are different but");
puts("they point to the same file.");
close(file_descriptor);
close(file_descriptor2);
}
unlink(fn);
}
}
</pre>
<p><strong>Output:</strong></p>
<pre>
The file id of file_descriptor 0 is 30
The file id of file_descriptor 3 is 30
The file descriptors are different but
they point to the same file.
</pre>
<br>
<hr>
API introduced: V3R1
<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>