LN(1) General Commands Manual LN(1)

NAME

ln — link files

SYNOPSIS

`ln`	[`-f`] `source_file` `target_file`

`ln`	[`-f`] `source_file` `...` `target_dir`

DESCRIPTION

In the first synopsis form, the ln utility shall create a new directory entry (link) for the file specified by the source_file operand, at the destination path specified by the target_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 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 POSIX. 1 {8}, 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, 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:

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_files. (b) Actions shall be performed equivalent to the POSIX. 1 {8} unlink() function, called using destination 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_files.
Actions shall be performed equivalent to the POSIX. 1 {8} link() function using source_file as the path1 argument, and the destination path as the path2 argument.

OPTIONS

The ln utility shall conform to the utility argument syntax guidelines described in 2.10.2. The following option shall be supported by the implementation:

-f: Force existing destination pathnames to be removed to allow the link.

OPERANDS

The following operands shall be supported by the implementation:

source_file: A pathname of a file to be linked. This can be a regular or special file; 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 to be created.

STANDARD INPUT

None.

INPUT FILES

None.

ENVIRONMENT VARIABLES

The following environment variables shall affect the execution of ln:

LANG: This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_ ) do not specify a locale. See 2.6.
LC_ALL: This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_.
LC_CTYPE: This variable shall determine the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments).
LC_MESSAGES: This variable shall determine the language in which messages should be written.

ASYNCHRONOUS EVENTS

Default.

STANDARD OUTPUT

None.

STANDARD ERROR

Used only for diagnostic messages.

OUTPUT FILES

None.

EXTENDED DESCRIPTION

None.

EXIT STATUS

The ln utility shall exit with one of the following values:

0: All the specified files were linked successfully.
>0: An error occurred.

CONSEQUENCES OF ERRORS

Default.

The following section is informative.

RATIONALE

EXAMPLES

None.

HISTORY OF DECISIONS MADE

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 will prompt for confirmation before attempting the unlink. In these versions the −f option causes ln to not 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). Previous versions of this draft specified this functionality. This draft does not allow the ln utility to unlink existing destination paths by default for the following reasons:

The ln utility has traditionally 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 already exist.

This standard 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. It should also be noted that −f is an undocumented feature of many historical versions of the ln utility, allowing linking to directories. These versions will require modification. Previous drafts of this standard also required an −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 deleted from this version. Although symbolic links are not part of the standard, the −s option should be used only for the traditional purpose of creating symbolic links.

September 1991 posix.fail