diff options
Diffstat (limited to 'man1p/ln.1p')
| -rw-r--r-- | man1p/ln.1p | 262 |
1 files changed, 262 insertions, 0 deletions
diff --git a/man1p/ln.1p b/man1p/ln.1p new file mode 100644 index 000000000..6b2f3eb9d --- /dev/null +++ b/man1p/ln.1p @@ -0,0 +1,262 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ln +.SH NAME +ln \- link files +.SH SYNOPSIS +.LP +\fBln\fP \fB[\fP\fB-fs\fP\fB]\fP \fIsource_file target_file\fP\fB +.br +.sp +ln\fP \fB[\fP\fB-fs\fP\fB]\fP \fIsource_file\fP \fB...\fP \fItarget_dir\fP\fB +.br +\fP +.SH DESCRIPTION +.LP +In the first synopsis form, the \fIln\fP utility shall create a new +directory entry (link) at the destination path specified by +the \fItarget_file\fP operand. If the \fB-s\fP option is specified, +a symbolic link shall be created for the file specified by +the \fIsource_file\fP operand. This first synopsis form shall be 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 shall result. +.LP +In the second synopsis form, the \fIln\fP utility shall create a new +directory entry (link), or if the \fB-s\fP option is +specified a symbolic link, for each file specified by a \fIsource_file\fP +operand, at a destination path in the existing directory +named by \fItarget_dir\fP. +.LP +If the last operand specifies an existing file of a type not specified +by the System Interfaces volume of +IEEE\ Std\ 1003.1-2001, the behavior is implementation-defined. +.LP +The corresponding destination path for each \fIsource_file\fP shall +be the concatenation of the target directory pathname, a +slash character, and the last pathname component of the \fIsource_file\fP. +The second synopsis form shall be assumed when the +final operand names an existing directory. +.LP +For each \fIsource_file\fP: +.IP " 1." 4 +If the destination path exists: +.RS +.IP " a." 4 +If the \fB-f\fP option is not specified, \fIln\fP shall write a diagnostic +message to standard error, do nothing more with the +current \fIsource_file\fP, and go on to any remaining \fIsource_files\fP. +.LP +.IP " b." 4 +Actions shall be performed equivalent to the \fIunlink\fP() function +defined in the +System Interfaces volume of IEEE\ Std\ 1003.1-2001, called using \fIdestination\fP +as the \fIpath\fP argument. If this +fails for any reason, \fIln\fP shall write a diagnostic message to +standard error, do nothing more with the current +\fIsource_file\fP, and go on to any remaining \fIsource_files\fP. +.LP +.RE +.LP +.IP " 2." 4 +If the \fB-s\fP option is specified, \fIln\fP shall create a symbolic +link named by the destination path and containing as its +pathname \fIsource_file\fP. The \fIln\fP utility shall do nothing +more with \fIsource_file\fP and shall go on to any remaining +files. +.LP +.IP " 3." 4 +If \fIsource_file\fP is a symbolic link, actions shall be performed +equivalent to the \fIlink\fP() function using the object that \fIsource_file\fP +references as the \fIpath1\fP +argument and the destination path as the \fIpath2\fP argument. The +\fIln\fP utility shall do nothing more with \fIsource_file\fP +and shall go on to any remaining files. +.LP +.IP " 4." 4 +Actions shall be performed equivalent to the \fIlink\fP() function +defined in the System +Interfaces volume of IEEE\ Std\ 1003.1-2001 using \fIsource_file\fP +as the \fIpath1\fP argument, and the destination path +as the \fIpath2\fP argument. +.LP +.SH OPTIONS +.LP +The \fIln\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following option shall be supported: +.TP 7 +\fB-f\fP +Force existing destination pathnames to be removed to allow the link. +.TP 7 +\fB-s\fP +Create symbolic links instead of hard links. +.sp +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIsource_file\fP +A pathname of a file to be linked. If the \fB-s\fP option is specified, +no restrictions on the type of file or on its +existence shall be made. If the \fB-s\fP option is not specified, +whether a directory can be linked is +implementation-defined. +.TP 7 +\fItarget_file\fP +The pathname of the new directory entry to be created. +.TP 7 +\fItarget_dir\fP +A pathname of an existing directory in which the new directory entries +are created. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIln\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All the specified files were linked successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +None. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +Some historic versions of \fIln\fP (including the one specified by +the SVID) unlink the destination file, if it exists, by +default. If the mode does not permit writing, these versions prompt +for confirmation before attempting the unlink. In these +versions the \fB-f\fP option causes \fIln\fP not to attempt to prompt +for confirmation. +.LP +This allows \fIln\fP to succeed in creating links when the target +file already exists, even if the file itself is not writable +(although the directory must be). Early proposals specified this functionality. +.LP +This volume of IEEE\ Std\ 1003.1-2001 does not allow the \fIln\fP +utility to unlink existing destination paths by +default for the following reasons: +.IP " *" 3 +The \fIln\fP utility has historically been used to provide locking +for shell applications, a usage that is incompatible with +\fIln\fP unlinking the destination path by default. There was no corresponding +technical advantage to adding this +functionality. +.LP +.IP " *" 3 +This functionality gave \fIln\fP the ability to destroy the link structure +of files, which changes the historical behavior of +\fIln\fP. +.LP +.IP " *" 3 +This functionality is easily replicated with a combination of \fIrm\fP +and \fIln\fP. +.LP +.IP " *" 3 +It is not historical practice in many systems; BSD and BSD-derived +systems do not support this behavior. Unfortunately, +whichever behavior is selected can cause scripts written expecting +the other behavior to fail. +.LP +.IP " *" 3 +It is preferable that \fIln\fP perform in the same manner as the \fIlink\fP() +function, +which does not permit the target to exist already. +.LP +.LP +This volume of IEEE\ Std\ 1003.1-2001 retains the \fB-f\fP option +to provide support for shell scripts depending on the +SVID semantics. It seems likely that shell scripts would not be written +to handle prompting by \fIln\fP and would therefore have +specified the \fB-f\fP option. +.LP +The \fB-f\fP option is an undocumented feature of many historical +versions of the \fIln\fP utility, allowing linking to +directories. These versions require modification. +.LP +Early proposals of this volume of IEEE\ Std\ 1003.1-2001 also required +a \fB-i\fP option, which behaved like the +\fB-i\fP options in \fIcp\fP and \fImv\fP, prompting for +confirmation before unlinking existing files. This was not historical +practice for the \fIln\fP utility and has been omitted. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIchmod\fP() , \fIfind\fP , \fIpax\fP , \fIrm\fP , the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, \fIlink\fP(), \fIunlink\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version 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 . |