Directory and file management

Using symbolic links

This section discusses creating, removing, accessing, copying, and linking symbolic links.

Creating symbolic links

To create a symbolic link, the new system call symlink(2) is used and the owner must have write permission in the directory where the link will reside. The file is created with the user's user-id and group-id but these are subsequently ignored. The mode of the file is created as 0777.

CAUTION: No checking is done when a symbolic link is created. There is nothing to stop a user from creating a symbolic link that refers to itself or to an ancestor of itself or several links that loop around among themselves. Therefore, when evaluating a pathname, it is important to put a limit on the number of symbolic links that may be encountered in case the evaluation encounters a loop. The variable MAXSYMLINKS is used to force the error ELOOP after MAXSYMLINKS symbolic links have been encountered. The value of MAXSYMLINKS should be at least 20.

To create a symbolic link, the ln command is used with the -s option (see ln(1)). If the -s option is not used and a user tries to create a link to a file on another file system, a symbolic link will not be created and the command will fail.

The syntax for creating symbolic links is as follows:

   ln -s sourcefile1 [ sourcefile2 ... ] target

With two arguments:

sourcefile1 may be any pathname and need not exist.
target may be an existing directory or a non-existent file.
If target is an existing directory, a file is created in directory target whose name is the last component of sourcefile1 (`basename sourcefile1`). This file is a symbolic link that references sourcefile1.
If target does not exist, a file with name target is created and it is a symbolic link that references sourcefile1.
If target already exists and is not a directory, an error is returned.
sourcefile1 and target may reside on different file systems.

With more than two arguments:

For each sourcefile, a file is created in target whose name is sourcefile or its last component (`basename sourcefile`) and is a symbolic link to sourcefile.
If target is not an existing directory, an error is returned.
Each sourcefile and target may reside on different file systems.

Examples

The following examples show how symbolic links may be created.

   ln -s /usr/src/uts/sys  /usr/include/sys

In this example /usr/include is an existing directory. But file sys does not exist so it will be created as a symbolic link that refers to /usr/src/uts/sys. The result is that when file /usr/include/sys/x is accessed, the file /usr/src/uts/sys/x will actually be accessed.

This kind of symbolic link may be used when files exist in the directory /usr/src/uts/sys but programs often refer to files in /usr/include/sys. Rather than creating corresponding files in /usr/include/sys that are hard links to files in /usr/src/uts/sys, one symbolic link can be used to link the two directories. In this example /usr/include/sys becomes a symbolic link that links the former /usr/include/sys directory to the /usr/src/uts/sys directory.

   ln -s  /etc/group  .

In this example the target is a directory (the current directory), so a file called group (`basename /etc/group`) is created in the current directory that is a symbolic link to /etc/group.

   ln -s  /fs1/jan/abc  /var/spool/abc

In this example we imagine that /fs1/jan/abc does not exist at the time the command is issued. Nevertheless, the file /var/spool/abc is created as a symbolic link to /fs1/jan/abc. Later, /fs1/jan/abc may be created as a directory, regular file, or any other file type.

The following example illustrates the use of more than two arguments:

   ln -s  /etc/group  /etc/passwd  .

The user would like to have the group and passwd files in the current directory but cannot use hard links because /etc is a different file system. When more than two arguments are used, the last argument must be a directory; here it is the current directory. Two files, group and passwd, are created in the current directory, each a symbolic link to the associated file in /etc.

Removing symbolic links

Normally, when accessing a symbolic link, one follows the link and actually accesses the referenced file. However, this is not the case when one attempts to remove a symbolic link. When the rm(1) command is executed and the argument is a symbolic link, it is the symbolic link that is removed; the referenced file is not touched.

Accessing symbolic links

Suppose abc is a symbolic link to file def. When a user accesses the symbolic link abc, it is the file permissions (ownership and access) of file def that are actually used; the permissions of abc are always ignored. If file def is not accessible (that is, either it does not exist or it exists but is not accessible to the user because of access permissions) and a user tries to access the symbolic link abc, the error message will refer to abc, not file def.

Copying symbolic links

