| blob | 7887dfa1885f5de7116e61269081f76dffd97268 |
1 .\" $NetBSD: link.2,v 1.24 2010/05/31 12:16:20 njoly Exp $
2 .\"
3 .\" Copyright (c) 1980, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)link.2 8.3 (Berkeley) 1/12/94
31 .\"
32 .Dd January 12, 1994
33 .Dt LINK 2
34 .Os
35 .Sh NAME
36 .Nm link
37 .Nd make a hard file link
38 .Sh LIBRARY
39 .Lb libc
40 .Sh SYNOPSIS
41 .In unistd.h
42 .Ft int
43 .Fn link "const char *name1" "const char *name2"
44 .Sh DESCRIPTION
45 The
46 .Fn link
47 function call
48 atomically creates the specified directory entry (hard link)
49 .Fa name2
50 with the attributes of the underlying object pointed at by
51 .Fa name1 .
52 If the link is successful: the link count of the underlying object
53 is incremented;
54 .Fa name1
55 and
56 .Fa name2
57 share equal access and rights
58 to the
59 underlying object.
60 .Pp
61 If
62 .Fa name1
63 is removed, the file
64 .Fa name2
65 is not deleted and the link count of the
66 underlying object is
67 decremented.
68 .Pp
69 .Fa name1
70 must exist for the hard link to
71 succeed and
72 both
73 .Fa name1
74 and
75 .Fa name2
76 must be in the same file system.
77 .Fa name1
78 may not be a directory unless the caller is the super-user
79 and the file system containing it supports linking to directories.
80 .Sh RETURN VALUES
81 Upon successful completion, a value of 0 is returned.
82 Otherwise, a value of \-1 is returned and
83 .Va errno
84 is set to indicate the error.
85 .Sh ERRORS
86 .Fn link
87 will fail and no link will be created if:
88 .Bl -tag -width Er
89 .It Bq Er ENOTDIR
90 A component of either path prefix is not a directory.
91 .It Bq Er ENAMETOOLONG
92 A component of a pathname exceeded
93 .Brq Dv NAME_MAX
94 characters, or an entire path name exceeded
95 .Brq Dv PATH_MAX
96 characters.
97 .It Bq Er ENOENT
98 A component of either path prefix does not exist.
99 .It Bq Er EACCES
100 A component of either path prefix denies search permission, or
101 the requested link requires writing in a directory with a mode
102 that denies write permission.
103 .It Bq Er ELOOP
104 Too many symbolic links were encountered in translating one of the pathnames.
105 .It Bq Er ENOENT
106 The file named by
107 .Fa name1
108 does not exist.
109 .It Bq Er EOPNOTSUPP
110 The file system containing the file named by
111 .Fa name1
112 does not support links.
113 .It Bq Er EMLINK
114 The link count of the file named by
115 .Fa name1
116 would exceed
117 .Dv {LINK_MAX} .
118 .It Bq Er EEXIST
119 The link named by
120 .Fa name2
121 does exist.
122 .It Bq Er EPERM
123 The file named by
124 .Fa name1
125 is a directory and the effective
126 user ID is not super-user,
127 or the file system containing the file does not permit the use of
128 .Fn link
129 on a directory.
130 .It Bq Er EXDEV
131 The link named by
132 .Fa name2
133 and the file named by
134 .Fa name1
135 are on different file systems.
136 .It Bq Er ENOSPC
137 The directory in which the entry for the new link is being placed
138 cannot be extended because there is no space left on the file
139 system containing the directory.
140 .It Bq Er EDQUOT
141 The directory in which the entry for the new link
142 is being placed cannot be extended because the
143 user's quota of disk blocks on the file system
144 containing the directory has been exhausted.
145 .It Bq Er EIO
146 An I/O error occurred while reading from or writing to
147 the file system to make the directory entry.
148 .It Bq Er EROFS
149 The requested link requires writing in a directory on a read-only file
150 system.
151 .It Bq Er EFAULT
152 One of the pathnames specified
153 is outside the process's allocated address space.
154 .El
155 .Sh SEE ALSO
156 .Xr symlink 2 ,
157 .Xr unlink 2
158 .Sh STANDARDS
159 The
160 .Fn link
161 function conforms to
162 .St -p1003.1-90 .