1 UNLINK(2)                        System Calls                        UNLINK(2)
   2 
   3 
   4 
   5 NAME
   6        unlink, unlinkat - remove directory entry
   7 
   8 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 
  17 DESCRIPTION
  18        The unlink() function removes a link to a file. If path names a
  19        symbolic link, unlink() removes the symbolic link named by path and
  20        does not affect any file or directory named by the contents of the
  21        symbolic link.  Otherwise, unlink() removes the link named by the
  22        pathname pointed to by path and decrements the link count of the file
  23        referenced 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
  30        argument is unused. If path is relative and dirfd has the value
  31        AT_FDCWD, defined in <fcntl.h>, unlinkat() also behaves the same   as
  32        unlink().  Otherwise, path is resolved relative to the directory
  33        referenced by the 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
  38        processing 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 
  68 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 
  72 ERRORS
  73        The unlink() and unlinkat() functions will fail if:
  74 
  75        EACCES
  76                        Search permission is denied for a component of the path
  77                        prefix, or write permission is denied on the directory
  78                        containing the link to be removed.
  79 
  80 
  81        EACCES
  82                        The parent directory has the sticky bit set and the
  83                        file is not writable by the user, the user does not own
  84                        the parent directory, the user does not own the file,
  85                        and the user is not a privileged user.
  86 
  87 
  88        EBUSY
  89                        The entry to be unlinked is the mount point for a
  90                        mounted file system.
  91 
  92 
  93        EEXIST
  94                        The entry to be unlinked is a directory which is not
  95                        empty.
  96 
  97 
  98        EFAULT
  99                        The path argument points to an illegal address.
 100 
 101 
 102        EILSEQ
 103                        The path argument includes non-UTF8 characters and the
 104                        file system accepts only file names where all
 105                        characters are part of the UTF-8 character codeset.
 106 
 107 
 108        EINTR
 109                        A signal was caught during the execution of the
 110                        unlink() function.
 111 
 112 
 113        ELOOP
 114                        Too many symbolic links were encountered in translating
 115                        path.
 116 
 117 
 118        ENAMETOOLONG
 119                        The length of the path argument exceeds PATH_MAX, or
 120                        the length of a path component exceeds NAME_MAX while
 121                        _POSIX_NO_TRUNC is in effect.
 122 
 123 
 124        ENOENT
 125                        The named file does not exist or is a null pathname.
 126 
 127 
 128        ENOLINK
 129                        The path argument points to a remote machine and the
 130                        link to that machine is no longer active.
 131 
 132 
 133        ENOTDIR
 134                        A component of the path prefix is not a directory or
 135                        the provided directory descriptor for unlinkat() is not
 136                        AT_FDCWD or does not reference a directory.
 137 
 138 
 139        EPERM
 140                        The named file is a directory and {PRIV_SYS_LINKDIR} is
 141                        not asserted in the effective set of the calling
 142                        process, or the filesystem implementation does not
 143                        support unlink() or unlinkat() on directories.
 144 
 145 
 146        EROFS
 147                        The directory entry to be unlinked is part of a read-
 148                        only file system.
 149 
 150 
 151 
 152        The unlink() and unlinkat() functions may fail if:
 153 
 154        ENAMETOOLONG
 155                        Pathname resolution of a symbolic link produced an
 156                        intermediate result whose length exceeds {PATH_MAX}.
 157 
 158 
 159        ETXTBSY
 160                        The entry to be unlinked is the last directory entry to
 161                        a pure procedure (shared text) file that is being
 162                        executed.
 163 
 164 
 165 USAGE
 166        Applications should use rmdir(2) to remove a directory.
 167 
 168 ATTRIBUTES
 169        See attributes(5) for descriptions of the following attributes:
 170 
 171 
 172 
 173 
 174        +--------------------+----------------------------------------------+
 175        |  ATTRIBUTE TYPE    |               ATTRIBUTE VALUE                |
 176        +--------------------+----------------------------------------------+
 177        |Interface Stability | unlink() is Standard; unlinkat() is Evolving |
 178        +--------------------+----------------------------------------------+
 179        |MT-Level            | Async-Signal-Safe                            |
 180        +--------------------+----------------------------------------------+
 181 
 182 SEE ALSO
 183        rm(1), close(2), link(2), open(2), rmdir(2), remove(3C), attributes(5),
 184        privileges(5), fsattr(5)
 185 
 186 
 187 
 188                                December 7, 2016                      UNLINK(2)