| blob | e2b1f644d98f7703cc9fa0723cf5c13d6c07391b |
1 .\" $NetBSD: unlink.2,v 1.28 2013/07/28 13:53:04 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 .\" @(#)unlink.2 8.1 (Berkeley) 6/4/93
31 .\"
32 .Dd July 28, 2013
33 .Dt UNLINK 2
34 .Os
35 .Sh NAME
36 .Nm unlink ,
37 .Nm unlinkat ,
38 .Nd remove directory entry
39 .Sh LIBRARY
40 .Lb libc
41 .Sh SYNOPSIS
42 .In unistd.h
43 .Ft int
44 .Fn unlink "const char *path"
45 .In fcntl.h
46 .Ft int
47 .Fn unlinkat "int fd" "const char *path" "int flag"
48 .Sh DESCRIPTION
49 The
50 .Fn unlink
51 function
52 removes the link named by
53 .Fa path
54 from its directory and decrements the link count of the
55 file which was referenced by the link.
56 If that decrement reduces the link count of the file
57 to zero,
58 and no process has the file open, then
59 all resources associated with the file are reclaimed.
60 If one or more process have the file open when the last link is removed,
61 the link is removed, but the removal of the file is delayed until
62 all references to it have been closed.
63 .Pp
64 .Fn unlinkat
65 works the same way as
66 .Fn unlink
67 except if
68 .Fa path
69 is relative.
70 In that case, it is looked up from a directory whose file
71 descriptor was passed as
72 .Fa fd .
73 Search permission is required on this directory.
74 .\" (These alternatives await a decision about the semantics of O_SEARCH)
75 .\" Search permission is required on this directory
76 .\" except if
77 .\" .Fa fd
78 .\" was opened with the
79 .\" .Dv O_SEARCH
80 .\" flag.
81 .\" - or -
82 .\" This file descriptor must have been opened with the
83 .\" .Dv O_SEARCH
84 .\" flag.
85 .Fa fd
86 can be set to
87 .Dv AT_FDCWD
88 in order to specify the current directory.
89 .Pp
90 .Fn unlinkat
91 will remove directories just like
92 .Fn rmdir
93 provided
94 .Dv AT_REMOVEDIR
95 is set in
96 .Fa flag .
97 .Sh RETURN VALUES
98 .Rv -std unlink unlinkat
99 .Sh ERRORS
100 The
101 .Fn unlink
102 and
103 .Fn unlinkat
104 succeeds unless:
105 .Bl -tag -width Er
106 .It Bq Er EACCES
107 Search permission is denied for a component of the path prefix, or
108 write permission is denied on the directory containing the link
109 to be removed.
110 .It Bq Er EBUSY
111 The entry to be unlinked is the mount point for a
112 mounted file system.
113 .It Bq Er EFAULT
114 .Fa path
115 points outside the process's allocated address space.
116 .It Bq Er EIO
117 An I/O error occurred while deleting the directory entry
118 or deallocating the inode.
119 .It Bq Er ELOOP
120 Too many symbolic links were encountered in translating the pathname.
121 .It Bq Er ENAMETOOLONG
122 A component of a pathname exceeded
123 .Brq Dv NAME_MAX
124 characters, or an entire path name exceeded
125 .Brq Dv PATH_MAX
126 characters.
127 .It Bq Er ENOENT
128 The named file does not exist.
129 .It Bq Er ENOTDIR
130 A component of the path prefix is not a directory.
131 .It Bq Er EPERM
132 The named file is a directory and the effective user ID
133 of the process is not the super-user, the file system
134 containing the file does not permit the use of
135 .Fn unlink
136 on a directory,
137 or the directory containing the file is marked sticky,
138 and neither the containing directory nor the file to be removed
139 are owned by the effective user ID.
140 .It Bq Er EROFS
141 The named file resides on a read-only file system.
142 .El
143 .Pp
144 In addition,
145 .Fn unlinkat
146 will fail if:
147 .Bl -tag -width Er
148 .It Bq Er EBADF
149 .Fa path
150 does not specify an absolute path and
151 .Fa fd
152 is neither
153 .Dv AT_FDCWD
154 nor a valid file descriptor open for reading or searching.
155 .It Bq Er ENOTDIR
156 .Fa path
157 is not an absolute path and
158 .Fa fd
159 is a file descriptor associated with a non-directory file; or
160 .Fa flag
161 has
162 .Dv AT_REMOVEDIR
163 set and
164 .Fa path
165 does not name a directory.
166 .It Bq Er ENOTEMPTY
167 .Fa flag
168 has
169 .Dv AT_REMOVEDIR
170 set and
171 .Fa path
172 is a directory that is not empty.
173 .El
174 .Sh SEE ALSO
175 .Xr close 2 ,
176 .Xr link 2 ,
177 .Xr rmdir 2 ,
178 .Xr symlink 7
179 .Sh STANDARDS
180 The
181 .Fn unlink
182 function conforms to
183 .St -p1003.1-90 .
184 .Fn unlinkat
185 conforms to
186 .St -p1003.1-2008 .
187 .Sh HISTORY
188 An
189 .Fn unlink
190 function call appeared in
191 .At v2 .