symlink() — Create a symbolic link to a path name

Standards

Standards / Extensions	C or C++	Dependencies
POSIX.1a XPG4.2 Single UNIX Specification, Version 3	both

Format

#define _POSIX1_SOURCE 2
#include <unistd.h>

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

General description

Creates the symbolic link named by slink with the file specified by pathname. File access checking is not performed on the file pathname, and the file need not exist. In addition, a symbolic link can cross file system boundaries.

A symbolic link path name is resolved in this fashion:

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 process root directory.
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 it appears as the final component of either the new or old path name. However, open does resolve a symbolic link when it appears as 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.

Because the mode of a symbolic link cannot be changed, its mode is ignored during the lookup process. Any files and directories to which a symbolic link refers are checked for access permission.

Returned value

If successful, symlink() returns 0.

If unsuccessful, symlink() returns -1, does not affect any file it names, and sets errno to one of the following values:

Error Code

Description

EACCES

A component of the slink path prefix denies search permission, or write permission is denied in the parent directory of the symbolic link to be created.

EEXIST

The file named by slink already exists.

EINVAL

This may be returned for either of these reasons:

There is a NULL character in pathname.
slink has a slash as its last component, which indicates that the preceding component will be a directory. A symbolic link cannot be a directory.

EIO

Added for XPG4.2: An I/O error occurred while reading from the file system.

ELOOP

A loop exists in symbolic links. This error is issued if more than POSIX_SYMLOOP symbolic links are encountered during resolution of the slink argument.

ENAMETOOLONG

pathname is longer than PATH_MAX characters, or some component of pathname is longer than NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length of the path name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and NAME_MAX values can be determined with pathconf().

ENOENT

Added for XPG4.2: A component of slink does not name an existing file or slink is an empty string.

ENOSPC

The new symbolic link cannot be created because there is no space left on the file system that will contain the symbolic link.

ENOTDIR

A component of the path prefix of slink is not a directory.

EROFS

The file slink cannot reside on a read-only system.

Example

/* This example works only under z/OS XL C, not z/OS XL C++  */
#define _POSIX1_SOURCE 2
#include <fcntl.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>

main() {
  char fn[]="test.file";
  char sln[]="test.symlink";
  int fd;

  if ((fd = creat(fn, S_IWUSR)) < 0)
    perror("creat() error");
  else {
    close(fd);
    puts("before symlink()");
    system("ls -il test.*");
    if (symlink(fn, sln) != 0) {
      perror("symlink() error");
      unlink(fn);
    }
    else {
      puts("after symlink()");
      system("ls -il test.*");
      unlink(fn);
      puts("after first unlink()");
      system("ls -il test.*");
      unlink(sln);
    }
  }
}

Output

before symlink()
 4030 --w-------   1 MVSUSR1  SYS1     0 Apr 20 13:57 test.file

after symlink()
 4030 --w-------   1 MVSUSR1  SYS1     0 Apr 20 13:57 test.file
 4031 l---------   1 MVSUSR1  SYS1     9 Apr 20 13:57 test.symlink -> test.file
after first unlink()
 4031 l---------   1 MVSUSR1  SYS1     9 Apr 20 13:57 test.symlink -> test.file