friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
8826eae394
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/symlink.htm

643 lines
14 KiB
HTML
Raw Blame History

<!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>symlink()--Make Symbolic Link</title>
<!-- 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. -->
<!-- Begin Header Records ========================================== -->
<!-- file cleaned -->
<!-- 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 -->
<!-- 020618 EMIG: updated for NFS threadsafety, V5R3 -->
<!-- 0206?? JET This file has undergone html cleanup -->
<!-- 020719 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 -->
<!-- 050407 JTROUS: fix enums, no change flag, V5R4 -->
<!--End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>symlink()--Make Symbolic Link</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;unistd.h&gt;
int symlink(const char <em>*pname</em>, const char <em>*slink</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>symlink()</strong> function creates the symbolic link named by
<em>slink</em> with the value specified by <em>pname</em>. File access checking
is not performed on the file <em>pname</em>, and the file need not exist. In
addition, a symbolic link can cross file system boundaries.</p>
<p>If <em>slink</em> names a symbolic link, <strong>symlink()</strong> fails
with the [EEXIST] error.</p>
<p>A symbolic link path name is resolved in the following manner:</p>
<ul>
<li>When a component of a path name refers to a symbolic link rather than to a
directory, the path name contained in the symbolic link is resolved.<br>
</li>
<li>If the path name in the symbolic link begins with / (slash), the symbolic
link path name is resolved relative to the root directory for the job.
<p>If the path name in the symbolic link does not start with / (slash), the
symbolic link path name is resolved relative to the directory that contains the
symbolic link.</p>
</li>
<li>If the symbolic link is the last component of a path name, it may or may
not be resolved. Resolution depends on the function using the path name. For
example, <strong>rename()</strong> does not resolve a symbolic link when the
symbolic link is the final component of either the new or old path name.
However, <strong>open()</strong> does resolve a symbolic link when the link is
the last component.<br>
</li>
<li>If the symbolic link is not the last component of the original path name,
remaining components of the original path name are resolved relative to the
symbolic link.<br>
</li>
<li>When a / (slash) is the last component of a path name and it is preceded by
a symbolic link, the symbolic link is always resolved.</li>
</ul>
<p>Any files and directories to which a symbolic link refers are checked for
access permission.</p>
<p><strong>symlink()</strong> sets the access, change, modification, and
creation times for the new symbolic link. It also sets the change and
modification times for the directory that contains the new symbolic link.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>pname</em></strong></dt>
<dd>(Input) A pointer to the null-terminated value of the symbolic link.
<p>The value of the symbolic link 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>See <a href="symlinku.htm">QlgSymlink--Make Symbolic Link (using NLS-enabled
path name)</a> for a description and an example of supplying the <em>pname</em>
in any CCSID.</p>
<br>
</dd>
<dt><strong><em>slink</em></strong></dt>
<dd>(Input) A pointer to the null-terminated name of the symbolic link to be
created.
<p>This parameter is assumed to be represented in the CCSID, language, and
country or region 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>See <a href="symlinku.htm">QlgSymlink--Make Symbolic Link (using NLS-enabled
path name)</a> for a description and an example of supplying the <em>slink</em>
in any CCSID.</p>
</dd>
</dl>
<br>
<h3>Authorities</h3>
<p><strong>Note:</strong> Adopted authority is not used.</p>
<p><strong><a name="TBLASYMLNK">Authorization Required for
symlink()</a></strong></p>
<table border>
<!-- cols="60 20 20" -->
<tr>
<th align="left" valign="bottom">Object Referred to</th>
<th align="left" valign="bottom">Authority Required</th>
<th align="left" valign="bottom">errno</th>
</tr>
<tr>
<td align="left" valign="top" width="90%">Each directory in the path name
preceding the object to be created</td>
<td align="left" valign="top" width="5%">*X</td>
<td align="left" valign="top" width="5%">EACCES</td>
</tr>
<tr>
<td align="left" valign="top" width="90%">Parent directory of object to be
created</td>
<td align="left" valign="top" width="5%">*WX</td>
<td align="left" valign="top" width="5%">EACCES</td>
</tr>
</table>
<br>
<br>
<h3>Return Value</h3>
<dl compact>
<dt><em>0</em></dt>
<dd><strong>symlink()</strong> was successful.</dd>
<dt><em>-1</em></dt>
<dd><strong>symlink()</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>symlink()</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#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#EISDIR">EISDIR</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#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#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>
<br>
<br>
<h3>Error Messages</h3>
<p>The following messages may be sent from this function:</p>
<table width="100%" cellpadding="5">
<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:
<ul>
<li>Where multiple threads exist in the job.<br>
</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:
<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>Network File System</li>
<li>QFileSvr.400</li>
</ul>
</li>
</ul>
<br>
</li>
<li>The following file systems do not support <strong>symlink()</strong>:</p>
<ul>
<li>QSYS.LIB</li>
<li>Independent ASP QSYS.LIB</li>
<li>QDLS</li>
<li>QOPT</li>
<li>QFileSvr.400</li>
<li>QNetWare</li>
<li>QNTC</li>
</ul>
</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="link.htm">link()</a>--Create Link to File<br>
</li>
<li><a href="symlinku.htm">QlgSymlink</a>--Make Symbolic Link (using
NLS-enabled path name)<br>
</li>
<li><a href="readlink.htm">readlink()</a>--Read Value of Symbolic Link<br>
</li>
<li><a href="unlink.htm">unlink()</a>--Remove Link to 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 uses <strong>symlink()</strong>:</p>
<pre>
#include &lt;stdio.h&gt;
#include &lt;unistd.h&gt;
#include &lt;sys/types.h&gt;
#include &lt;sys/stat.h&gt;
#include &lt;fcntl.h&gt;
#include &lt;stdlib.h&gt;
main() {
char fn[]="readlink.file";
char sl[]="readlink.symlink";
char buf[30];
int file_descriptor;
if ((file_descriptor = creat(fn, S_IWUSR)) &lt; 0)
perror("creat() error");
else {
close(file_descriptor);
if (symlink(fn, sl) != 0)
perror("symlink() error");
else {
if (readlink(sl, buf, sizeof(buf)) &lt; 0)
perror("readlink() error");
else printf("readlink() returned '%s' for '%s'\n", buf, sl);
unlink(sl);
}
unlink(fn);
}
}
</pre>
<p><strong>Output:</strong></p>
<pre>
readlink() returned 'readlink.file' for 'readlink.symlink'
</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>
Reference in New Issue View Git Blame Copy Permalink