# link

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           link, linkat — link one file to another file
    


## SYNOPSIS



           #include <unistd.h>
    
           int link(const char *_path1_ , const char *_path2_);
    
           #include <fcntl.h>
    
           int linkat(int _fd1_ , const char *_path1_ , int _fd2_ ,
               const char *_path2_ , int _flag_);
    


## DESCRIPTION



           The _link_() function shall create a new link (directory entry) for
           the existing file, _path1_.
    
           The _path1_ argument points to a pathname naming an existing file.
           The _path2_ argument points to a pathname naming the new directory
           entry to be created. The _link_() function shall atomically create a
           new link for the existing file and the link count of the file
           shall be incremented by one.
    
           If _path1_ names a directory, _link_() shall fail unless the process
           has appropriate privileges and the implementation supports using
           _link_() on directories.
    
           If _path1_ names a symbolic link, it is implementation-defined
           whether _link_() follows the symbolic link, or creates a new link to
           the symbolic link itself.
    
           Upon successful completion, _link_() shall mark for update the last
           file status change timestamp of the file. Also, the last data
           modification and last file status change timestamps of the
           directory that contains the new entry shall be marked for update.
    
           If _link_() fails, no link shall be created and the link count of
           the file shall remain unchanged.
    
           The implementation may require that the calling process has
           permission to access the existing file.
    
           The _linkat_() function shall be equivalent to the _link_() function
           except that symbolic links shall be handled as specified by the
           value of _flag_ (see below) and except in the case where either
           _path1_ or _path2_ or both are relative paths. In this case a relative
           path _path1_ is interpreted relative to the directory associated
           with the file descriptor _fd1_ instead of the current working
           directory and similarly for _path2_ and the file descriptor _fd2_.  If
           the access mode of the open file description associated with the
           file descriptor is not O_SEARCH, the function shall check whether
           directory searches are permitted using the current permissions of
           the directory underlying the file descriptor. If the access mode
           is O_SEARCH, the function shall not perform the check.
    
           Values for _flag_ are constructed by a bitwise-inclusive OR of flags
           from the following list, defined in _< fcntl.h>_:
    
           AT_SYMLINK_FOLLOW
                 If _path1_ names a symbolic link, a new link for the target of
                 the symbolic link is created.
    
           If _linkat_() is passed the special value AT_FDCWD in the _fd1_ or _fd2_
           parameter, the current working directory shall be used for the
           respective _path_ argument. If both _fd1_ and _fd2_ have value AT_FDCWD,
           the behavior shall be identical to a call to _link_(), except that
           symbolic links shall be handled as specified by the value of _flag_.
    
           If the AT_SYMLINK_FOLLOW flag is clear in the _flag_ argument and
           the _path1_ argument names a symbolic link, a new link is created
           for the symbolic link _path1_ and not its target.
    


## RETURN VALUE



           Upon successful completion, these functions shall return 0.
           Otherwise, these functions shall return -1 and set _errno_ to
           indicate the error.
    


## ERRORS



           These functions shall fail if:
    
           **EACCES** A component of either path prefix denies search permission,
                  or the requested link requires writing in a directory that
                  denies write permission, or the calling process does not
                  have permission to access the existing file and this is
                  required by the implementation.
    
           **EEXIST** The _path2_ argument resolves to an existing directory entry
                  or refers to a symbolic link.
    
           **ELOOP** A loop exists in symbolic links encountered during
                  resolution of the _path1_ or _path2_ argument.
    
           **EMLINK** The number of links to the file named by _path1_ would exceed
                  {LINK_MAX}.
    
           **ENAMETOOLONG**
                  The length of a component of a pathname is longer than
                  {NAME_MAX}.
    
           **ENOENT** A component of either path prefix does not exist; the file
                  named by _path1_ does not exist; or _path1_ or _path2_ points to
                  an empty string.
    
           **ENOENT** or **ENOTDIR**
                  The _path1_ argument names an existing non-directory file,
                  and the _path2_ argument contains at least one non-<slash>
                  character and ends with one or more trailing <slash>
                  characters. If _path2_ without the trailing <slash>
                  characters would name an existing file, an **[ENOENT]** error
                  shall not occur.
    
           **ENOSPC** The directory to contain the link cannot be extended.
    
           **ENOTDIR**
                  A component of either path prefix names an existing file
                  that is neither a directory nor a symbolic link to a
                  directory, or the _path1_ argument contains at least one
                  non-<slash> character and ends with one or more trailing
                  <slash> characters and the last pathname component names an
                  existing file that is neither a directory nor a symbolic
                  link to a directory, or the _path1_ argument names an
                  existing non-directory file and the _path2_ argument names a
                  nonexistent file, contains at least one non-<slash>
                  character, and ends with one or more trailing <slash>
                  characters.
    
           **EPERM** The file named by _path1_ is a directory and either the
                  calling process does not have appropriate privileges or the
                  implementation prohibits using _link_() on directories.
    
           **EROFS** The requested link requires writing in a directory on a
                  read-only file system.
    
           **EXDEV** The link named by _path2_ and the file named by _path1_ are on
                  different file systems and the implementation does not
                  support links between file systems.
    
           **EXDEV** _path1_ refers to a named STREAM.
    
           The _linkat_() function shall fail if:
    
           **EACCES** The access mode of the open file description associated
                  with _fd1_ or _fd2_ is not O_SEARCH and the permissions of the
                  directory underlying _fd1_ or _fd2_ , respectively, do not
                  permit directory searches.
    
           **EBADF** The _path1_ or _path2_ argument does not specify an absolute
                  path and the _fd1_ or _fd2_ argument, respectively, is neither
                  AT_FDCWD nor a valid file descriptor open for reading or
                  searching.
    
           **ENOTDIR**
                  The _path1_ or _path2_ argument is not an absolute path and _fd1_
                  or _fd2_ , respectively, is a file descriptor associated with
                  a non-directory file.
    
           These functions may fail if:
    
           **ELOOP** More than {SYMLOOP_MAX} symbolic links were encountered
                  during resolution of the _path1_ or _path2_ argument.
    
           **ENAMETOOLONG**
                  The length of a pathname exceeds {PATH_MAX}, or pathname
                  resolution of a symbolic link produced an intermediate
                  result with a length that exceeds {PATH_MAX}.
    
           The _linkat_() function may fail if:
    
           **EINVAL** The value of the _flag_ argument is not valid.
    
           _The following sections are informative._
    


