1LINK(3P)                   POSIX Programmer's Manual                  LINK(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       link, linkat — link one file to another file relative to two  directory
14       file descriptors
15

SYNOPSIS

17       #include <unistd.h>
18
19       int link(const char *path1, const char *path2);
20       int linkat(int fd1, const char *path1, int fd2,
21           const char *path2, int flag);
22

DESCRIPTION

24       The  link()  function shall create a new link (directory entry) for the
25       existing file, path1.
26
27       The path1 argument points to a pathname naming an  existing  file.  The
28       path2  argument  points to a pathname naming the new directory entry to
29       be created. The link() function shall atomically create a new link  for
30       the  existing  file and the link count of the file shall be incremented
31       by one.
32
33       If path1 names a directory, link() shall fail unless  the  process  has
34       appropriate  privileges and the implementation supports using link() on
35       directories.
36
37       If path1 names a symbolic link, it  is  implementation-defined  whether
38       link() follows the symbolic link, or creates a new link to the symbolic
39       link itself.
40
41       Upon successful completion, link() shall mark for update the last  file
42       status  change  timestamp of the file. Also, the last data modification
43       and last file status change timestamps of the directory  that  contains
44       the new entry shall be marked for update.
45
46       If  link()  fails,  no  link shall be created and the link count of the
47       file shall remain unchanged.
48
49       The implementation may require that the calling process has  permission
50       to access the existing file.
51
52       The linkat() function shall be equivalent to the link() function except
53       that symbolic links shall be handled as specified by the value of  flag
54       (see  below) and except in the case where either path1 or path2 or both
55       are relative paths. In this case a relative path path1  is  interpreted
56       relative  to  the  directory  associated  with  the file descriptor fd1
57       instead of the current working directory and similarly  for  path2  and
58       the  file  descriptor  fd2.   If the file descriptor was opened without
59       O_SEARCH, the function shall check whether directory searches are  per‐
60       mitted  using  the  current permissions of the directory underlying the
61       file descriptor. If the file descriptor was opened with  O_SEARCH,  the
62       function shall not perform the check.
63
64       Values for flag are constructed by a bitwise-inclusive OR of flags from
65       the following list, defined in <fcntl.h>:
66
67       AT_SYMLINK_FOLLOW
68             If path1 names a symbolic link, a new link for the target of  the
69             symbolic link is created.
70
71       If  linkat()  is  passed  the  special value AT_FDCWD in the fd1 or fd2
72       parameter, the current working directory shall be used for the  respec‐
73       tive path argument. If both fd1 and fd2 have value AT_FDCWD, the behav‐
74       ior shall be identical to a call to link(), except that symbolic  links
75       shall be handled as specified by the value of flag.
76
77       If  the  AT_SYMLINK_FOLLOW  flag  is clear in the flag argument and the
78       path1 argument names a symbolic link, a new link  is  created  for  the
79       symbolic link path1 and not its target.
80

RETURN VALUE

82       Upon  successful completion, these functions shall return 0. Otherwise,
83       these functions shall return −1 and set errno to indicate the error.
84

ERRORS

86       These functions shall fail if:
87
88       EACCES A component of either path prefix denies search  permission,  or
89              the  requested  link requires writing in a directory that denies
90              write permission, or the calling process does not  have  permis‐
91              sion  to  access  the  existing file and this is required by the
92              implementation.
93
94       EEXIST The path2 argument resolves to an existing  directory  entry  or
95              refers to a symbolic link.
96
97       ELOOP  A loop exists in symbolic links encountered during resolution of
98              the path1 or path2 argument.
99
100       EMLINK The number of links to the file  named  by  path1  would  exceed
101              {LINK_MAX}.
102
103       ENAMETOOLONG
104              The  length  of  a  component  of  a  pathname  is  longer  than
105              {NAME_MAX}.
106
107       ENOENT A component of either path prefix does not exist; the file named
108              by  path1  does  not exist; or path1 or path2 points to an empty
109              string.
110
111       ENOSPC The directory to contain the link cannot be extended.
112
113       ENOTDIR
114              A component of either path prefix names an existing file that is
115              neither  a  directory nor a symbolic link to a directory, or the
116              path1 argument contains at least one non-<slash>  character  and
117              ends  with  one or more trailing <slash> characters and the last
118              pathname component names an existing  file  that  is  neither  a
119              directory nor a symbolic link to a directory, or the path1 argu‐
120              ment names an existing non-directory file and the path2 argument
121              names  a  nonexistent  file,  contains  at least one non-<slash>
122              character, and ends with one or more  trailing  <slash>  charac‐
123              ters.
124
125       EPERM  The  file  named  by path1 is a directory and either the calling
126              process does not have appropriate privileges or the  implementa‐
127              tion prohibits using link() on directories.
128
129       EROFS  The  requested  link  requires writing in a directory on a read-
130              only file system.
131
132       EXDEV  The link named by path2 and the file named by path1 are on  dif‐
133              ferent  file  systems  and  the  implementation does not support
134              links between file systems.
135
136       EXDEV  path1 refers to a named STREAM.
137
138       The linkat() function shall fail if:
139
140       EBADF  The path1 or path2 argument does not specify  an  absolute  path
141              and  the  fd1 or fd2 argument, respectively, is neither AT_FDCWD
142              nor a valid file descriptor open for reading or searching.
143
144       ENOTDIR
145              The path1 or path2 argument is not an absolute path and  fd1  or
146              fd2,  respectively,  is a file descriptor associated with a non-
147              directory file.
148
149       These functions may fail if:
150
151       ELOOP  More than {SYMLOOP_MAX} symbolic links were  encountered  during
152              resolution of the path1 or path2 argument.
153
154       ENAMETOOLONG
155              The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
156              tion of a symbolic link produced an intermediate result  with  a
157              length that exceeds {PATH_MAX}.
158
159       The linkat() function may fail if:
160
161       EINVAL The value of the flag argument is not valid.
162
163       The following sections are informative.
164

