link() — Create a link to a file
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
POSIX.1 |
both |
Format
#define _POSIX_SOURCE
#include <unistd.h>
int link(const char *oldfile, const char *newname);
General description
Provides an alternative pathname for the existing file, so that the file can be accessed by either the old or the new name. link() creates a link from the pathname newname to an existing file, with the pathname oldfile. The link can be stored in the same directory as the original file or in a completely different one.
Links are allowed to files only, not to directories.
This is a hard link, which ensures the existence of a file even after its original name has been removed.
If link() successfully creates the link, it increments the link count of the file. The link count tells how many links there are to the file. At the same time, link() updates the change time of the file, and the change time and modification time of the directory that contains newname (that is, the directory that holds the link). If link() fails, the link count is not incremented.
If oldfile names a symbolic link, link() creates a link that refers to the file that results from resolving the pathname contained in the symbolic link. If newname names a symbolic link, link() fails and sets errno to EEXIST.
Returned value
If successful, link() returns 0.
- Error Code
- Description
- EACCES
- The process did not have appropriate permissions to create the link. Possible reasons include no search permission on a pathname component of oldfile or newname, no write permission on the directory intended to contain the link, or no permission to access oldfile.
- EEXIST
- Either newname refers to a symbolic link, or a file or directory with the name newname already exists.
- EINVAL
- Either oldfile or newname is incorrect, because it contains a NULL.
- ELOOP
- A loop exists in symbolic links. This error is issued if the number of symbolic links encountered during resolution of oldfile or newname is greater than POSIX_SYMLOOP.
- EMLINK
- oldfile already has its maximum number of links. The maximum number of links to a file is given by LINK_MAX, which you can determine by using pathconf() or fpathconf().
- ENAMETOOLONG
- oldfile or newname is longer than PATH_MAX, or a component of one of the pathnames is longer than NAME_MAX while _POSIX_NO_TRUNC is in effect. For symbolic links, the length of the pathname string substituted for a symbolic link in oldfile or newname exceeds PATH_MAX. The PATH_MAX and NAME_MAX values can be determined using pathconf().
- ENOENT
- A pathname component of oldfile or newname does not exist, or oldfile itself does not exist, or one of the two arguments is an empty string.
- ENOSPC
- The directory intended to contain the link cannot be extended to contain another entry.
- ENOTDIR
- A pathname component of one of the arguments is not a directory.
- EPERM
- oldfile is the name of a directory, and links to directories are not supported.
- EROFS
- Creating the link would require writing on a read-only file system.
- EXDEV
- oldfile and newname are on different file systems.
Example
#define _POSIX_SOURCE
#include <fcntl.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>
main() {
char fn[]="link.example.file";
char ln[]="link.example.link";
int fd;
if ((fd = creat(fn, S_IWUSR)) < 0)
perror("creat() error");
else {
close(fd);
if (link(fn, ln) != 0) {
perror("link() error");
unlink(fn);
}
else {
unlink(fn);
unlink(ln);
}
}
}