Symbolic Links

Symbolic links solve the thorny problem of providing a link to a file on another file system. They represent a file system "re-director" of sorts. In order to allow programs to work with symbolic links, the UNIX kernel provides a few system calls specific to symbolic links.

The symlink(2) Function

The symlink(2) function permits the caller to create a symbolic link, as opposed to a hard link that is created by link(2). The synopsis for symlink(2) is as follows:

#include <unistd.h>

int symlink(const char *path, const char *symlnk);

The symbolic link named by the argument symlnk is created to point to the pathname provided by the argument path. The function returns 0 if successful; otherwise -1 and a value for errno are returned. The pathname in path does not need to exist already.

The following example shows how a symbolic link named my_hosts can be created to point to the file /etc/hosts:

if ( symlink("/etc/hosts","./my_hosts") == -1 )
    /* Report error */
else
    /* Success */

FreeBSD has an extensive man(1) page describing how symbolic links work, in section seven, symlink(7).

The lstat(2) Function

There are times when your program may need status information about the symbolic link, rather than the file it points to. The lstat(2) function fills this need:

#include <sys/types.h>
#include <sys/stat.h>

int lstat(const char *path, struct stat *sb);

The structure sb is filled with the same type of information that is provided for stat(2) and fstat(2). The difference, of course, is that the information is returned for the symbolic link itself. The function returns 0 when successful; otherwise -1 and a value for errno are returned instead.

Reading the Contents of the Symbolic Link with readlink(2)

In order to determine what an existing symbolic link points to, you call upon the function readlink(2):

#include <unistd.h>

int readlink(const char *path, char *buf, int bufsiz);

The symbolic link of interest is provided in the argument path. The buffer pointer buf indicates where the symbolic link information should be returned. The argument bufsiz indicates the maximum number of bytes that can be returned by readlink(2).

The value returned by readlink(2) is the number of characters that were placed into the buffer buf. There is no null byte returned by readlink(2). If an error occurred, -1 is returned and errno holds the error code. The following example shows how to report the link information for symbolic link my_symlink:

int z;
char buf[1024];

z = readlink("my_symlink",buf,sizeof buf-1);
if ( z == -1 )
    /* Report error */
else {
    /* Success */
    buf[z] = 0;    /* Null terminate */
    printf("symlink is '%s'
",buf);
}

Notice how the null byte has to be added by the caller, since readlink(2) does not provide one.