linkat • man page

link ,linkat - make a hard file link

linkat • man page

link ,linkat - make a hard file link

linkat (2)

Leading comments

Copyright (c) 1980, 1991, 1993
The Regents of the University of California. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the fol...

(The comments found at the beginning of the groff file "man2/linkat.2freebsd".)

NAME

linklinkat
- make a hard file link

LIBRARY

Lb libc

SYNOPSIS

DESCRIPTION

The
Fn link
system call
atomically creates the specified directory entry (hard link)
Fa name2
with the attributes of the underlying object pointed at by
Fa name1 .
If the link is successful: the link count of the underlying object
is incremented;
Fa name1
and
Fa name2
share equal access and rights
to the
underlying object.

If
Fa name1
is removed, the file
Fa name2
is not deleted and the link count of the
underlying object is
decremented.

The object pointed at by the
Fa name1
argument
must exist for the hard link to
succeed and
both
Fa name1
and
Fa name2
must be in the same file system.
The
Fa name1
argument
may not be a directory.

The
Fn linkat
system call is equivalent to
Fa link
except in the case where either
Fa name1
or
Fa name2
or both are relative paths.
In this case a relative path
Fa name1
is interpreted relative to
the directory associated with the file descriptor
Fa fd1
instead of the current working directory and similarly for
Fa name2
and the file descriptor
Fa fd2 .

Values for
Fa flag
are constructed by a bitwise-inclusive OR of flags from the following
list, defined in
In fcntl.h :

AT_SYMLINK_FOLLOW

If
Fa name1
names a symbolic link, a new link for the target of the symbolic link is
created.

If
Fn linkat
is passed the special value
AT_FDCWD
in the
Fa fd1
or
Fa fd2
parameter, the current working directory is used for the respective
Fa name
argument.
If both
Fa fd1
and
Fa fd2
have value
AT_FDCWD
the behavior is identical to a call to
Fn link .
Unless
Fa flag
contains the
AT_SYMLINK_FOLLOW
flag, if
Fa name1
names a symbolic link, a new link is created for the symbolic link
Fa name1
and not its target.

RETURN VALUES

Rv -std link

ERRORS

The
Fn link
system call
will fail and no link will be created if:

Bq Er ENOTDIR

A component of either path prefix is not a directory.

Bq Er ENAMETOOLONG

A component of either pathname exceeded 255 characters,
or entire length of either path name exceeded 1023 characters.

Bq Er ENOENT

A component of either path prefix does not exist.

Bq Er EOPNOTSUPP

The file system containing the file named by
Fa name1
does not support links.

Bq Er EMLINK

The link count of the file named by
Fa name1
would exceed 32767.

Bq Er EACCES

A component of either path prefix denies search permission.

Bq Er EACCES

The requested link requires writing in a directory with a mode
that denies write permission.

Bq Er ELOOP

Too many symbolic links were encountered in translating one of the pathnames.

Bq Er ENOENT

The file named by
Fa name1
does not exist.

Bq Er EEXIST

The link named by
Fa name2
does exist.

Bq Er EPERM

The file named by
Fa name1
is a directory.

Bq Er EPERM

The file named by
Fa name1
has its immutable or append-only flag set, see the
chflags(2)
manual page for more information.

Bq Er EPERM

The parent directory of the file named by
Fa name2
has its immutable flag set.

Bq Er EXDEV

The link named by
Fa name2
and the file named by
Fa name1
are on different file systems.

Bq Er ENOSPC

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.

Bq Er EDQUOT

The directory in which the entry for the new link
is being placed cannot be extended because the
user's quota of disk blocks on the file system
containing the directory has been exhausted.

Bq Er EIO

An I/O error occurred while reading from or writing to
the file system to make the directory entry.

Bq Er EROFS

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

Bq Er EFAULT

One of the pathnames specified
is outside the process's allocated address space.

In addition to the errors returned by the
Fn link ,
the
Fn linkat
system call may fail if:

Bq Er EBADF

The
Fa name1
or
Fa name2
argument does not specify an absolute path and the
Fa fd1
or
Fa fd2
argument, respectively, is neither
AT_FDCWD
nor a valid file descriptor open for searching.

Bq Er EINVAL

The value of the
Fa flag
argument is not valid.

Bq Er ENOTDIR

The
Fa name1
or
Fa name2
argument is not an absolute path and
Fa fd1
or
Fa fd2 ,
respectively, is neither
AT_FDCWD
nor a file descriptor associated with a directory.