Create a link to an existing file
Synopsis:
#include <unistd.h>
int link( const char* existing,
const char* new );
Arguments:
- existing
- The path of an existing file.
- new
- The path for the new link.
Library:
libc
Use the -l c option to
qcc
to link against this library.
This library is usually included automatically.
Description:
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.
Note:
This implementation doesn't support using link() on
directories or the linking of files across filesystems (different
logical disks).
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.
If the function fails, no link is created, and the link count of the file remains unchanged.
Returns:
- 0
- Success.
- -1
- An error occurred (errno
is set).
Errors:
- EACCES
- One of the following occurred:
- A component of either path prefix denies search permission.
- The
link named by new is in a directory with a mode that denies
write permission.
- (QNX Neutrino 6.6 or later) You don't have read permission for the existing file.
- EEXIST
- The link named by new already exists.
- ELOOP
- There are too many levels of symbolic links or prefixes.
- EMLINK
- The number of links to the 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
- This error code can mean the following:
- A component of either path prefix doesn't exist.
- The file named by existing doesn't exist.
- Either existing or new points to an empty string.
- ENOSPC
- The directory that would contain the link can't be extended.
- ENOSYS
- The link() function isn't implemented for the filesystem underlying
the path specified in existing or new.
- ENOTDIR
- A component of either path prefix isn't 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>
int main( int argc, char** argv )
{
/* Create a link of argv[1] to argv[2].
*/
if( link( argv[1], argv[2] ) == -1 ) {
perror( "link" );
return( EXIT_FAILURE );
}
if( unlink( argv[1] ) == -1 ) {
perror( argv[1] );
return( EXIT_FAILURE );
}
return( EXIT_SUCCESS );
}
Classification:
POSIX 1003.1
Safety: |
|
Cancellation point |
Yes |
Interrupt handler |
No |
Signal handler |
Yes |
Thread |
Yes |