Technical Reference: Base Operating System and Extensions, Volume 1

link Subroutine

Purpose

Creates an additional directory entry for an existing file.

Library

Standard C Library (libc.a)

Syntax

#include <unistd.h>

int link ( Path1, Path2) const char *Path1, *Path2;

Description

The link subroutine creates an additional hard link (directory entry) for an existing file. Both the old and the new links share equal access rights to the underlying object.

Parameters

Path1	Points to the path name of an existing file.
Path2	Points to the path name of the directory entry to be created.

Notes:

If Network File System (NFS) is installed on your system, these paths can cross into another node.
With hard links, both the Path1 and Path2 parameters must reside on the same file system. If Path1 is a symbolic link, an error is returned. Creating links to directories requires root user authority.

Return Values

Upon successful completion, the link subroutine returns a value of 0. Otherwise, a value of -1 is returned, and the errno global variable is set to indicate the error.

Error Codes

The link subroutine is unsuccessful if one of the following is true:

EACCES	Indicates the requested link requires writing in a directory that denies write permission.
EDQUOT	Indicates the directory in which the entry for the new link is being placed cannot be extended, or disk blocks could not be allocated for the link because the user or group quota of disk blocks or i-nodes on the file system containing the directory has been exhausted.
EEXIST	Indicates the link named by the Path2 parameter already exists.
EMLINK	Indicates the file already has the maximum number of links.
ENOENT	Indicates the file named by the Path1 parameter does not exist.
ENOSPC	Indicates the directory in which the entry for the new link is being placed cannot be extended because there is no space left on the file system containing the directory.
EPERM	Indicates the file named by the Path1 parameter is a directory, and the calling process does not have root user authority.
EROFS	Indicates the requested link requires writing in a directory on a read-only file system.
EXDEV	Indicates the link named by the Path2 parameter and the file named by the Path1 parameter are on different file systems, or the file named by Path1 refers to a named STREAM.

The link subroutine can be unsuccessful for other reasons. See Appendix A, Base Operating System Error Codes for Services That Require Path-Name Resolution for a list of additional errors.

If NFS is installed on the system, the link subroutine is unsuccessful if the following is true:

ETIMEDOUT

Indicates the connection timed out.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The symlink subroutine, unlink subroutine.

The link or unlink command, ln command, rm command.

Files, Directories, and File Systems for Programmers in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.