This section describes the behavior of the cp(1) command when one or more arguments are symbolic links. With the cp(1) command, if any argument is a symbolic link, that link is followed. Suppose the command line is

   cp sym file3

where sym is a symbolic link that references a regular file test1 and file3 is a regular file. After execution of the command, file3 gets overwritten with the contents of the file test1.

If the last argument is a symbolic link that references a directory, then files are copied to that directory. Suppose the command line is

   cp file1 sym symd

where file1 is a regular file, sym is a symbolic link that references a regular file test1, and symd is a symbolic link that references a directory DIR. After execution of the command, there will be two new files, DIR/file1 and DIR/sym that have the same contents as file1 and test1.

Linking symbolic links

This section describes the behavior of the ln(1) command when one or more arguments are symbolic links. To understand the difference in behavior between this and the cp(1) command, it is useful to think of a copy operation as dealing with the contents of a file while the link operation deals with the name of a file.

Let us look at the case where the source argument to ln is a symbolic link. If the -s option is specified to ln, the command calls the symlink system call (see symlink(2)). symlink does not follow the symbolic link specified by the source argument and creates a symbolic link to it. If -s is not specified, ln invokes the link(2) system call. link follows the symbolic link specified by the source argument and creates a hard link to the file referenced by the symbolic link.

For the target argument, ln invokes a stat system call (see stat(2)). If stat indicates that the target argument is a directory, the files are linked in that directory. Otherwise, if the target argument is an existing file, it is overwritten. This means that if the second argument is a symbolic link to a directory, it is followed, but if it is a symbolic link to a regular file, the symbolic link is overwritten.

For example, if the command line is

   ln sym file1

where sym is a symbolic link that references a regular file foo, and file1 is a regular file, file1 is overwritten and hard-linked to foo. Thus a hard link to a regular file has been created.

If the command is

   ln -s sym file1

where the files are the same as in first example, file1 is overwritten and becomes a symbolic link to sym.

If the command is

   ln file1 sym

where the files are the same as in the first example, sym is overwritten and hard-linked to file1.

When the last argument is a directory as in

   ln file1 sym symd

where symd is a symbolic link to a directory DIR, and file1 and sym are the same as in the first example, the file DIR/file1 is hard-linked to file1 and DIR/sym is hard-linked to foo.

Moving symbolic links

This section describes the behavior of the mv(1) command. Like the ln(1) command, mv(1) deals with file names rather than file contents. With two arguments, a user invokes the mv(1) command to rename a file. Therefore, one would not want to follow the first argument if it is a symbolic link because it is the name of the file that is to be changed rather than the file contents. Suppose that sym is a symbolic link to /etc/passwd and abc is a regular file. If the command

   mv sym abc

is executed, the file sym is renamed abc and is still a symbolic link to /etc/passwd. If abc existed (as a regular file or a symbolic link to a regular file) before the command was executed, it is overwritten.

Suppose the command is

   mv sym1 file1 symd

where sym1 is a symbolic link to a regular file foo, file1 is a regular file, and symd is a symbolic link that references a directory DIR. When the command is executed, the files sym1 and file1 are moved from the current directory to the DIR directory so that there are two new files, DIR/sym1, which is still a symbolic link to foo, and DIR/file1.

In UnixWare, the mv(1) command uses the rename(2) system call. If the first argument to rename(2) is a symbolic link, rename(2) does not follow it; instead it renames the symbolic link itself. In System V prior to Release 4, a file was moved using the link(2) system call followed by the unlink(2) system call. Since link(2) and unlink(2) do not follow symbolic links, the result of those two operations is the same as the result of a call to rename(2).

File ownership and permissions

The system calls chmod, chown and chgrp are used to change the mode and ownership of a file. If the argument to chmod, chown or chgrp is a symbolic link, the mode and ownership of the referenced file rather than of the symbolic link itself will be changed (see ``Symbolic links''). In such cases, the link is followed.

Once a symbolic link has been created, its permissions cannot be changed. By default, the chown(1) and chgrp(1) commands change the owner and group of the referenced file. However, a new -h option enables the user to change the owner and group of the symbolic link itself. This is useful for removing files from sticky directories.