Reformatting page.  Please Wait... done


System Calls                                            UNLINK(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.


     If the path argument is a directory and the filesystem  sup-
     ports  unlink() and unlinkat() on directories, the directory
     is unlinked from its parent with no cleanup being performed.
     In  UFS,  the  disconnected directory will be found the next


Illumos             Last change: May 18, 2007                   1


System Calls                                            UNLINK(2)


     time the filesystem is checked with fsck(1M).  The  unlink()
     and  unlinkat()  functions  will  not  fail simply because a
     directory is not empty. The user with appropriate privileges
     can orphan a non-empty directory without generating an error
     message.


     If the path argument is a directory and the filesystem  does
     not  support unlink() and unlink() on directories (for exam-
     ple, ZFS), the call will fail with errno set to EPERM.


     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, or write permission is
                     denied on the directory containing the  link
                     to be removed.


     EACCES
                     The parent directory has the sticky bit  set
                     and  the  file  is not writable by the user,
                     the user does not own the parent  directory,
                     the user does not own the file, and the user
                     is not a privileged user.


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


     EFAULT
                     The  path  argument  points  to  an  illegal
                     address.


     EILSEQ
                     The   path   argument   includes    non-UTF8


Illumos             Last change: May 18, 2007                   2


System Calls                                            UNLINK(2)


                     characters  and the file system accepts only
                     file names where all characters are part  of
                     the UTF-8 character codeset.


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


     ELOOP
                     Too many symbolic links were encountered  in
                     translating 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 descrip-
                     tor for unlinkat() is not AT_FDCWD  or  does
                     not reference a directory.


     EPERM
                     The  named   file   is   a   directory   and
                     {PRIV_SYS_LINKDIR}  is  not  asserted in the
                     effective set of the calling process, or the
                     filesystem  implementation  does not support
                     unlink() or unlinkat() on directories.


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


Illumos             Last change: May 18, 2007                   3


System Calls                                            UNLINK(2)


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

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


     ETXTBSY
                     The entry to be unlinked is the last  direc-
                     tory 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)privileges(5)fsattr(5)


Illumos             Last change: May 18, 2007                   4