Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
unlink(2)			 System	Calls			     unlink(2)

       unlink, unlinkat	- remove directory entry

       #include	<unistd.h>

       int unlink(const	char *path);

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

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

       The unlinkat() function also removes a link to a	file.  See  fsattr(5).
       If  the	flag  argument is 0, the behavior of unlinkat()	is the same as
       unlink()	except in the processing of its	path argument. If path is  ab-
       solute,	unlinkat() behaves the same as unlink()	and the	dirfd argument
       is unused. If path is relative and dirfd	has the	 value	AT_FDCWD,  de-
       fined  in <fcntl.h>, unlinkat() also behaves the	same as	unlink(). Oth-
       erwise, path is resolved	relative to the	directory  referenced  by  the
       dirfd argument.

       If  the flag argument is	set to the value AT_REMOVEDIR, defined in <fc-
       ntl.h>, unlinkat() behaves the same as rmdir(2) except in the  process-
       ing 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()  re-
       turns, but the removal of the file contents is postponed	until all ref-
       erences to the file are closed.

       The path	argument must not name a directory unless the process has  ap-
       propriate privileges and	the implementation supports using unlink() and
       unlinkat() on directories.

       Upon successful completion, unlink() and	unlinkat() will	mark  for  up-
       date  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.

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

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

	     Search permission is denied for a component of the	 path  prefix;
	     write  permission	is denied on the directory 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

	     The path argument points to an illegal address.

       EINTR A	signal	was  caught during the execution of the	unlink() func-

       ELOOP Too many symbolic links were encountered in translating path.

	     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

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

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

	     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 call-
	     ing process is not	superuser.

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

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

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

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

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

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |unlink()	is  Standard; un-  |
       |			     |linkat() is Evolving	   |
       |MT-Level		     |Async-Signal-Safe		   |

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

SunOS 5.9			  1 Aug	2001			     unlink(2)


Want to link to this manual page? Use this URL:

home | help