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

FreeBSD Manual Pages


home | help
UNLINK(2)		  FreeBSD System Calls Manual		     UNLINK(2)

     unlink, unlinkat -- remove	directory entry

     #include <unistd.h>

     unlink(const char *path);

     #include <fcntl.h>
     #include <unistd.h>

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

     The unlink() function removes the link named by path from its directory
     and decrements the	link count of the file which was referenced by the
     link.  If that decrement reduces the link count of	the file to zero, and
     no	process	has the	file open, then	all resources associated with the file
     are reclaimed.  If	one or more processes have the file open when the last
     link is removed, the link is removed, but the removal of the file is de-
     layed until all references	to it have been	closed.

     The unlinkat() function is	equivalent to either the unlink() or rmdir(2)
     function depending	on the value of	flag (see below), except that where
     path specifies a relative path, the directory entry to be removed is de-
     termined relative to the directory	associated with	file descriptor	fd in-
     stead of the current working directory.

     If	unlinkat() is passed the special value AT_FDCWD	(defined in <fcntl.h>)
     in	the fd parameter, the current working directory	is used	and the	behav-
     ior is identical to a call	to unlink() or rmdir(2), depending on whether
     or	not the	AT_REMOVEDIR bit is set	in flag.

     The flag argument is the bitwise OR of zero or more of the	following val-

	   AT_REMOVEDIR	 Remove	the directory entry specified by path as a di-
			 rectory, not a	normal file.

     Upon successful completion, the value 0 is	returned; otherwise the
     value -1 is returned and the global variable errno	is set to indicate the

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

     [ENOTDIR]		A component of the path	prefix is not a	directory.

     [ENAMETOOLONG]	A component of a pathname exceeded NAME_MAX charac-
			ters, or an entire pathname (including the terminating
			NUL) exceeded PATH_MAX bytes.

     [ENOENT]		The named file does not	exist.

     [EACCES]		Search permission is denied for	a component of the
			path prefix.

     [EACCES]		Write permission is denied on the directory containing
			the link to be removed.

     [ELOOP]		Too many symbolic links	were encountered in translat-
			ing the	pathname.

     [EPERM]		The named file is a directory and the effective	user
			ID of the process is not the superuser,	or the file
			system containing the file does	not permit the use of
			unlink() on a directory.

     [EPERM]		The directory containing the file is marked sticky,
			and neither the	containing directory nor the file to
			be removed are owned by	the effective user ID.

     [EPERM]		The named file or the directory	containing it has its
			immutable or append-only flag set (see chflags(2)).

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

     [EIO]		An I/O error occurred while deleting the directory en-
			try or deallocating the	inode.

     [EROFS]		The named file resides on a read-only file system.

     [EFAULT]		path points outside the	process's allocated address

     Additionally, unlinkat() will fail	if:

     [ENOTDIR]		The AT_REMOVEDIR flag bit is set and path does not
			name a directory.

     [ENOTEMPTY]	The AT_REMOVEDIR flag bit is set and the named direc-
			tory contains files other than `.' and `..' in it.

     [EINVAL]		The value of the flag argument was neither zero	nor

     [EINVAL]		The value of the flag argument was AT_REMOVEDIR	and
			the last element of path consists of `.'.

     [EBADF]		The path argument specifies a relative path and	the fd
			argument is neither AT_FDCWD nor a valid file descrip-

     [ENOTDIR]		The path argument specifies a relative path and	the fd
			argument is a valid file descriptor but	it does	not
			reference a directory.

     [EACCES]		The path argument specifies a relative path but	search
			permission is denied for the directory which the fd
			file descriptor	references.

     rm(1), chflags(2),	close(2), link(2), rmdir(2), symlink(7)

     The unlink() and unlinkat() functions conform to IEEE Std 1003.1-2008

     The unlink() system call first appeared in	Version	1 AT&T UNIX.  The
     unlinkat()	function appeared in OpenBSD 5.0.

FreeBSD	13.0			 June 1, 2016			  FreeBSD 13.0


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

home | help