path: root/usr/src/man/man1/ln.1

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
.\" Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved
.\"
.TH LN 1 "Mar 25, 2004"
.SH NAME
ln \- make hard or symbolic links to files
.SH SYNOPSIS
.LP
.nf
\fB/usr/bin/ln\fR [\fB-fns\fR] \fIsource_file\fR [\fItarget\fR]
.fi

.LP
.nf
\fB/usr/bin/ln\fR [\fB-fns\fR] \fIsource_file\fR... \fItarget\fR
.fi

.LP
.nf
\fB/usr/xpg4/bin/ln\fR [\fB-fs\fR] \fIsource_file\fR [\fItarget\fR]
.fi

.LP
.nf
\fB/usr/xpg4/bin/ln\fR [\fB-fs\fR] \fIsource_file\fR... \fItarget\fR
.fi

.SH DESCRIPTION
.sp
.LP
In the first synopsis form, the \fBln\fR utility creates a new directory entry
(link) for the file specified by \fIsource_file\fR, at the destination path
specified by \fItarget\fR. If \fItarget\fR is not specified, the link is made
in the current directory. This first synopsis form is 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 will result.
.sp
.LP
In the second synopsis form, the \fBln\fR utility creates a new directory entry
for each file specified by a \fIsource_file\fR operand, at a destination path
in the existing directory named by \fItarget\fR.
.sp
.LP
The \fBln\fR utility may be used to create both hard links and symbolic links.
A hard link is a pointer to a file and 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 span file systems and may not
refer to directories.
.sp
.LP
\fBln\fR by default creates hard links. \fIsource_file\fR is linked to
\fItarget\fR. If \fItarget\fR is a directory, another file named
\fIsource_file\fR is created in \fItarget\fR and linked to the original
\fIsource_file\fR.
.sp
.LP
If \fItarget\fR is an existing file and the \fB-f\fR option is not specified,
\fBln\fR will write a diagnostic message to standard error, do nothing more
with the current \fIsource_file\fR, and go on to any remaining
\fIsource_file\fRs.
.sp
.LP
A symbolic link is an indirect pointer to a file; its directory entry  contains
the name of the file to which it is linked. Symbolic links may span file
systems and may refer to directories.
.sp
.LP
File permissions for \fItarget\fR may be different from those displayed with an
\fB-l\fR listing of the \fBls\fR(1) command. To display the permissions of
\fItarget\fR, use \fBls\fR \fB-lL\fR. See \fBstat\fR(2) for more information.
.SS "/usr/bin/ln"
.sp
.LP
If \fB/usr/bin/ln\fR determines that the mode of \fItarget\fR forbids writing,
it prints the mode (see \fBchmod\fR(1)), asks for a response, and reads the
standard input for one line. If the response is affirmative, the link occurs,
if permissible. Otherwise, the command exits.
.SS "/usr/xpg4/bin/ln"
.sp
.LP
When creating a hard link, and the source file is itself a symbolic link, the
target will be a hard link to the file referenced by the symbolic link, not to
the symbolic link object itself (\fIsource_file\fR).
.SH OPTIONS
.sp
.LP
The following options are supported for both \fB/usr/bin/ln\fR and
\fB/usr/xpg4/bin/ln\fR:
.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 6n
Links files without questioning the user, even if the mode of \fItarget\fR
forbids writing. This is the default if the standard input is not a terminal.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 6n
Creates a symbolic link.
.sp
If the \fB-s\fR option is used with two arguments, \fItarget\fR may be an
existing directory or a non-existent file. If \fItarget\fR already exists and
is not a directory, an error is returned. \fIsource_file\fR may be any path
name and need not exist. If it exists, it may be a file or directory and may
reside on a different file system from \fItarget\fR. If \fItarget\fR is an
existing directory, a file is created in directory \fItarget\fR whose name is
\fIsource_file\fR or the last component of \fIsource_file\fR. This file is a
symbolic link that references \fIsource_file\fR. If \fItarget\fR does not
exist, a file with name \fItarget\fR is created and it is a symbolic link that
references \fIsource_file\fR.
.sp
If the \fB-s\fR option is used with more than two arguments, \fItarget\fR must
be an existing directory or an error will be returned. For each
\fIsource_file\fR, a link is created in \fItarget\fR whose name is the last
component of \fIsource_file\fR. Each new \fIsource_file\fR is a symbolic link
to the original \fIsource_file\fR. The files and \fItarget\fR may reside on
different file systems.
.RE

.SS "/usr/bin/ln"
.sp
.LP
The following option is supported for \fB/usr/bin/ln\fR only:
.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.RS 6n
If \fItarget\fR is an existing file, writes a diagnostic message to stderr and
goes on to any remaining \fIsource_file\fRs. The \fB-f\fR option overrides this
option. This is the default behavior for \fB/usr/bin/ln\fR and
\fB/usr/xpg4/bin/ln\fR, and is silently ignored.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIsource_file\fR\fR
.ad
.RS 15n
A path name of a file to be linked. This can be either a regular or special
file. If the \fB-s\fR option is specified, \fIsource_file\fR can also be a
directory.
.RE

.sp
.ne 2
.na
\fB\fItarget\fR\fR
.ad
.RS 15n
The path name of the new directory entry to be created, or of an existing
directory in which the new directory entries are to be created.
.RE

.SH USAGE
.sp
.LP
See \fBlargefile\fR(5) for the description of the behavior of \fBln\fR when
encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBln\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
All the specified files were linked successfully
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.SS "/usr/bin/ln"
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled
.TE

.SS "/usr/xpg4/bin/ln"
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled
_
Interface Stability	Standard
.TE

.SH SEE ALSO
.sp
.LP
\fBchmod\fR(1), \fBls\fR(1), \fBstat\fR(2), \fBattributes\fR(5),
\fBenviron\fR(5), \fBlargefile\fR(5), \fBstandards\fR(5)
.SH NOTES
.sp
.LP
A symbolic link to a directory behaves differently than you might expect in
certain cases. While an \fBls\fR(1) command on such a link displays the files
in the pointed-to directory, entering \fBls\fR \fB-l\fR displays information
about the link itself:
.sp
.in +2
.nf
example% \fBln -s dir link\fR
example% \fBls link\fR
file1 file2 file3 file4
example% \fBls -l link\fR
lrwxrwxrwx  1 user            7 Jan 11 23:27 link -> dir
.fi
.in -2
.sp

.sp
.LP
When you change to a directory (see \fBcd\fR(1)) through a symbolic link, using
\fB/usr/bin/sh\fR or \fB/usr/bin/csh\fR, you wind up in the pointed-to location
within the file system. This means that the parent of the new working directory
is not the parent of the symbolic link, but rather, the parent of the
pointed-to directory. This will also happen when using \fBcd\fR with the
\fB-P\fR option from \fB/usr/bin/ksh\fR or \fB/usr/xpg4/bin/sh\fR. For
instance, in the following case, the final working directory is \fB/usr\fR and
not \fB/home/user/linktest\fR.
.sp
.in +2
.nf
example% \fBpwd\fR
/home/user/linktest
example% \fBln -s /usr/tmp symlink\fR
example% \fBcd symlink\fR
example% \fBcd .\|.\fR
example% \fBpwd\fR
/usr
.fi
.in -2
.sp

.sp
.LP
C shell users can avoid any resulting navigation problems by using the
\fBpushd\fR and \fBpopd\fR built-in commands instead of \fBcd\fR.