1unlink(2)                        System Calls                        unlink(2)
2
3
4

NAME

6       unlink, unlinkat - remove directory entry
7

SYNOPSIS

9       #include <unistd.h>
10
11       int unlink(const char *path);
12
13
14       int unlinkat(int dirfd, const char *path, int flag);
15
16

DESCRIPTION

18       The  unlink()  function  removes a link to a file. If path names a sym‐
19       bolic link, unlink() removes the symbolic link named by path  and  does
20       not  affect any file or directory named by the contents of the symbolic
21       link.  Otherwise, unlink() removes  the  link  named  by  the  pathname
22       pointed to by path and decrements the link count of the file referenced
23       by the link.
24
25
26       The unlinkat() function also removes a link to a file.  See  fsattr(5).
27       If  the  flag  argument is 0, the behavior of unlinkat() is the same as
28       unlink() except in the processing of its  path  argument.  If  path  is
29       absolute,  unlinkat()  behaves the same as unlink() and the dirfd argu‐
30       ment is unused. If path is relative and dirfd has the  value  AT_FDCWD,
31       defined  in  <fcntl.h>,  unlinkat()  also behaves the same as unlink().
32       Otherwise, path is resolved relative to the directory referenced by the
33       dirfd argument.
34
35
36       If  the  flag  argument  is  set  to the value AT_REMOVEDIR, defined in
37       <fcntl.h>, unlinkat() behaves the same as rmdir(2) except in  the  pro‐
38       cessing of the path argument as described above.
39
40
41       When  the file's link count becomes 0 and no process has the file open,
42       the space occupied by the file will be freed and the file is no  longer
43       accessible.  If  one or more processes have the file open when the last
44       link is removed, the link is  removed  before  unlink()  or  unlinkat()
45       returns,  but  the  removal of the file contents is postponed until all
46       references to the file are closed.
47
48
49       If the path  argument  is  a  directory  and  the  filesystem  supports
50       unlink()  and unlinkat() on directories, the directory is unlinked from
51       its parent with no cleanup being performed.  In UFS,  the  disconnected
52       directory  will  be  found the next time the filesystem is checked with
53       fsck(1M). The unlink() and unlinkat() functions will  not  fail  simply
54       because  a directory is not empty. The user with appropriate privileges
55       can orphan a non-empty directory without generating an error message.
56
57
58       If the path argument is a directory and the filesystem does not support
59       unlink()  and unlink() on directories (for example, ZFS), the call will
60       fail with errno set to EPERM.
61
62
63       Upon successful completion,  unlink()  and  unlinkat()  will  mark  for
64       update  the  st_ctime  and st_mtime fields of the parent directory.  If
65       the file's link count is not 0, the st_ctime field of the file will  be
66       marked for update.
67

RETURN VALUES

69       Upon  successful completion, 0 is returned.  Otherwise, −1 is returned,
70       errno is set to indicate the error, and the file is not unlinked.
71

ERRORS

73       The unlink() and unlinkat() functions will fail if:
74
75       EACCES          Search permission is denied for a component of the path
76                       prefix,  or write permission is denied on the directory
77                       containing the link to be removed.
78
79
80       EACCES          The parent directory has the sticky  bit  set  and  the
81                       file is not writable by the user, the user does not own
82                       the parent directory, the user does not own  the  file,
83                       and the user is not a privileged user.
84
85
86       EBUSY           The  entry  to  be  unlinked  is  the mount point for a
87                       mounted file system.
88
89
90       EFAULT          The path argument points to an illegal address.
91
92
93       EILSEQ          The path argument includes non-UTF8 characters and  the
94                       file  system  accepts only file names where all charac‐
95                       ters are part of the UTF-8 character codeset.
96
97
98       EINTR           A  signal  was  caught  during  the  execution  of  the
99                       unlink() function.
100
101
102       ELOOP           Too many symbolic links were encountered in translating
103                       path.
104
105
106       ENAMETOOLONG    The length of the path argument  exceeds  PATH_MAX,  or
107                       the  length  of a path component exceeds NAME_MAX while
108                       _POSIX_NO_TRUNC is in effect.
109
110
111       ENOENT          The named file does not exist or is a null pathname.
112
113
114       ENOLINK         The path argument points to a remote  machine  and  the
115                       link to that machine is no longer active.
116
117
118       ENOTDIR         A  component  of  the path prefix is not a directory or
119                       the provided directory descriptor for unlinkat() is not
120                       AT_FDCWD or does not reference a directory.
121
122
123       EPERM           The named file is a directory and {PRIV_SYS_LINKDIR} is
124                       not asserted  in  the  effective  set  of  the  calling
125                       process, or the filesystem implementation does not sup‐
126                       port unlink() or unlinkat() on directories.
127
128
129       EROFS           The directory entry to be unlinked is part of  a  read-
130                       only file system.
131
132
133
134       The unlink() and unlinkat() functions may fail if:
135
136       ENAMETOOLONG    Pathname  resolution  of  a  symbolic  link produced an
137                       intermediate result whose length exceeds {PATH_MAX}.
138
139
140       ETXTBSY         The entry to be unlinked is the last directory entry to
141                       a  pure procedure (shared text) file that is being exe‐
142                       cuted.
143
144

USAGE

146       Applications should use rmdir(2) to remove a directory.
147

ATTRIBUTES

149       See attributes(5) for descriptions of the following attributes:
150
151
152
153
154       ┌─────────────────────────────┬─────────────────────────────┐
155       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
156       ├─────────────────────────────┼─────────────────────────────┤
157       │Interface Stability          │unlink()    is    Standard;  │
158       │                             │unlinkat() is Evolving       │
159       ├─────────────────────────────┼─────────────────────────────┤
160       │MT-Level                     │Async-Signal-Safe            │
161       └─────────────────────────────┴─────────────────────────────┘
162

SEE ALSO

164       rm(1), close(2), link(2), open(2), rmdir(2), remove(3C), attributes(5),
165       privileges(5), fsattr(5)
166
167
168
169SunOS 5.11                        18 May 2007                        unlink(2)
Impressum