Technical Reference: Base Operating System and Extensions , Volume 2

symlink Subroutine

Syntax

#include <unistd.h>

int symlink ( Path1, Path2) const char *Path1; const char *Path2;

Description

The symlink subroutine creates a symbolic link with the file named by the Path2 parameter, which refers to the file named by the Path1 parameter.

As with a hard link (described in the link subroutine), a symbolic link allows a file to have multiple names. The presence of a hard link guarantees the existence of a file, even after the original name has been removed. A symbolic link provides no such assurance. In fact, the file named by the Path1 parameter need not exist when the link is created. In addition, a symbolic link can cross file system boundaries.

When a component of a path name refers to a symbolic link rather than a directory, the path name contained in the symbolic link is resolved. If the path name in the symbolic link starts with a / (slash), it is resolved relative to the root directory of the process. If the path name in the symbolic link does not start with / (slash), it is resolved relative to the directory that contains the symbolic link.

If the symbolic link is not the last component of the original path name, remaining components of the original path name are resolved from the symbolic-link point.

If the last component of the path name supplied to a subroutine refers to a symbolic link, the symbolic link path name may or may not be traversed. Most subroutines always traverse the link; for example, the chmod, chown, link, and open subroutines. The statx subroutine takes an argument that determines whether the link is to be traversed.

The following subroutines refer only to the symbolic link itself, rather than to the object to which the link refers:

mkdir
	Fails with the EEXIST error code if the target is a symbolic link.
mknod
	Fails with the EEXIST error code if a symbolic link exists with the same name as the target file as specified by the Path parameter in the mknod and mkfifo subroutines.
open
	Fails with EEXIST error code when the O_CREAT and O_EXCL flags are specified and a symbolic link exists for the path name specified.
readlink (readlink Subroutine)
	Applies only to symbolic links.
rename (rename Subroutine)
	Renames the symbolic link if the file to be renamed (the FromPath parameter for the rename subroutine) is a symbolic link. If the new name (the ToPath parameter for the rename subroutine) refers to an existing symbolic link, the symbolic link is destroyed.
rmdir (rmdir Subroutine)
	Fails with the ENOTDIR error code if the target is a symbolic link.
symlink	Running this subroutine causes an error if a symbolic link named by the Path2 parameter already exists. A symbolic link can be created that refers to another symbolic link; that is, the Path1 parameter can refer to a symbolic link.
unlink (unlink Subroutine)
	Removes the symbolic link.

Since the mode of a symbolic link cannot be changed, its mode is ignored during the lookup process. Any files and directories referenced by a symbolic link are checked for access normally.

Parameters

Path1	Specifies the contents of the Path2 symbolic link. This value is a null-terminated string representing the object to which the symbolic link will point. Path1 cannot be the null value and cannot be more than PATH_MAX characters long. PATH_MAX is defined in the limits.h file.
Path2	Names the symbolic link to be created.

Return Values

Upon successful completion, the symlink subroutine returns a value of 0. If the symlink subroutine fails, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The symlink subroutine fails if one or more of the following are true:

EEXIST	Path2 already exists.
EACCES	The requested operation requires writing in a directory with a mode that denies write permission.
EROFS	The requested operation requires writing in a directory on a read-only file system.
ENOSPC	The directory in which the entry for the symbolic link is being placed cannot be extended because there is no space left on the file system containing the directory.
EDQUOT	The directory in which the entry for the new symbolic link is being placed cannot be extended or disk blocks could not be allocated for the symbolic link because the user's or group's quota of disk blocks on the file system containing the directory has been exhausted.

The symlink subroutine can be unsuccessful for other reasons. See "Base Operating System Error Codes For Services That Require Path-Name Resolution" for a list of additional errors.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The chown, fchown, chownx, or fchown subroutine, link subroutine, mkdir subroutine, mknod subroutine, openx, open, or create subroutine, readlink (readlink Subroutine) subroutine, rename (rename Subroutine) subroutine, rmdir (rmdir Subroutine) subroutine, statx (statx, stat, lstat, fstatx, fstat, fullstat, ffullstat, stat64, lstat64, or fstat64 Subroutine) subroutine, unlink (unlink Subroutine) subroutine.

The ln command.

The limits.h file.

Files, Directories, and File Systems for Programmers in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.