Add an EXAMPLES section. Note that symbolic links may refer to non-existent

files (as pointed out in symlink(2)). Fix some formatting, too.

1 files changed, 49 insertions, 17 deletions

diff --git a/bin/ln/ln.1 b/bin/ln/ln.1
index 6cfa21a2332..e519288e61b 100644
--- a/bin/ln/ln.1
+++ b/bin/ln/ln.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ln.1,v 1.7 1999/08/16 18:40:03 aaron Exp $
+.\"	$OpenBSD: ln.1,v 1.8 1999/09/23 19:15:49 aaron Exp $
 .\"	$NetBSD: ln.1,v 1.10 1995/07/25 19:37:04 jtc Exp $
 .\"
 .\" Copyright (c) 1980, 1990, 1993
@@ -42,7 +42,7 @@
 .Os
 .Sh NAME
 .Nm ln
-.Nd make links
+.Nd make hard and symbolic links to files
 .Sh SYNOPSIS
 .Nm ln
 .Op Fl fs
@@ -58,14 +58,12 @@ The
 utility creates a new directory entry (linked file) which has the
 same modes as the original file.
 It is useful for maintaining multiple copies of a file in many places
-at once without using up storage for the
-.Dq copies ;
+at once without using up storage for the 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
+How a link points
 to a file is one of the differences between a hard and symbolic link.
 .Pp
 The options are as follows:
@@ -79,7 +77,7 @@ Create a symbolic link.
 By default,
 .Nm
 makes
-.Em hard
+.Dq hard
 links.
 A hard link to a file is indistinguishable from the original directory entry;
 any changes to a file are effectively independent of the name used to reference
@@ -87,32 +85,34 @@ 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
+which it is linked.
+The referenced file is used when an
+.Xr open 2
 operation is performed on the link.
 A
-.Xr stat  2
+.Xr stat 2
 on a symbolic link will return the linked-to file; an
-.Xr lstat  2
+.Xr lstat 2
 must be done to obtain information about the link.
 The
-.Xr readlink  2
+.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.
+Symbolic links may span file systems, refer to directories, and refer to
+non-existent files.
 .Pp
 Given one or two arguments,
 .Nm
 creates a link to an existing file
-.Ar source_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.
+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  .
+.Ar source_file .
 .Pp
 Given more than two arguments,
 .Nm
@@ -120,6 +120,38 @@ 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 EXAMPLES
+Create a symbolic link named
+.Pa /home/www
+and point it to
+.Pa /var/www :
+.Pp
+.D1 Ic ln -s /var/www /home/www
+.Pp
+Hard link
+.Pa /usr/local/bin/fooprog
+to file
+.Pa /usr/local/bin/fooprog-1.0 :
+.Pp
+.D1 Ic ln /usr/local/bin/fooprog-1.0 /usr/local/bin/fooprog
+.Pp
+As an exercise, try the following commands:
+.Pp
+.D1 Ic $ ls -i /bin/[
+.D1 Li 11553 /bin/[
+.D1 Ic $ ls -i /bin/test
+.D1 Li 11553 /bin/test
+.Pp
+Note that both files have the same inode; that is,
+.Pa /bin/[
+is essentially an alias for the
+.Xr test 1
+command.
+This hard link exists so
+.Xr test 1
+may be invoked from shell scripts, for example, using the
+.Cm "if [ ]"
+construct.
 .Sh SEE ALSO
 .Xr link 2 ,
 .Xr lstat 2 ,