# ln

## 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



           ln — link files
    


## SYNOPSIS



           ln **[** -fs**] [** -L|-P**]**_source_file target_file_
    
           ln **[** -fs**] [** -L|-P**]**_source_file_... _target_dir_
    


## DESCRIPTION



           In the first synopsis form, the _ln_ utility shall create a new
           directory entry (link) at the destination path specified by the
           _target_file_ operand. If the **-s** option is specified, a symbolic
           link shall be created for the file specified by the _source_file_
           operand. This first synopsis form shall be assumed when the final
           operand does not name an existing directory; if more than two
           operands are specified and the final is not an existing directory,
           an error shall result.
    
           In the second synopsis form, the _ln_ utility shall create a new
           directory entry (link), or if the **-s** option is specified a
           symbolic link, for each file specified by a _source_file_ operand,
           at a destination path in the existing directory named by
           _target_dir_.
    
           If the last operand specifies an existing file of a type not
           specified by the System Interfaces volume of POSIX.1‐2017, the
           behavior is implementation-defined.
    
           The corresponding destination path for each _source_file_ shall be
           the concatenation of the target directory pathname, a <slash>
           character if the target directory pathname did not end in a
           <slash>, and the last pathname component of the _source_file_.  The
           second synopsis form shall be assumed when the final operand names
           an existing directory.
    
           For each _source_file_ :
    
            1. If the destination path exists and was created by a previous
               step, it is unspecified whether _ln_ shall write a diagnostic
               message to standard error, do nothing more with the current
               _source_file_ , and go on to any remaining _source_file_ s; or will
               continue processing the current _source_file_.  If the
               destination path exists:
    
                a. If the **-f** option is not specified, _ln_ shall write a
                   diagnostic message to standard error, do nothing more with
                   the current _source_file_ , and go on to any remaining
                   _source_file_ s.
    
                b. If the destination path names the same directory entry as
                   the current _source_file ln_ shall write a diagnostic
                   message to standard error, do nothing more with the
                   current _source_file_ , and go on to any remaining
                   _source_file_ s _._
    
                c. Actions shall be performed equivalent to the _unlink_()
                   function defined in the System Interfaces volume of
                   POSIX.1‐2017, called using the destination path as the
                   _path_ argument. If this fails for any reason, _ln_ shall
                   write a diagnostic message to standard error, do nothing
                   more with the current _source_file_ , and go on to any
                   remaining _source_file_ s.
    
            2. If the **-s** option is specified, actions shall be performed
               equivalent to the _symlink_() function with _source_file_ as the
               _path1_ argument and the destination path as the _path2_ argument.
               The _ln_ utility shall do nothing more with _source_file_ and
               shall go on to any remaining files.
    
            3. If _source_file_ is a symbolic link:
    
                a. If the **-P** option is in effect, actions shall be performed
                   equivalent to the _linkat_() function with _source_file_ as
                   the _path1_ argument, the destination path as the _path2_
                   argument, AT_FDCWD as the _fd1_ and _fd2_ arguments, and zero
                   as the _flag_ argument.
    
                b. If the **-L** option is in effect, actions shall be performed
                   equivalent to the _linkat_() function with _source_file_ as
                   the _path1_ argument, the destination path as the _path2_
                   argument, AT_FDCWD as the _fd1_ and _fd2_ arguments, and
                   AT_SYMLINK_FOLLOW as the _flag_ argument.
    
               The _ln_ utility shall do nothing more with _source_file_ and
               shall go on to any remaining files.
    
            4. Actions shall be performed equivalent to the _link_() function
               defined in the System Interfaces volume of POSIX.1‐2017 using
               _source_file_ as the _path1_ argument, and the destination path as
               the _path2_ argument.
    


## OPTIONS



           The _ln_ utility shall conform to the Base Definitions volume of
           POSIX.1‐2017, _Section 12.2_ , _Utility Syntax Guidelines_.
    
           The following options shall be supported:
    
           **-f** Force existing destination pathnames to be removed to
                     allow the link.
    
           **-L** For each _source_file_ operand that names a file of type
                     symbolic link, create a (hard) link to the file
                     referenced by the symbolic link.
    
           **-P** For each _source_file_ operand that names a file of type
                     symbolic link, create a (hard) link to the symbolic link
                     itself.
    
           **-s** Create symbolic links instead of hard links. If the **-s**
                     option is specified, the **-L** and **-P** options shall be
                     silently ignored.
    
           Specifying more than one of the mutually-exclusive options **-L** and
           **-P** shall not be considered an error. The last option specified
           shall determine the behavior of the utility (unless the **-s** option
           causes it to be ignored).
    
           If the **-s** option is not specified and neither a **-L** nor a **-P** option
           is specified, it is implementation-defined which of the **-L** and **-P**
           options will be used as the default.
    