EXAMPLES

166   Creating a Link to a File
167       The  following  example  shows  how  to  create  a link to a file named
168       /home/cnd/mod1 by creating a new directory entry named /modules/pass1.
169
170           #include <unistd.h>
171
172           char *path1 = "/home/cnd/mod1";
173           char *path2 = "/modules/pass1";
174           int   status;
175           ...
176           status = link (path1, path2);
177
178   Creating a Link to a File Within a Program
179       In the  following  program  example,  the  link()  function  links  the
180       /etc/passwd  file  (defined as PASSWDFILE) to a file named /etc/opasswd
181       (defined as SAVEFILE), which is used to save the current password file.
182       Then, after removing the current password file (defined as PASSWDFILE),
183       the new password file is saved as the current password file  using  the
184       link() function again.
185
186           #include <unistd.h>
187
188           #define LOCKFILE "/etc/ptmp"
189           #define PASSWDFILE "/etc/passwd"
190           #define SAVEFILE "/etc/opasswd"
191           ...
192           /* Save current password file */
193           link (PASSWDFILE, SAVEFILE);
194
195           /* Remove current password file. */
196           unlink (PASSWDFILE);
197
198           /* Save new password file as current password file. */
199           link (LOCKFILE,PASSWDFILE);
200

APPLICATION USAGE

202       Some implementations do allow links between file systems.
203
204       If  path1  refers to a symbolic link, application developers should use
205       linkat() with appropriate flags to select whether or not  the  symbolic
206       link should be resolved.
207

RATIONALE

209       Linking  to a directory is restricted to the superuser in most histori‐
210       cal implementations because this capability may produce  loops  in  the
211       file  hierarchy  or  otherwise  corrupt the file system. This volume of
212       POSIX.1‐2008  continues  that  philosophy  by  prohibiting  link()  and
213       unlink()  from doing this. Other functions could do it if the implemen‐
214       tor designed such an extension.
215
216       Some historical implementations allow linking  of  files  on  different
217       file  systems.  Wording  was  added  to  explicitly allow this optional
218       behavior.
219
220       The exception for cross-file system links is intended to apply only  to
221       links that are programmatically indistinguishable from ``hard'' links.
222
223       The  purpose  of  the linkat() function is to link files in directories
224       other than the current working directory without exposure to race  con‐
225       ditions. Any part of the path of a file could be changed in parallel to
226       a call to link(), resulting in unspecified behavior. By opening a  file
227       descriptor  for  the directory of both the existing file and the target
228       location and using the linkat() function it can be guaranteed that  the
229       both filenames are in the desired directories.
230
231       The  AT_SYMLINK_FOLLOW  flag allows for implementing both common behav‐
232       iors of the link() function. The POSIX specification requires  that  if
233       path1  is  a  symbolic  link, a new link for the target of the symbolic
234       link is created. Many systems by default or as an alternative provide a
235       mechanism  to  avoid the implicit symbolic link lookup and create a new
236       link for the symbolic link itself.
237
238       Earlier versions of this standard specified only the  link()  function,
239       and  required  it  to  behave  like linkat() with the AT_SYMLINK_FOLLOW
240       flag. However, historical practice from  SVR4  and  Linux  kernels  had
241       link()  behaving  like  linkat()  with  no flags, and many systems that
242       attempted to provide a conforming link() function did so in a way  that
243       was  rarely  used, and when it was used did not conform to the standard
244       (e.g., by not being atomic,  or  by  dereferencing  the  symbolic  link
245       incorrectly).  Since  applications  could  not rely on link() following
246       links in practice, the linkat() function was added  taking  a  flag  to
247       specify the desired behavior for the application.
248

FUTURE DIRECTIONS

250       None.
251

SEE ALSO

253       rename(), symlink(), unlink()
254
255       The Base Definitions volume of POSIX.1‐2008, <fcntl.h>, <unistd.h>
256
258       Portions  of  this text are reprinted and reproduced in electronic form
259       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
260       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
261       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
262       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
263       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
264       event of any discrepancy between this version and the original IEEE and
265       The Open Group Standard, the original IEEE and The Open Group  Standard
266       is  the  referee document. The original Standard can be obtained online
267       at http://www.unix.org/online.html .
268
269       Any typographical or formatting errors that appear  in  this  page  are
270       most likely to have been introduced during the conversion of the source
271       files to man page format. To report such errors,  see  https://www.ker
272       nel.org/doc/man-pages/reporting_bugs.html .
273
274
275
276IEEE/The Open Group                  2013                             LINK(3P)
Impressum