Format
- ln [–fiRrs] old new
- ln [–fiRrs] old
old … dir
- ln -e [-fi] old new
Description
ln creates
a link to an existing file or set of files.
A link is a new directory entry that refers to the same file.
This entry can be in the same directory that currently contains the
file or in a different directory. The result is that you get a new
path name that refers to the file. You can access the file under the
old path name or the new one. Both path names are of equal importance.
If you use rm to remove either name, the
other one still remains and the file contents are still available
under that name. The contents of the file do not disappear until you
remove the last link.
A file can have any number of links to
it. Thus you can establish any number of different path names for
any file.
In the first form given in the syntax,
new becomes
a new path name for the existing file
old.
In the second form,
ln creates entries for
all the
old files under the directory
dir.
For example,
ln yourdir/* mydir
creates
links under mydir to all the files under yourdir. The
files have the same names under mydir that they had under yourdir. ln always
assumes this directory form when the last operand on the command line
is the name of a directory. In this case, none of the old names
can be a directory, unless -r or -R is
specified.
There could already be a file with the same name
as the link you are trying to set up: a conflicting path name. To
deal with a conflicting path name,
ln follows
these steps.
- If you have specified –i, ln writes
a prompt to stderr to ask if you want to get rid of the conflicting
path name. If you answer affirmatively, ln attempts
to remove it.
- Otherwise, if you have specified –f, ln attempts
to remove the existing file without a warning.
- Otherwise, ln prints a diagnostic message.
- ln gets to this point if it is going
to get rid of the conflicting path name. It therefore attempts to
get rid of the conflicting path name in the same way that rm does. ln deletes
the file associated with the path name if this path name is the last
link to the file. If ln can't get rid of
the conflicting path name, it does not attempt to establish the new
link; it simply prints an error message on stderr and goes
on to process any other files.
- If ln successfully gets rid of the conflicting
path name, it then establishes the link.
Options
- –e
- Specifies that the link created by ln is
to be an external link. One purpose for creating an external link
is to create a mount point that an NFS client can use to access a
data set through the Network File System feature. If you specify one
of these options with -e, the command will
fail. The normal content of an external link is a name that refers
to an object outside the hierarchical file system, such as a data
set. The data set that the Network File System feature uses can be
any type of MVS™ data set. For
a partitioned data set, however, you specify a fully qualified name
in all caps. For example:
ln -e NOLL.PLIB.PGMA /u/noll/plib/pgma
The -e option
is mutually exclusive with -r, -R and -s.
Restriction: Due
to the NFS protocol limitation, -e does
not create an external link on NFS. If you want to create an external
link on NFS, see the topic on creating an
external link for details in z/OS Network File System Guide and Reference.
External
links can also be used to map a z/OS® UNIX file name to a PDS or PDSE
member name for an executable load module. An example of how you would
define the external link is:
ln -e MYPGM /u/smorg/mylongpgmname
If
an application attempts to access
/u/smorg/mylongpgmname as
an executable file, the kernel will attempt to load MYPGM from the
current MVS search order (Job
Pack Queue, STEPLIB/JOBLIB, LPA, LINK LIST). The kernel services which
behave this way for external links are:
- exec() (all flavors)
- spawn() (including _spawn2, spawnp,
_spawnp2)
- loadhfs which is used for all DLL processing
and locales
An external link can be used as a shell command to invoke a program
in the current MVS search order.
- –f
- Deletes any conflicting path names without asking you for confirmation.
If -i is also specified, regardless of the
order in which -i and -f appear
on the command line, -i is ignored.
- –i
- Checks with you before deleting conflicting path names. If -f is
also specified, regardless of the order in which -i and -f appear
on the command line, -i is ignored.
- –R
- Links files recursively. That is, you can link an entire hierarchy
of subdirectories at once. -R is mutually
exclusive with the -e option.
- –r
- Is identical to –R. -r is
mutually exclusive with the -e option.
- –s
- Creates a symbolic link. The -s option
is mutually exclusive with the -e option.
For
a symbolic link, old refers to the file
you want to create the link to. That file does not have to exist.
The name of the symbolic link that you are creating is new.
Example:
If you have a file called
f1 and you want to create a symbolic
link to it called
my_sym, issue:
ln -s f1 my_sym
The locale settings for LC_COLLATE, LC_CTYPE, and
LC_MESSAGES affect the program's interpretation of what constitutes
a Yes answer when ln asks if you want to
delete a conflicting path name.
Examples
If you define /u/user1/name1 as
a symbolic link to /u/user1/name2, and then invoke name1:
- The shell will spawn name1.
- spawn() will access the file for name1 unaware
that there is a symbolic link already established. It will access
the name2 file by its underlying vnode, not the name2 handle.
- If the sticky bit is on for the name2 file, spawn() will
do the MVS search for name1 (the
only name it has to work with).
Symbolic and external links with a sticky bit:
Note: DLLs,
and all flavors of spawn() and exec(),
follow the same processing as described in this section. Where it
says exec(), it covers all forms of module
loading.
- External links:
exec() does a stat() on
the passed filename. stat() does the search,
not exec(). If the filename is an external
link, then stat() fails with a unique reason
code which causes exec() to read the external
link. If the external link name is a valid PDS member name (1–8 alphanumeric
or special characters), then exec() will
attempt to locate the module in the MVS search
order. If it cannot be found, exec() fails.
The
external link is normally used when you want to set the sticky bit
on for a file name which is longer than 8 characters or contains characters
unacceptable for a PDS member name.
- Symbolic links:
If the filename you specify is a symbolic link,
and exec() sees the sticky bit on, then
it will truncate any dot qualifiers. So, as long as the base filename
is an acceptable PDS member name, the need to set up links in order
to get exec() to go to the MVS search order should not be an issue.
For
example, if you have a file named java.jll, when you put the sticky
bit on, exec() will attempt to load JAVA.
If exec() cannot find JAVA, it will revert
to using the java.jll file in the file system.
The important
thing to understand is that exec() never
sees the name that the symbolic link resolves to even though it can
see the stat() data for the final file.
Localization
ln uses
the following localization environment variables:
- LANG
- LC_ALL
- LC_CTYPE
- LC_MESSAGES
- LC_SYNTAX
- NLSPATH
See Localization for more
information.
Exit values
- 0
- All requested links were established successfully.
- 1
- Failure due to any of the following:
- An argument had a trailing / but was not the
name of a directory.
- A file could not be found.
- An input file could not be opened for reading.
- An output file could not be created or opened for output.
- The new link file already exists.
- A link could not be established.
- A read error occurred on an input file.
- A write error occurred on an output file.
- The input and output files were the same file.
- Inability to access a file when using –r.
- Inability to read a directory when using –r.
- Inability to create a directory when using –r.
- A target is not a directory when using –r.
- Source and destination directory are the same when using –r.
- 2
- Failure due to any of the following:
- Incorrect command-line option.
- Too few arguments on the command line.
- A target that should be a directory but isn't.
- No space left on target device.
- Out of memory to hold the data to be copied.
- Inability to create a directory to hold a target file.
Messages
Possible error messages include:
- link to target name failed
- ln could not establish the link to the
given file or directory. This may be because you do not have appropriate
permissions, or because the target did not exist.
- source name and target name are
identical
- The source and the target are actually the same file (for example,
because of links, on UNIX systems).
In this case, ln does nothing.
- target directory name on different file
system than source name
- You cannot establish a normal link between files that are two
different file systems.
- target name must be a directory
- The target name must be a directory
- cannot find file name
- The file name could not be found.
- target file name already exists
- The target file name already exists.
Portability
POSIX.2, X/Open Portability Guide, UNIX systems.
Only
the -f option is part of the POSIX standard.
Related information
cp, locale, mv, rm