symlink()

create a symbolic link 

Function

SYNOPSIS

#include <unistd.h>

int symlink(const char *name1, const char *name2);

DESCRIPTION

The symlink() function creates a symbolic link from the file name2 to the file name1. Either name may be an arbitrary path name, the files need not be on the same file system, and name1 may be non-existent.

The file to which the symbolic points is used when an open() operation is performed on the link. Using stat() on the symbolic link returns the linked-to file, while lstat() returns information about the link itself. To avoid confusion in programs, the readlink() function can be used to read the contents of a symbolic link.

If the file named by name2 does not exist, it is created. The permission mode of name2 is 777.

PARAMETERS

name1 

Is the file that the symbolic link is to point to.

name2 

Is the name of symbolic link to be created.

RETURN VALUES

On success, symlink() returns 0. On failure, it returns -1 and sets errno to one of the following values:

EACCES 

Search permission is denied on a component of name2.

EEXIST 

The file referenced by name2 already exists.

EFAULT 

name1 or name2 is an invalid pointer.

EINVAL 

name1 or name2 contains an invalid character.

ENAMETOOLONG 

The length of name1 or name2 exceeds PATH_MAX, or a path name component is longer than NAME_MAX.

ENOENT 

name1 or name2 points to an empty string.

ENOSPC 

The new symbolic link cannot be created because no space is left on the file system which is to contain the link.

ENOTDIR 

A component of name2 is not a directory.

EROFS 

The new symbolic link would reside on a read-only file system.

CONFORMANCE

UNIX 98, with exceptions.

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

Symbolic links are implemented in two different ways:

The older implementation was only supported on 8.1/2012R2/2016/2019/2022 on local NTFS-5 file systems. On all other supported platforms, symlink() and readlink() fail. In addition, symbolic links can only point to directories and not to an ordinary file.

The newer implmentation works on Windows 8.1/2012R2/10/2016/2019/11/2022 and only when the calling user account can assert the SeCreateSymbolicLinkPrivilege privilege. By default this privilige is held only by administrators but may be assigned to any user using standard windows tools or the PTC MKS Toolkit priv. When it cannot be asserted, symlink() falls back to the 8.1/2012R2/2016/2019/2022 implementation.

In this latter case, the underlying Win32 API CreateSymbolicLink() needs to know of the target of the symbolic link is a file or directory. No action is needed if the target name1 exists as the type is derived from the existing target file. It is legal to create a symbolic link that points to a file or directory that has yet to be created. In that case symlink() needs to know what default action to take. This infomation is taken from _NutConf(_NC_GET_DFLT_SYMLINK_IS_DIRECTORY, &isDirectory); which may be set with _NutConf(_NC_SET_DFLT_SYMLINK_IS_DIRECTORY, TRUE) or _NutConf(_NC_SET_DFLT_SYMLINK_IS_DIRECTORY, FALSE) and defaults to FALSE such that file symbolic links are created for non-existant targets.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Functions:
_NutConf(), chown(), lchown(), link(), lstat(), open(), readlink(), stat(), unlink()

PTC MKS Toolkit 10.4 Documentation Build 39.