1link(2)                       System Calls Manual                      link(2)
2
3
4

NAME

6       link, linkat - make a new name for a file
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <unistd.h>
13
14       int link(const char *oldpath, const char *newpath);
15
16       #include <fcntl.h>           /* Definition of AT_* constants */
17       #include <unistd.h>
18
19       int linkat(int olddirfd, const char *oldpath,
20                  int newdirfd, const char *newpath, int flags);
21
22   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
23
24       linkat():
25           Since glibc 2.10:
26               _POSIX_C_SOURCE >= 200809L
27           Before glibc 2.10:
28               _ATFILE_SOURCE
29

DESCRIPTION

31       link()  creates  a  new link (also known as a hard link) to an existing
32       file.
33
34       If newpath exists, it will not be overwritten.
35
36       This new name may be used exactly as the old  one  for  any  operation;
37       both names refer to the same file (and so have the same permissions and
38       ownership) and it is impossible to tell which name was the "original".
39
40   linkat()
41       The linkat() system call operates in exactly the same  way  as  link(),
42       except for the differences described here.
43
44       If  the  pathname  given in oldpath is relative, then it is interpreted
45       relative to the directory referred to by the file  descriptor  olddirfd
46       (rather  than  relative to the current working directory of the calling
47       process, as is done by link() for a relative pathname).
48
49       If oldpath is relative and olddirfd is the special value AT_FDCWD, then
50       oldpath is interpreted relative to the current working directory of the
51       calling process (like link()).
52
53       If oldpath is absolute, then olddirfd is ignored.
54
55       The interpretation of newpath is as for oldpath, except that a relative
56       pathname  is  interpreted  relative to the directory referred to by the
57       file descriptor newdirfd.
58
59       The following values can be bitwise ORed in flags:
60
61       AT_EMPTY_PATH (since Linux 2.6.39)
62              If oldpath is an empty string, create a link to the file  refer‐
63              enced  by  olddirfd  (which  may  have  been  obtained using the
64              open(2) O_PATH flag).  In this case, olddirfd can refer  to  any
65              type  of  file except a directory.  This will generally not work
66              if the file has a link count of zero (files created with  O_TMP‐
67              FILE and without O_EXCL are an exception).  The caller must have
68              the CAP_DAC_READ_SEARCH capability in order to  use  this  flag.
69              This  flag  is  Linux-specific; define _GNU_SOURCE to obtain its
70              definition.
71
72       AT_SYMLINK_FOLLOW (since Linux 2.6.18)
73              By default, linkat(), does not dereference oldpath if  it  is  a
74              symbolic  link (like link()).  The flag AT_SYMLINK_FOLLOW can be
75              specified in flags to cause oldpath to be dereferenced if it  is
76              a  symbolic  link.  If procfs is mounted, this can be used as an
77              alternative to AT_EMPTY_PATH, like this:
78
79                  linkat(AT_FDCWD, "/proc/self/fd/<fd>", newdirfd,
80                         newname, AT_SYMLINK_FOLLOW);
81
82       Before Linux 2.6.18, the flags argument was unused, and had to be spec‐
83       ified as 0.
84
85       See openat(2) for an explanation of the need for linkat().
86

RETURN VALUE

88       On  success,  zero is returned.  On error, -1 is returned, and errno is
89       set to indicate the error.
90

ERRORS

