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

FreeBSD Manual Pages


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

     unlink, unlinkat -- remove	directory entry

     Standard C	Library	(libc, -lc)

     #include <unistd.h>

     unlink(const char *path);

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

     The unlink() system call removes the link named by	path from its direc-
     tory 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 process have the file open when the
     last link is removed, the link is removed,	but the	removal	of the file is
     delayed until all references to it	have been closed.  The path argument
     may not be	a directory.

     The unlinkat() system call	is equivalent to unlink() or rmdir() except in
     the case where path specifies a relative path.  In	this case the direc-
     tory entry	to be removed is determined relative to	the directory associ-
     ated with the file	descriptor fd instead of the current working direc-

     The values	for flag are constructed by a bitwise-inclusive	OR of flags
     from the following	list, defined in <fcntl.h>:

	     Remove the	directory entry	specified by fd	and path as a direc-
	     tory, not a normal	file.

     If	unlinkat() is passed the special value AT_FDCWD	in the fd parameter,
     the current working directory is used and the behavior is identical to a
     call to unlink or rmdir respectively, depending on	whether	or not the
     AT_REMOVEDIR bit is set in	flag.

     The unlink() function returns the value 0 if successful; otherwise	the
     value -1 is returned and the global variable errno	is set to indicate the

     The unlink() succeeds unless:

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

     [EISDIR]		The named file is a directory.

     [ENAMETOOLONG]	A component of a pathname exceeded 255 characters, or
			an entire path name exceeded 1023 characters.

     [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.

     [EPERM]		The named file has its immutable, undeletable or ap-
			pend-only flag set, see	the chflags(2) manual page for
			more information.

     [EPERM]		The parent directory of	the named file has its im-
			mutable	or append-only flag set.

     [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.

     [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]		The path argument points outside the process's allo-
			cated address space.

     [ENOSPC]		On file	systems	supporting copy-on-write or snapshots,
			there was not enough free space	to record metadata for
			the delete operation of	the file.

     In	addition to the	errors returned	by the unlink(), the unlinkat()	may
     fail if:

     [EBADF]		The path argument does not specify an absolute path
			and the	fd argument is neither AT_FDCWD	nor a valid
			file descriptor	open for searching.

     [ENOTEMPTY]	The flag parameter has the AT_REMOVEDIR	bit set	and
			the path argument names	a directory that is not	an
			empty directory, or there are hard links to the	direc-
			tory other than	dot or a single	entry in dot-dot.

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

     [EINVAL]		The value of the flag argument is not valid.

     [ENOTDIR]		The path argument is not an absolute path and fd is
			neither	AT_FDCWD nor a file descriptor associated with
			a directory.

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

     The unlinkat() system call	follows	The Open Group Extended	API Set	2

     The unlink() function appeared in Version 6 AT&T UNIX.  The unlinkat()
     system call appeared in FreeBSD 8.0.

     The unlink() system call traditionally allows the super-user to unlink
     directories which can damage the file system integrity.  This implementa-
     tion no longer permits it.

BSD				 July 28, 2015				   BSD


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

home | help