Standards
| Standards / Extensions |
C or C++ |
Dependencies |
|---|
POSIX.1
XPG4
XPG4.2
Single UNIX Specification, Version 3
|
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.
If unsuccessful, link() returns -1 and sets errno to one
of the following values:
- 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);
}
}
}