92       EACCES Write access to the directory containing newpath is  denied,  or
93              search  permission  is  denied for one of the directories in the
94              path prefix of  oldpath  or  newpath.   (See  also  path_resolu‐
95              tion(7).)
96
97       EDQUOT The  user's  quota of disk blocks on the filesystem has been ex‐
98              hausted.
99
100       EEXIST newpath already exists.
101
102       EFAULT oldpath or newpath points outside your accessible address space.
103
104       EIO    An I/O error occurred.
105
106       ELOOP  Too many symbolic links were encountered in resolving oldpath or
107              newpath.
108
109       EMLINK The  file  referred to by oldpath already has the maximum number
110              of links to it.  For example, on an ext4(5) filesystem that does
111              not  employ  the  dir_index  feature, the limit on the number of
112              hard links to a file is 65,000; on btrfs(5), the limit is 65,535
113              links.
114
115       ENAMETOOLONG
116              oldpath or newpath was too long.
117
118       ENOENT A directory component in oldpath or newpath does not exist or is
119              a dangling symbolic link.
120
121       ENOMEM Insufficient kernel memory was available.
122
123       ENOSPC The device containing the file has no room for the new directory
124              entry.
125
126       ENOTDIR
127              A component used as a directory in oldpath or newpath is not, in
128              fact, a directory.
129
130       EPERM  oldpath is a directory.
131
132       EPERM  The filesystem containing oldpath and newpath does  not  support
133              the creation of hard links.
134
135       EPERM (since Linux 3.6)
136              The  caller  does  not  have permission to create a hard link to
137              this   file   (see   the   description   of    /proc/sys/fs/pro‐
138              tected_hardlinks in proc(5)).
139
140       EPERM  oldpath    is    marked    immutable   or   append-only.    (See
141              ioctl_iflags(2).)
142
143       EROFS  The file is on a read-only filesystem.
144
145       EXDEV  oldpath and newpath are not  on  the  same  mounted  filesystem.
146              (Linux  permits  a  filesystem to be mounted at multiple points,
147              but link() does not work across different mounts,  even  if  the
148              same filesystem is mounted on both.)
149
150       The following additional errors can occur for linkat():
151
152       EBADF  oldpath (newpath) is relative but olddirfd (newdirfd) is neither
153              AT_FDCWD nor a valid file descriptor.
154
155       EINVAL An invalid flag value was specified in flags.
156
157       ENOENT AT_EMPTY_PATH was specified in flags, but  the  caller  did  not
158              have the CAP_DAC_READ_SEARCH capability.
159
160       ENOENT An  attempt was made to link to the /proc/self/fd/NN file corre‐
161              sponding to a file descriptor created with
162
163                  open(path, O_TMPFILE | O_EXCL, mode);
164
165              See open(2).
166
167       ENOENT An attempt was made to link to a  /proc/self/fd/NN  file  corre‐
168              sponding to a file that has been deleted.
169
170       ENOENT oldpath  is  a relative pathname and olddirfd refers to a direc‐
171              tory that has been deleted, or newpath is  a  relative  pathname
172              and newdirfd refers to a directory that has been deleted.
173
174       ENOTDIR
175              oldpath  is relative and olddirfd is a file descriptor referring
176              to a file other than a directory; or  similar  for  newpath  and
177              newdirfd
178
179       EPERM  AT_EMPTY_PATH  was  specified  in  flags,  oldpath  is  an empty
180              string, and olddirfd refers to a directory.
181

VERSIONS

183       POSIX.1-2001 says that link() should dereference oldpath  if  it  is  a
184       symbolic link.  However, since Linux 2.0, Linux does not do so: if old‐
185       path is a symbolic link, then newpath is created as a  (hard)  link  to
186       the  same  symbolic link file (i.e., newpath becomes a symbolic link to
187       the same file that oldpath refers to).  Some other implementations  be‐
188       have  in the same manner as Linux.  POSIX.1-2008 changes the specifica‐
189       tion of link(), making it implementation-dependent whether or not  old‐
190       path  is  dereferenced  if  it is a symbolic link.  For precise control
191       over the  treatment  of  symbolic  links  when  creating  a  link,  use
192       linkat().
193
194   glibc
195       On older kernels where linkat() is unavailable, the glibc wrapper func‐
196       tion falls back to the use of link(), unless the  AT_SYMLINK_FOLLOW  is
197       specified.  When oldpath and newpath are relative pathnames, glibc con‐
198       structs pathnames based on the symbolic  links  in  /proc/self/fd  that
199       correspond to the olddirfd and newdirfd arguments.
200

STANDARDS

202       link() POSIX.1-2008.
203

HISTORY

205       link() SVr4, 4.3BSD, POSIX.1-2001 (but see VERSIONS).
206
207       linkat()
208              POSIX.1-2008.  Linux 2.6.16, glibc 2.4.
209

NOTES

211       Hard  links,  as  created by link(), cannot span filesystems.  Use sym‐
212       link(2) if this is required.
213

BUGS

215       On NFS filesystems, the return code may be wrong in case the NFS server
216       performs  the link creation and dies before it can say so.  Use stat(2)
217       to find out if the link got created.
218

SEE ALSO

220       ln(1), open(2), rename(2), stat(2), symlink(2), unlink(2), path_resolu‐
221       tion(7), symlink(7)
222
223
224
225Linux man-pages 6.05              2023-03-30                           link(2)
Impressum