## EXAMPLES



       **Creating a Link to a File**
           The following example shows how to create a link to a file named
           **/home/cnd/mod1** by creating a new directory entry named
           **/modules/pass1**.
    
               #include <unistd.h>
    
               char *path1 = "/home/cnd/mod1";
               char *path2 = "/modules/pass1";
               int   status;
               ...
               status = link (path1, path2);
    
       **Creating a Link to a File Within a Program**
           In the following program example, the _link_() function links the
           **/etc/passwd** file (defined as **PASSWDFILE**) to a file named
           **/etc/opasswd**(defined as **SAVEFILE**), which is used to save the
           current password file. Then, after removing the current password
           file (defined as **PASSWDFILE**), the new password file is saved as
           the current password file using the _link_() function again.
    
               #include <unistd.h>
    
               #define LOCKFILE "/etc/ptmp"
               #define PASSWDFILE "/etc/passwd"
               #define SAVEFILE "/etc/opasswd"
               ...
               /* Save current password file */
               link (PASSWDFILE, SAVEFILE);
    
               /* Remove current password file. */
               unlink (PASSWDFILE);
    
               /* Save new password file as current password file. */
               link (LOCKFILE,PASSWDFILE);
    


## APPLICATION USAGE



           Some implementations do allow links between file systems.
    
           If _path1_ refers to a symbolic link, application developers should
           use _linkat_() with appropriate flags to select whether or not the
           symbolic link should be resolved.
    


## RATIONALE



           Linking to a directory is restricted to the superuser in most
           historical implementations because this capability may produce
           loops in the file hierarchy or otherwise corrupt the file system.
           This volume of POSIX.1‐2017 continues that philosophy by
           prohibiting _link_() and _unlink_() from doing this. Other functions
           could do it if the implementor designed such an extension.
    
           Some historical implementations allow linking of files on
           different file systems. Wording was added to explicitly allow this
           optional behavior.
    
           The exception for cross-file system links is intended to apply
           only to links that are programmatically indistinguishable from
           ``hard'' links.
    
           The purpose of the _linkat_() function is to link files in
           directories other than the current working directory without
           exposure to race conditions. Any part of the path of a file could
           be changed in parallel to a call to _link_(), resulting in
           unspecified behavior. By opening a file descriptor for the
           directory of both the existing file and the target location and
           using the _linkat_() function it can be guaranteed that the both
           filenames are in the desired directories.
    
           The AT_SYMLINK_FOLLOW flag allows for implementing both common
           behaviors of the _link_() function. The POSIX specification requires
           that if _path1_ is a symbolic link, a new link for the target of the
           symbolic link is created. Many systems by default or as an
           alternative provide a mechanism to avoid the implicit symbolic
           link lookup and create a new link for the symbolic link itself.
    
           Earlier versions of this standard specified only the _link_()
           function, and required it to behave like _linkat_() with the
           AT_SYMLINK_FOLLOW flag. However, historical practice from SVR4 and
           Linux kernels had _link_() behaving like _linkat_() with no flags, and
           many systems that attempted to provide a conforming _link_()
           function did so in a way that was rarely used, and when it was
           used did not conform to the standard (e.g., by not being atomic,
           or by dereferencing the symbolic link incorrectly). Since
           applications could not rely on _link_() following links in practice,
           the _linkat_() function was added taking a flag to specify the
           desired behavior for the application.
    


## FUTURE DIRECTIONS



           None.
    


* * *