## OPERANDS



           The following operands shall be supported:
    
           _source_file_
                     A pathname of a file to be linked. If the **-s** option is
                     specified, no restrictions on the type of file or on its
                     existence shall be made. If the **-s** option is not
                     specified, whether a directory can be linked is
                     implementation-defined.
    
           _target_file_
                     The pathname of the new directory entry to be created.
    
           _target_dir_
                     A pathname of an existing directory in which the new
                     directory entries are created.
    


## STDIN



           Not used.
    


## INPUT FILES



           None.
    


## ENVIRONMENT VARIABLES



           The following environment variables shall affect the execution of
           _ln_ :
    
           _LANG_      Provide a default value for the internationalization
                     variables that are unset or null. (See the Base
                     Definitions volume of POSIX.1‐2017, _Section 8.2_ ,
                     _Internationalization Variables_ for the precedence of
                     internationalization variables used to determine the
                     values of locale categories.)
    
           _LC_ALL_    If set to a non-empty string value, override the values
                     of all the other internationalization variables.
    
           _LC_CTYPE_  Determine the locale for the interpretation of sequences
                     of bytes of text data as characters (for example,
                     single-byte as opposed to multi-byte characters in
                     arguments).
    
           _LC_MESSAGES_
                     Determine the locale that should be used to affect the
                     format and contents of diagnostic messages written to
                     standard error.
    
           _NLSPATH_   Determine the location of message catalogs for the
                     processing of _LC_MESSAGES_.
    


## ASYNCHRONOUS EVENTS



           Default.
    


## STDOUT



           Not used.
    


## STDERR



           The standard error shall be used only for diagnostic messages.
    


## OUTPUT FILES



           None.
    


## EXTENDED DESCRIPTION



           None.
    


## EXIT STATUS



           The following exit values shall be returned:
    
            0    All the specified files were linked successfully.
    
           >0    An error occurred.
    


## CONSEQUENCES OF ERRORS



           Default.
    
           _The following sections are informative._
    


## APPLICATION USAGE



           None.
    


## EXAMPLES



           None.
    


## RATIONALE



           The CONSEQUENCES OF ERRORS section does not require _ln_ **-f** _a b_ to
           remove _b_ if a subsequent link operation would fail.
    
           Some historic versions of _ln_ (including the one specified by the
           SVID) unlink the destination file, if it exists, by default. If
           the mode does not permit writing, these versions prompt for
           confirmation before attempting the unlink. In these versions the
           **-f** option causes _ln_ not to attempt to prompt for confirmation.
    
           This allows _ln_ to succeed in creating links when the target file
           already exists, even if the file itself is not writable (although
           the directory must be).  Early proposals specified this
           functionality.
    
           This volume of POSIX.1‐2017 does not allow the _ln_ utility to
           unlink existing destination paths by default for the following
           reasons:
    
            *  The _ln_ utility has historically been used to provide locking
               for shell applications, a usage that is incompatible with _ln_
               unlinking the destination path by default. There was no
               corresponding technical advantage to adding this
               functionality.
    
            *  This functionality gave _ln_ the ability to destroy the link
               structure of files, which changes the historical behavior of
               _ln_.
    
            *  This functionality is easily replicated with a combination of
               _rm_ and _ln_.
    
            *  It is not historical practice in many systems; BSD and BSD-
               derived systems do not support this behavior. Unfortunately,
               whichever behavior is selected can cause scripts written
               expecting the other behavior to fail.
    
            *  It is preferable that _ln_ perform in the same manner as the
               _link_() function, which does not permit the target to exist
               already.
    
           This volume of POSIX.1‐2017 retains the **-f** option to provide
           support for shell scripts depending on the SVID semantics. It
           seems likely that shell scripts would not be written to handle
           prompting by _ln_ and would therefore have specified the **-f** option.
    
           The **-f** option is an undocumented feature of many historical
           versions of the _ln_ utility, allowing linking to directories. These
           versions require modification.
    
           Early proposals of this volume of POSIX.1‐2017 also required a **-i**
           option, which behaved like the **-i** options in _cp_ and _mv_ , prompting
           for confirmation before unlinking existing files. This was not
           historical practice for the _ln_ utility and has been omitted.
    
           The **-L** and **-P** options allow for implementing both common behaviors
           of the _ln_ utility. Earlier versions of this standard did not
           specify these options and required the behavior now described for
           the **-L** option. Many systems by default or as an alternative
           provided a non-conforming _ln_ utility with the behavior now
           described for the **-P** option. Since applications could not rely on
           _ln_ following links in practice, the **-L** and **-P** options were added
           to specify the desired behavior for the application.
    
           The **-L** and **-P** options are ignored when **-s** is specified in order to
           allow an alias to be created to alter the default behavior when
           creating hard links (for example, _alias ln_ ='_ln_ **-L** ').  They serve
           no purpose when **-s** is specified, since _source_file_ is then just a
           string to be used as the contents of the created symbolic link and
           need not exist as a file.
    
           The specification ensures that _ln_ **a a** with or without the **-f**
           option will not unlink the file **a**.  Earlier versions of this
           standard were unclear in this case.
    


## FUTURE DIRECTIONS



           None.
    


* * *