link()

create a link to an existing file

Synopsis:

#include <unistd.h>
int link( const char *existing, const char *new );

The link() function creates a new directory entry named by new to refer to (that is, to be a link to) an existing file named by existing. The function atomically creates a new link for the existing file, and increments the link count of the file by one.

This implementation does not support using link() on directories or the linking of files across file systems (different logical disks).

If the function fails, no link is created, and the link count of the file remains unchanged.

If link() succeeds, the st_ctime field of the file and the st_ctime and st_mtime fields of the directory that contains the new entry are marked for update.

Returns:

0: Success
-1: An error occurred. errno is set to indicate the error.

Errors:

EACCES

A component of either path prefix denies search permission, or the link named by new is in a directory with a mode that denies write permission.

EEXIST

The link named by new already exists.

EMLINK

The number of links to the file file named by existing would exceed LINK_MAX.

ENAMETOOLONG

The length of the existing or new string exceeds PATH_MAX, or a pathname component is longer than NAME_MAX.

ENOENT

The error can mean the following:

A component of either path prefix does not exist
the file named by existing does not exist
either existing or new points to an empty string.

ENOSPC

The directory that would contain the link cannot be extended.

ENOTDIR

A component of either path prefix is not a directory.

EPERM

The file named by existing is a directory.

EROFS

The requested link requires writing in a directory on a read-only file system.

EXDEV

The link named by new and the file named by existing are on different logical disks.

Examples:

/*
 * The following program performs a rename
 * operation of argv[1] to argv[2].
 * Please note that this example,  unlike the
 * library function rename(), ONLY works if
 * argv[2] doesn't already exist.
 */
#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>

void main( int argc, char **argv )
  {
    /* create a link of argv[1] to argv[2].
     */
    if( link( argv[1], argv[2] ) == -1 ) {
      perror( "link" );
      exit( EXIT_FAILURE );
    }
    if( unlink( argv[1] ) == -1 ) {
      perror( argv[1] );
      exit( EXIT_FAILURE );
    }
    exit( EXIT_SUCCESS );
  }

Classification:

POSIX 1003.1

Safety:
Interrupt handler	No
Signal handler	Yes
Thread	No