ln — Create a link to a file

Format

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:

  1. The shell will spawn name1.
  2. 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.
  3. 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.
  1. 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.

  2. 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

Parent topic: Shell command descriptions