manual/gnumaniak/original/man1/ln.1

   1 .\" Copyright Andries Brouwer, A. Wik 1998, Ragnar Hojland Espinosa 1998-2002
   2 .\"
   3 .\" This file may be copied under the conditions described
   4 .\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998
   5 .\" that should have been distributed together with this file.
   6 .\"
   7 .TH LN 1 "18 June 2002" "GNU fileutils 4.1"
   8 .SH NAME
   9 ln \- make links between files
  10 .SH SYNOPSIS
  11 .B ln [options]
  12 .IB source " [" dest ]
  13 .br
  14 .B ln [options]
  15 .I source... directory
  16 .sp
  17 POSIX options:
  18 .B [\-f]
  19 .sp
  20 GNU options (shortest form):
  21 .B [\-bdfinsvF]
  22 .BI "[\-S " backup-suffix ]
  23 .B "[\-V {numbered,existing,simple}]"
  24 .BI [\-\-target\-directory= dir ]
  25 .B "[\-\-help] [\-\-version] [\-\-]"
  26 .SH DESCRIPTION
  27 .B ln
  28 makes links between files.  By default, it makes hard links;
  29 with the
  30 .B "\-s"
  31 option, it makes symbolic (or `soft') links.
  32 .PP
  33 There are two concepts of `link' in Unix, usually called
  34 hard link and soft link. A hard link is just a name for a file.
  35 (And a file can have several names. It is deleted from disk only
  36 when the last name is removed. The number of names is given by
  37 .BR ls (1).
  38 There is no such thing as an `original' name: all names have the
  39 same status. Usually, but not necessarily, all names of a file
  40 are found in the filesystem that also contains its data.)
  41 .PP
  42 A soft link (or symbolic link, or symlink) is an entirely different
  43 animal: it is a small special file that contains a pathname.
  44 Thus, soft links can point at files on different filesystems
  45 (possibly NFS mounted from different machines), and need not point
  46 to actually existing files.
  47 When accessed (with the
  48 .BR open (2)
  49 or
  50 .BR stat (2)
  51 system calls), a reference to a symlink is replaced by the operating
  52 system kernel with a reference to the file named by the path name.
  53 (However, with
  54 .BR rm (1)
  55 and
  56 .BR unlink (2)
  57 the link itself is removed, not the file it points to.
  58 There are special system calls
  59 .BR lstat (2)
  60 and
  61 .BR readlink (2)
  62 that read the status of a symlink and the filename it points to.
  63 For various other system calls there is some uncertainty
  64 and variation between operating systems as to whether
  65 the operation acts on the symlink itself, or on the file pointed to.)
  66 .PP
  67 \fB\(bu\fR\ If only one file is given, it links that file into
  68 the current directory, that is, creates a link to that file
  69 in the current directory, with name equal to (the last component of)
  70 the name of that file. (This is a GNU extension)
  71 .PP
  72 \fB\(bu\fR\ If the last argument names an existing directory,
  73 .B ln
  74 will create links to each mentioned
  75 .I source
  76 file in that directory, with a name equal to (the last component of)
  77 the name of that
  78 .I source
  79 file.  (But see the description of the
  80 .B "\-\-no\-dereference"
  81 option below)
  82 .PP
  83 \fB\(bu\fR\ If only two files are given, it creates a link named
  84 .I dest
  85 to the file
  86 .IR source .
  87 It is an error if the last argument is not a directory and
  88 more than two files are given.
  89 .PP
  90 By default,
  91 .B ln
  92 does not remove existing files or existing symbolic links.
  93 (Thus, it can be used for locking purposes: it will succeed only if
  94 .I dest
  95 did not exist already.)
  96 But it can be forced to do so with the option \-f.
  97 .PP
  98 On existing implementations, if it is at all possible to make a hard link
  99 to a directory, this may be done by the superuser only. POSIX forbids
 100 the system call
 101 .BR link (2)
 102 and the utility
 103 .B ln
 104 to make hard links to directories (but does not forbid
 105 hard links to cross filesystem boundaries).
 106 .SH "POSIX OPTIONS"
 107 .TP
 108 .B "\-f"
 109 Remove existing destination files.
 110 .SH "GNU OPTIONS"
 111 .TP
 112 .B "\-d, \-F, \-\-directory"
 113 Allow the super-user to make hard links to directories.
 114 .TP
 115 .B "\-f, \-\-force"
 116 Remove existing destination files.
 117 .TP
 118 .B "\-i, \-\-interactive"
 119 Prompt whether to remove existing destination files.
 120 .TP
 121 .B "\-n, \-\-no\-dereference"
 122 When given an explicit destination that is a symlink to a
 123 directory, treat that destination as if it were a normal file.
 124 .br
 125 When the destination is an actual directory (not a symlink to one),
 126 the link is created in that directory.
 127 But when the specified destination is a symlink to a directory,
 128 there are two possibilities:
 129 .B ln
 130 can treat the destination just as it would a normal directory and
 131 create the link in it.  On the other hand, the destination can be
 132 viewed as a non-directory--as the symlink itself.  In that case,
 133 .B ln
 134 must delete or backup that symlink before creating the new link.
 135 The default is to treat a destination that is a symlink to a directory
 136 just like a directory.
 137 .TP
 138 .B "\-s, \-\-symbolic"
 139 Make symbolic links instead of hard links.  This option merely
 140 produces an error message on systems that do not support symbolic links.
 141 .TP
 142 .BI "\-\-target\-directory=" DIR
 143 Specify the the target directory with an option instead of as the last arg
 144 in the command line.  This is useful with \fBxargs(1)\fR.
 145 .TP
 146 .B "\-v, \-\-verbose"
 147 Print the name of each file before linking it.
 148 .SH "GNU BACKUP OPTIONS"
 149 The GNU versions of programs like
 150 .BR cp ,
 151 .BR mv ,
 152 .BR ln ,
 153 .B install
 154 and
 155 .B patch
 156 will make a backup of files about to be overwritten, changed or destroyed
 157 if that is desired. That backup files are desired is indicated by
 158 the \-b option. How they should be named is specified by the \-\-backup option.
 159 In case the name of the backup file is given by the name of the file
 160 extended by a suffix, this suffix is specified by the \-S option.
 161 .TP
 162 .BI "\-b, \-\-backup[=" METHOD ]
 163 Make backups of files that are about to be overwritten or removed.  Note
 164 that \fB\-b\fR does not take args.
 165 .TP
 166 .BI "\-S " SUFFIX ", \-\-suffix=" SUFFIX
 167 Append
 168 .I SUFFIX
 169 to each backup file made.
 170 If this option is not specified, the value of the
 171 .B SIMPLE_BACKUP_SUFFIX
 172 environment variable is used.  And if
 173 .B SIMPLE_BACKUP_SUFFIX
 174 is not set, the default is `~'.
 175 .TP
 176 .BI "\-V " METHOD ", \-\-version\-control=" METHOD
 177 This option is deprecated, use \fB\-\-backup=\fIMETHOD\fR instead.
 178 .RS
 179 Specify how backup files are named. The
 180 .I METHOD
 181 argument can be `numbered' (or `t'), `existing' (or `nil'), or `never' (or
 182 `simple').
 183 If this option is not specified, the value of the
 184 .B VERSION_CONTROL
 185 environment variable is used.  And if
 186 .B VERSION_CONTROL
 187 is not set, the default backup type is `existing'.
 188 .PP
 189 This option corresponds to the Emacs variable `version-control'.
 190 The valid
 191 .IR METHOD s
 192 are (unique abbreviations are accepted):
 193 .TP
 194 .BR t ", " numbered
 195 Always make numbered backups.
 196 .TP
 197 .BR nil ", " existing
 198 Make numbered backups of files that already have them, simple
 199 backups of the others.
 200 .TP
 201 .BR never ", " simple
 202 Always make simple backups.
 203 .RE
 204 .SH "GNU STANDARD OPTIONS"
 205 .TP
 206 .B "\-\-help"
 207 Print a usage message on standard output and exit successfully.
 208 .TP
 209 .B "\-\-version"
 210 Print version information on standard output, then exit successfully.
 211 .TP
 212 .B "\-\-"
 213 Terminate option list.
 214 .SH ENVIRONMENT
 215 The variables LANG, LC_ALL, LC_CTYPE and LC_MESSAGES have the
 216 usual meaning.
 217 .SH "CONFORMING TO"
 218 POSIX 1003.2. However, POSIX 1003.2 (1996) does not discuss soft links.
 219 Soft links were introduced by BSD, and do not occur in System V release 3
 220 (and older) systems.
 221 .SH "SEE ALSO"
 222 .BR ls (1),
 223 .BR rm (1),
 224 .BR link (2),
 225 .BR lstat (2),
 226 .BR open (2),
 227 .BR readlink (2),
 228 .BR stat (2),
 229 .BR unlink (2)
 230 .SH NOTES
 231 This page describes
 232 .B ln
 233 as found in the fileutils-4.1 package;
 234 other versions may differ slightly. Mail corrections and additions
 235 aeb@cwi.nl and aw@mail1.bet1.puv.fi and ragnar@ragnar-hojland.com
 236 Report bugs in the program to bug-fileutils@gnu.org.