coreutils: ln invocation
1
1 12.2 ‘ln’: Make links between files
1 ===================================
1
1 ‘ln’ makes links between files. By default, it makes hard links; with
1 the ‘-s’ option, it makes symbolic (or “soft”) links. Synopses:
1
1 ln [OPTION]... [-T] TARGET LINKNAME
1 ln [OPTION]... TARGET
1 ln [OPTION]... TARGET... DIRECTORY
1 ln [OPTION]... -t DIRECTORY TARGET...
1
1 • If two file names are given, ‘ln’ creates a link to the first file
1 from the second.
1
1 • If one TARGET is given, ‘ln’ creates a link to that file in the
1 current directory.
1
1 • If the ‘--target-directory’ (‘-t’) option is given, or failing that
1 if the last file is a directory and the ‘--no-target-directory’
1 (‘-T’) option is not given, ‘ln’ creates a link to each TARGET file
1 in the specified directory, using the TARGETs’ names.
1
1 Normally ‘ln’ does not replace existing files. Use the ‘--force’
1 (‘-f’) option to replace them unconditionally, the ‘--interactive’
1 (‘-i’) option to replace them conditionally, and the ‘--backup’ (‘-b’)
1 option to rename them. Unless the ‘--backup’ (‘-b’) option is used
1 there is no brief moment when the destination does not exist; this is an
1 extension to POSIX.
1
1 A “hard link” is another name for an existing file; the link and the
1 original are indistinguishable. Technically speaking, they share the
1 same inode, and the inode contains all the information about a
1 file—indeed, it is not incorrect to say that the inode _is_ the file.
1 Most systems prohibit making a hard link to a directory; on those where
1 it is allowed, only the super-user can do so (and with caution, since
1 creating a cycle will cause problems to many other utilities). Hard
1 links cannot cross file system boundaries. (These restrictions are not
1 mandated by POSIX, however.)
1
1 “Symbolic links” (“symlinks” for short), on the other hand, are a
1 special file type (which not all kernels support: System V release 3
1 (and older) systems lack symlinks) in which the link file actually
1 refers to a different file, by name. When most operations (opening,
1 reading, writing, and so on) are passed the symbolic link file, the
1 kernel automatically “dereferences” the link and operates on the target
1 of the link. But some operations (e.g., removing) work on the link file
1 itself, rather than on its target. The owner and group of a symlink are
1 not significant to file access performed through the link, but do have
1 implications on deleting a symbolic link from a directory with the
1 restricted deletion bit set. On the GNU system, the mode of a symlink
1 has no significance and cannot be changed, but on some BSD systems, the
1 mode can be changed and will affect whether the symlink will be
1 traversed in file name resolution. ⇒(libc)Symbolic Links.
1
1 Symbolic links can contain arbitrary strings; a “dangling symlink”
1 occurs when the string in the symlink does not resolve to a file. There
1 are no restrictions against creating dangling symbolic links. There are
1 trade-offs to using absolute or relative symlinks. An absolute symlink
1 always points to the same file, even if the directory containing the
1 link is moved. However, if the symlink is visible from more than one
1 machine (such as on a networked file system), the file pointed to might
1 not always be the same. A relative symbolic link is resolved in
1 relation to the directory that contains the link, and is often useful in
1 referring to files on the same device without regards to what name that
1 device is mounted on when accessed via networked machines.
1
1 When creating a relative symlink in a different location than the
1 current directory, the resolution of the symlink will be different than
1 the resolution of the same string from the current directory.
1 Therefore, many users prefer to first change directories to the location
1 where the relative symlink will be created, so that tab-completion or
1 other file resolution will find the same target as what will be placed
1 in the symlink.
1
11 The program accepts the following options. Also see ⇒Common
options.
1
1 ‘-b’
1 ‘--backup[=METHOD]’
1 ⇒Backup options. Make a backup of each file that would
1 otherwise be overwritten or removed.
1
1 ‘-d’
1 ‘-F’
1 ‘--directory’
1 Allow users with appropriate privileges to attempt to make hard
1 links to directories. However, note that this will probably fail
1 due to system restrictions, even for the super-user.
1
1 ‘-f’
1 ‘--force’
1 Remove existing destination files.
1
1 ‘-i’
1 ‘--interactive’
1 Prompt whether to remove existing destination files.
1
1 ‘-L’
1 ‘--logical’
1 If ‘-s’ is not in effect, and the source file is a symbolic link,
1 create the hard link to the file referred to by the symbolic link,
1 rather than the symbolic link itself.
1
1 ‘-n’
1 ‘--no-dereference’
1 Do not treat the last operand specially when it is a symbolic link
1 to a directory. Instead, treat it as if it were a normal file.
1
1 When the destination is an actual directory (not a symlink to one),
1 there is no ambiguity. The link is created in that directory. But
1 when the specified destination is a symlink to a directory, there
1 are two ways to treat the user’s request. ‘ln’ can treat the
1 destination just as it would a normal directory and create the link
1 in it. On the other hand, the destination can be viewed as a
1 non-directory—as the symlink itself. In that case, ‘ln’ must
1 delete or backup that symlink before creating the new link. The
1 default is to treat a destination that is a symlink to a directory
1 just like a directory.
1
1 This option is weaker than the ‘--no-target-directory’ (‘-T’)
1 option, so it has no effect if both options are given.
1
1 ‘-P’
1 ‘--physical’
1 If ‘-s’ is not in effect, and the source file is a symbolic link,
1 create the hard link to the symbolic link itself. On platforms
1 where this is not supported by the kernel, this option creates a
1 symbolic link with identical contents; since symbolic link contents
1 cannot be edited, any file name resolution performed through either
1 link will be the same as if a hard link had been created.
1
1 ‘-r’
1 ‘--relative’
1 Make symbolic links relative to the link location.
1
1 Example:
1
1 ln -srv /a/file /tmp
1 '/tmp/file' -> '../a/file'
1
1 Relative symbolic links are generated based on their canonicalized
1 containing directory, and canonicalized targets. I.e., all
11 symbolic links in these file names will be resolved. ⇒
realpath invocation, which gives greater control over relative
1 file name generation, as demonstrated in the following example:
1
1 ln--relative() {
1 test "$1" = --no-symlinks && { nosym=$1; shift; }
1 target="$1";
1 test -d "$2" && link="$2/." || link="$2"
1 rtarget="$(realpath $nosym -m "$target" \
1 --relative-to "$(dirname "$link")")"
1 ln -s -v "$rtarget" "$link"
1 }
1
1 ‘-s’
1 ‘--symbolic’
1 Make symbolic links instead of hard links. This option merely
1 produces an error message on systems that do not support symbolic
1 links.
1
1 ‘-S SUFFIX’
1 ‘--suffix=SUFFIX’
11 Append SUFFIX to each backup file made with ‘-b’. ⇒Backup
options.
1
1 ‘-t DIRECTORY’
1 ‘--target-directory=DIRECTORY’
1 Specify the destination DIRECTORY. ⇒Target directory.
1
1 ‘-T’
1 ‘--no-target-directory’
1 Do not treat the last operand specially when it is a directory or a
1 symbolic link to a directory. ⇒Target directory.
1
1 ‘-v’
1 ‘--verbose’
1 Print the name of each file after linking it successfully.
1
1 If ‘-L’ and ‘-P’ are both given, the last one takes precedence. If
1 ‘-s’ is also given, ‘-L’ and ‘-P’ are silently ignored. If neither
1 option is given, then this implementation defaults to ‘-P’ if the system
1 ‘link’ supports hard links to symbolic links (such as the GNU system),
1 and ‘-L’ if ‘link’ follows symbolic links (such as on BSD).
1
1 An exit status of zero indicates success, and a nonzero value
1 indicates failure.
1
1 Examples:
1
1 Bad Example:
1
1 # Create link ../a pointing to a in that directory.
1 # Not really useful because it points to itself.
1 ln -s a ..
1
1 Better Example:
1
1 # Change to the target before creating symlinks to avoid being confused.
1 cd ..
1 ln -s adir/a .
1
1 Bad Example:
1
1 # Hard coded file names don't move well.
1 ln -s $(pwd)/a /some/dir/
1
1 Better Example:
1
1 # Relative file names survive directory moves and also
1 # work across networked file systems.
1 ln -s afile anotherfile
1 ln -s ../adir/afile yetanotherfile
1