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:

       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.

       EINTR	       A signal	was caught during the  execution  of  the  un-
		       link() function.

       ELOOP	       Too many	symbolic links were encountered	in translating

       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 {PRIV_SYS_LINKDIR} is
		       not asserted  in	 the  effective	 set  of  the  calling

       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  in-
		       termediate 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  exe-

       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),
       privileges(5), fsattr(5)

SunOS 5.10			  1 Feb	2003			     unlink(2)


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

home | help