unlinkat(2)

NAME

     unlink, unlinkat - remove directory entry

SYNOPSIS

     #include <unistd.h>

     int unlink(const char *path);

     int unlinkat(int dirfd, const char *path, int flag);

DESCRIPTION

     The unlink() function removes a link  to  a  file.  If  path
     names  a  symbolic  link, unlink() removes the symbolic link
     named by path and does not  affect  any  file  or  directory
     named by the contents of the symbolic link.
      Otherwise, unlink() removes the link named by the  pathname
     pointed to by path and decrements the link count of the file
     referenced by the link.

     The unlinkat() function also removes a link to a  file.  See
     fsattr(5). If the flag argument is 0, the behavior of unlin-
     kat() is the same as unlink() except in  the  processing  of
     its  path  argument. If path is absolute, unlinkat() behaves
     the same as unlink() and the dirfd argument  is  unused.  If
     path  is  relative and dirfd has the value AT_FDCWD, defined
     in <fcntl.h>, unlinkat() also behaves the same as  unlink().
     Otherwise, path is resolved relative to the directory refer-
     enced by the dirfd argument.

     If the flag argument  is  set  to  the  value  AT_REMOVEDIR,
     defined   in  <fcntl.h>,  unlinkat()  behaves  the  same  as
     rmdir(2) except in the processing of the  path  argument  as
     described above.

     When the file's link count becomes 0 and no process has  the
     file  open, the space occupied by the file will be freed and
     the file is no longer accessible. If one or  more  processes
     have  the  file open when the last link is removed, the link
     is removed before unlink() or unlinkat()  returns,  but  the
     removal  of  the file contents is postponed until all refer-
     ences to the file are closed.

     The path argument must not name a directory unless the  pro-
     cess  has appropriate privileges and the implementation sup-
     ports using unlink() and unlinkat() on directories.

     Upon successful completion,  unlink()  and  unlinkat()  will
     mark  for  update  the  st_ctime  and st_mtime fields of the
     parent directory.  If the file's link count is  not  0,  the
     st_ctime field of the file will be marked for update.

RETURN VALUES

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

ERRORS

     The unlink() and unlinkat() functions will fail if:

     EACCES
           Search permission is denied for  a  component  of  the
           path  prefix; write permission is denied on the direc-
           tory containing the link to  be  removed;  the  parent
           directory  has  the sticky bit set and the file is not
           writable by the user; or the user  does  not  own  the
           parent directory and the user does not own the file.

     EBUSY The entry to be unlinked is  the  mount  point  for  a
           mounted file system.

     EFAULT
           The path argument points to an illegal address.

     EINTR A signal  was  caught  during  the  execution  of  the
           unlink() function.

     ELOOP Too many symbolic links were encountered in  translat-
           ing path.

     ENAMETOOLONG
           The length of the path argument exceeds  PATH_MAX,  or
           the  length of a path component exceeds NAME_MAX while
           _POSIX_NO_TRUNC is in effect.

     ENOENT
           The named file does not exist or is a null pathname.

     ENOLINK
           The path argument points to a remote machine  and  the
           link to that machine is no longer active.

     ENOTDIR
           A component of the path prefix is not a  directory  or
           the  provided  directory  descriptor for unlinkat() is
           not AT_FDCWD or does not reference a directory.

     EPERM The named file is a directory and the  effective  user
           of the calling process is not superuser.

     EROFS The directory entry to be unlinked is part of a  read-
           only file system.

     The unlink() and unlinkat() functions may fail if:

     ENAMETOOLONG
           Pathname resolution of a  symbolic  link  produced  an
           intermediate result whose length exceeds {PATH_MAX}.

     ETXTBSY
           The entry to be unlinked is the last  directory  entry
           to  a  pure procedure (shared text) file that is being
           executed.

USAGE

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

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
   |        ATTRIBUTE TYPE       |        ATTRIBUTE VALUE      |
   | ____________________________|_____________________________|_
   |  Interface Stability        |  unlink()    is    Standard;|
   |                             |  unlinkat() is Evolving     |
   |_____________________________|_____________________________|
   | MT-Level                    | Async-Signal-Safe           |
   |_____________________________|_____________________________|

SEE ALSO

     rm(1), close(2),  link(2),  open(2),  rmdir(2),  remove(3C),
     attributes(5), fsattr(5)