Symbolic Links

The GNU system supports soft links or symbolic links. This is a kind of "file" that is essentially a pointer to another file name. Unlike hard links, symbolic links can be made to directories or across file systems with no restrictions. You can also make a symbolic link to a name which is not the name of any file. (Opening this link will fail until a file by that name is created.) Likewise, if the symbolic link points to an existing file which is later deleted, the symbolic link continues to point to the same file name even though the name no longer names any file.

The reason symbolic links work the way they do is that special things happen when you try to open the link. The open function realizes you have specified the name of a link, reads the file name contained in the link, and opens that file name instead. The stat function likewise operates on the file that the symbolic link points to, instead of on the link itself.

By contrast, other operations such as deleting or renaming the file operate on the link itself. The functions readlink and lstat also refrain from following symbolic links, because their purpose is to obtain information about the link. So does link, the function that makes a hard link--it makes a hard link to the symbolic link, which one rarely wants.

Prototypes for the functions listed in this section are in `unistd.h'.

Function: int symlink (const char *oldname, const char *newname)

The symlink function makes a symbolic link to oldname named newname.

The normal return value from symlink is 0. A return value of -1 indicates an error. In addition to the usual file name syntax errors (see section File Name Errors), the following errno error conditions are defined for this function:

EEXIST

There is already an existing file named newname.

EROFS

The file newname would exist on a read-only file system.

ENOSPC

The directory or file system cannot be extended to make the new link.

EIO

A hardware error occurred while reading or writing data on the disk.

Function: int readlink (const char *filename, char *buffer, size_t size)

The readlink function gets the value of the symbolic link filename. The file name that the link points to is copied into buffer. This file name string is not null-terminated; readlink normally returns the number of characters copied. The size argument specifies the maximum number of characters to copy, usually the allocation size of buffer.

If the return value equals size, you cannot tell whether or not there was room to return the entire name. So make a bigger buffer and call readlink again. Here is an example:

char *
readlink_malloc (char *filename)
{
  int size = 100;

  while (1)
    {
      char *buffer = (char *) xmalloc (size);
      int nchars = readlink (filename, buffer, size);
      if (nchars < size)
        return buffer;
      free (buffer);
      size *= 2;
    }
}

A value of -1 is returned in case of error. In addition to the usual file name errors (see section File Name Errors), the following errno error conditions are defined for this function:

EINVAL

The named file is not a symbolic link.

EIO

A hardware error occurred while reading or writing data on the disk.

Go to the first, previous, next, last section, table of contents.