symlink()--Make Symbolic Link

 #include <unistd.h>

 int symlink(const char *pname, const char *slink);  

The symlink() function creates the symbolic link named by slink with the value specified by pname. File access checking is not performed on the file pname, and the file need not exist. In addition, a symbolic link can cross file system boundaries.

If slink names a symbolic link, symlink() fails with the [EEXIST] error.

A symbolic link path name is resolved in the following manner:

• 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.
  
• 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.

  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.

• 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, rename() does not resolve a symbolic link when the symbolic link is the final component of either the new or old path name. However, open() does resolve a symbolic link when the link is the last component.
  
• 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.
  
• 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.

Any files and directories to which a symbolic link refers are checked for access permission.

symlink() 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.

Parameters

pname

(Input) A pointer to the null-terminated value of the symbolic link.

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.

See QlgSymlink--Make Symbolic Link (using NLS-enabled path name) for a description and an example of supplying the pname in any CCSID.

slink

(Input) A pointer to the null-terminated name of the symbolic link to be created.

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.

See QlgSymlink--Make Symbolic Link (using NLS-enabled path name) for a description and an example of supplying the slink in any CCSID.

Authorities

Note: Adopted authority is not used.

Authorization Required for symlink()

Return Value

0

symlink() was successful.

-1

symlink() was not successful. The errno global variable is set to indicate the error.

Error Conditions

If symlink() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

Error Messages

The following messages may be sent from this function:

Usage Notes

1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:
   • Where multiple threads exist in the job.
     
   • 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:
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • Independent ASP QSYS.LIB
     • QOPT
     • Network File System
     • QFileSvr.400
   
   
2. The following file systems do not support symlink():
   • QSYS.LIB
   • Independent ASP QSYS.LIB
   • QDLS
   • QOPT
   • QFileSvr.400
   • QNetWare
   • QNTC

Related Information

• The <unistd.h> file (see Header Files for UNIX-Type Functions)
  
• link()--Create Link to File
  
• QlgSymlink--Make Symbolic Link (using NLS-enabled path name)
  
• readlink()--Read Value of Symbolic Link
  
• unlink()--Remove Link to File

Example

See Code disclaimer information for information pertaining to code examples.

The following example uses symlink():

#include <stdio.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <stdlib.h>

main() {
  char fn[]="readlink.file";
  char sl[]="readlink.symlink";
  char buf[30];
  int  file_descriptor;

  if ((file_descriptor = creat(fn, S_IWUSR)) < 0)
    perror("creat() error");
  else {
    close(file_descriptor);
    if (symlink(fn, sl) != 0)
      perror("symlink() error");
    else {
      if (readlink(sl, buf, sizeof(buf)) < 0)
        perror("readlink() error");
      else printf("readlink() returned '%s' for '%s'\n", buf, sl);

      unlink(sl);
    }
    unlink(fn);
  }
}

Output:

readlink() returned 'readlink.file' for 'readlink.symlink'