.\" Copyright (c) 1980, 1990 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the Institute of Electrical and Electronics Engineers, Inc.
.\"
.\" %sccs.include.redist.roff%
.\"
.\"	@(#)ln.1	6.11 (Berkeley) %G%
.\"
.Dd 
.Dt LN 1
.Os BSD 4
.Sh NAME
.Nm ln
.Nd make links
.Sh SYNOPSIS
.Nm ln
.Op Fl fs
.Ar source_file
.Op target_file
.Nm ln
.Op Fl fs
.Ar source_file ...
.Op target_dir
.Sh DESCRIPTION
The
.Nm ln
utility creates a new directory entry (linked file) which has the
same modes as the orginal file.
It is useful for maintaining multiple copies of a file in many places
at once without using up storage for the
.Dq copies ;
instead, a link
.Dq points
to the original copy.
There are two types of links; hard links and symbolic links.
How a link
.Dq points
to a file is one of the differences between a hard or symbolic link.
.Pp
The options are as follows:
.Bl -tag -width flag
.It Fl f
Unlink any already existing file, permitting the link to occur.
.It Fl s
Create a symbolic link.
.El
.Pp
By default
.Nm ln
makes
.Em hard
links.
A hard link to a file is indistinguishable from the original directory entry;
any changes to a file are effective independent of the name used to reference
the file.
Hard links may not normally refer to directories and may not span file systems.
.Pp
A symbolic link contains the name of the file to
which it is linked.  The referenced file is used when an
.Xr open  2
operation is performed on the link.
A
.Xr stat  2
on a symbolic link will return the linked-to file; an
.Xr lstat  2
must be done to obtain information about the link.
The
.Xr readlink  2
call may be used to read the contents of a symbolic link.
Symbolic links may span file systems and may refer to directories.
.Pp
Given one or two arguments,
.Nm ln
creates a link to an existing file
.Ar source_file  .
If
.Ar target_file
is given, the link has that name;
.Ar target_file
may also be a directory in which to place the link;
otherwise it is placed in the current directory.
If only the directory is specified, the link will be made
to the last component of
.Ar source_file  .
.Pp
Given more than two arguments,
.Nm ln
makes links in
.Ar target_dir
to all the named source files.
The links made will have the same name as the files being linked to.
.Sh SYMBOLIC LINK HANDLING
There are two issues involved in symbolic link handling.
The first issue is whether or not the utility or system call operates
on the symbolic link itself or if it operates on the object to which
the symbolic link refers.
The following rules summarize the conventions of symbolic link handling
in the system.
Operating on the object referenced by the symbolic link or indirecting
through symbolic links to directories is termed ``following'' the link.
.Pp
The system calls that do not follow symbolic links are
.Xr lstat 2 ,
.Xr readlink 2 ,
.Xr rename 2 ,
and
.Xr unlink 2 .
All other system calls follow the symbolic link.
.Pp
The utilities that do not follow symbolic links are
.Xr mv 1
and
.Xr rm 1 .
For compatibility with historic systems, the 
.Xr ls
utility follows symbolic links listed on the command line, unless the
.Fl F ,
.Fl d
or
.Fl l 
options are specified.
However, if the
.Fl L
option is specified,
.Xr ls
always follows symbolic links.
All other utilities follow symbolic links.
.Pp
The second issue in symbolic link handling is traversal of a file hierarchy.
There are two ways for file hierarchy oriented utilities to traverse a
file hierarchy.
The first is a physical traversal, where the utility does not indirect
through symbolic links to directories.
The second is a logical traversal, where the utility does indirect
through symbolic links to directories.
.Pp
The utilities that work with file hierarchies, either optionally or by
default, are
.Xr chflags 1 ,
.Xr chgrp 1 ,
.Xr chmod 1 ,
.Xr chown 8 ,
.Xr cp 1 ,
.Xr du 1 ,
.Xr find 1 ,
.Xr ls 1 ,
.Xr rm 1
and
.Xr tar 1 .
All of these utilities, except for
.Xr cp ,
.Xr ls
and
.Xr rm ,
operate according to the following rules.
.Pp
By default, these utilities do a physical traversal, never following any
symbolic links.
If the
.Fl H 
option is specified, the utility will follow symbolic links specified
on the command line.
If the
.Fl h
option is specified, the utilities do a logical traversal, following all
symbolic links whether specified on the command line or encountered while
descending the file hierarchy.
The
.Fl H
flag is intended to make the command line name space look like the logical
name space and the
.Fl h
flag is intended to make the entire hierarchy look like the logical name
space.
.Pp
The utilities
.Xr cp , 
.Xr ls
and
.Xr rm
are exceptions to these rules.
.Pp
To maintain compatibility with historic systems,
.Xr cp
always follows symbolic links on the command line.
The 
.Fl H
and 
.Fl h
options have the effects described above only when the
.Fl R 
flag is specified.
.Pp
.Xr Rm
operates on the name, not the object it points to, and therefore never
follows a symbolic link.
The
.Xr rm
utility does not support the
.Fl H
or
.Fl h
options.
.Pp
To maintain compatibility with historic systems, the
.Xr ls
utility follows all symbolic links in the file hierarchy, including ones
listed on the command line, only when the 
.Fl L 
option is specified.
The
.Xr ls
utility does not support the
.Fl H
or
.Fl h
options.
.Sh SEE ALSO
.Xr link 2 ,
.Xr lstat 2 ,
.Xr readlink 2 ,
.Xr stat 2 ,
.Xr symlink 2
.Sh HISTORY
A
.Nm ln
command appeared in
.At v6 .