# symlink

## NAME



           symlink, symlinkat - make a new name for a file
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <unistd.h>**
    
           **int symlink(const char ***_target_**, const char ***_linkpath_**);**
    
           **#include <fcntl.h>           **/* Definition of **AT_*** constants */
           **#include <unistd.h>**
    
           **int symlinkat(const char ***_target_**, int** _newdirfd_**, const char ***_linkpath_**);**
    
       Feature Test Macro Requirements for glibc (see
       feature_test_macros(7)):
    
           **symlink**():
               _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
                   || /* glibc <= 2.19: */ _BSD_SOURCE
    
           **symlinkat**():
               Since glibc 2.10:
                   _POSIX_C_SOURCE >= 200809L
               Before glibc 2.10:
                   _ATFILE_SOURCE
    


## DESCRIPTION



           **symlink**() creates a symbolic link named _linkpath_ which contains
           the string _target_.
    
           Symbolic links are interpreted at run time as if the contents of
           the link had been substituted into the path being followed to find
           a file or directory.
    
           Symbolic links may contain _.._  path components, which (if used at
           the start of the link) refer to the parent directories of that in
           which the link resides.
    
           A symbolic link (also known as a soft link) may point to an
           existing file or to a nonexistent one; the latter case is known as
           a dangling link.
    
           The permissions of a symbolic link are irrelevant; the ownership
           is ignored when following the link (except when the
           _protected_symlinks_ feature is enabled, as explained in proc(5)),
           but is checked when removal or renaming of the link is requested
           and the link is in a directory with the sticky bit (**S_ISVTX**) set.
    
           If _linkpath_ exists, it will _not_ be overwritten.
    
       **symlinkat()**
           The **symlinkat**() system call operates in exactly the same way as
           **symlink**(), except for the differences described here.
    
           If the pathname given in _linkpath_ is relative, then it is
           interpreted relative to the directory referred to by the file
           descriptor _newdirfd_ (rather than relative to the current working
           directory of the calling process, as is done by **symlink**() for a
           relative pathname).
    
           If _linkpath_ is relative and _newdirfd_ is the special value
           **AT_FDCWD** , then _linkpath_ is interpreted relative to the current
           working directory of the calling process (like **symlink**()).
    
           If _linkpath_ is absolute, then _newdirfd_ is ignored.
    
           See openat(2) for an explanation of the need for **symlinkat**().
    


## RETURN VALUE



           On success, zero is returned.  On error, -1 is returned, and _errno_
           is set to indicate the error.
    


## ERRORS



           **EACCES** Write access to the directory containing _linkpath_ is
                  denied, or one of the directories in the path prefix of
                  _linkpath_ did not allow search permission.  (See also
                  path_resolution(7).)
    
           **EBADF**(**symlinkat**()) _linkpath_ is relative but _newdirfd_ is neither
                  **AT_FDCWD** nor a valid file descriptor.
    
           **EDQUOT** The user's quota of resources on the filesystem has been
                  exhausted.  The resources could be inodes or disk blocks,
                  depending on the filesystem implementation.
    
           **EEXIST** _linkpath_ already exists.
    
           **EFAULT** _target_ or _linkpath_ points outside your accessible address
                  space.
    
           **EIO** An I/O error occurred.
    
           **ELOOP** Too many symbolic links were encountered in resolving
                  _linkpath_.
    
           **ENAMETOOLONG**
                  _target_ or _linkpath_ was too long.
    
           **ENOENT** A directory component in _linkpath_ does not exist or is a
                  dangling symbolic link, or _target_ or _linkpath_ is an empty
                  string.
    
           **ENOENT**(**symlinkat**()) _linkpath_ is a relative pathname and _newdirfd_
                  refers to a directory that has been deleted.
    
           **ENOMEM** Insufficient kernel memory was available.
    
           **ENOSPC** The device containing the file has no room for the new
                  directory entry.
    
           **ENOTDIR**
                  A component used as a directory in _linkpath_ is not, in
                  fact, a directory.
    
           **ENOTDIR**
                  (**symlinkat**()) _linkpath_ is relative and _newdirfd_ is a file
                  descriptor referring to a file other than a directory.
    
           **EPERM** The filesystem containing _linkpath_ does not support the
                  creation of symbolic links.
    
           **EROFS** _linkpath_ is on a read-only filesystem.
    


## STANDARDS



           POSIX.1-2008.
    


## NOTES



           No checking of _target_ is done.
    
           Deleting the name referred to by a symbolic link will actually
           delete the file (unless it also has other hard links).  If this
           behavior is not desired, use link(2).
    


* * *