Differential D14567 Diff 55877 head/lib/libc/sys/unlink.2

Changeset View

Standalone View

head/lib/libc/sys/unlink.2

	Show All 22 Lines
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" @(#)unlink.2 8.1 (Berkeley) 6/4/93			.\" @(#)unlink.2 8.1 (Berkeley) 6/4/93
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd November 11, 2018			.Dd April 6, 2019
	.Dt UNLINK 2			.Dt UNLINK 2
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm unlink ,			.Nm unlink ,
	.Nm unlinkat			.Nm unlinkat
	.Nd remove directory entry			.Nd remove directory entry
	.Sh LIBRARY			.Sh LIBRARY
	.Lb libc			.Lb libc
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.In unistd.h			.In unistd.h
	.Ft int			.Ft int
	.Fn unlink "const char *path"			.Fn unlink "const char *path"
	.Ft int			.Ft int
	.Fn unlinkat "int fd" "const char *path" "int flag"			.Fn unlinkat "int dfd" "const char *path" "int flag"
				.Ft int
				.Fn funlinkat "int dfd" "const char *path" "int fd" "int flag"
	.Sh DESCRIPTION			.Sh DESCRIPTION
	The			The
	.Fn unlink			.Fn unlink
	system call			system call
	removes the link named by			removes the link named by
	.Fa path			.Fa path
	from its directory and decrements the link count of the			from its directory and decrements the link count of the
	file which was referenced by the link.			file which was referenced by the link.
	Show All 15 Lines
	.Fn unlink			.Fn unlink
	or			or
	.Fn rmdir			.Fn rmdir
	except in the case where			except in the case where
	.Fa path			.Fa path
	specifies a relative path.			specifies a relative path.
	In this case the directory entry to be removed is determined			In this case the directory entry to be removed is determined
	relative to the directory associated with the file descriptor			relative to the directory associated with the file descriptor
	.Fa fd			.Fa dfd
	instead of the current working directory.			instead of the current working directory.
	.Pp			.Pp
	The values for			The values for
	.Fa flag			.Fa flag
	are constructed by a bitwise-inclusive OR of flags from the following list,			are constructed by a bitwise-inclusive OR of flags from the following list,
	defined in			defined in
	.In fcntl.h :			.In fcntl.h :
	.Bl -tag -width indent			.Bl -tag -width indent
	Show All 22 Lines
	parameter, the current working directory is used and the behavior is			parameter, the current working directory is used and the behavior is
	identical to a call to			identical to a call to
	.Fa unlink			.Fa unlink
	or			or
	.Fa rmdir			.Fa rmdir
	respectively, depending on whether or not the			respectively, depending on whether or not the
	.Dv AT_REMOVEDIR			.Dv AT_REMOVEDIR
	bit is set in flag.			bit is set in flag.
				.Pp
				The
				.Fn funlinkat
				system call can be used to unlink an already-opened file, unless that
				file has been replaced since it was opened.
				It is equivalent to
				.Fn unlinkat
				in the case where
				.Fa path
				is already open as the file descriptor
				.Fa fd .
				Otherwise, the path will not be removed and an error will be returned.
				The
				.Fa fd
				can be set the
				.Dv FD_NONE .
				In that case
				.Fn funlinkat
				behaves exactly like
				.Fn unlinkat .
	.Sh RETURN VALUES			.Sh RETURN VALUES
	.Rv -std unlink			.Rv -std unlink
	.Sh ERRORS			.Sh ERRORS
	The			The
	.Fn unlink			.Fn unlink
	succeeds unless:			succeeds unless:
	.Bl -tag -width Er			.Bl -tag -width Er
	.It Bq Er ENOTDIR			.It Bq Er ENOTDIR
	▲ Show 20 Lines • Show All 98 Lines • ▼ Show 20 Lines
	.Fn unlinkat ,			.Fn unlinkat ,
	and the absolute			and the absolute
	.Fa path			.Fa path
	does not have its tail fully contained under the topping directory,			does not have its tail fully contained under the topping directory,
	or the relative			or the relative
	.Fa path			.Fa path
	escapes it.			escapes it.
	.El			.El
				.Pp
				In addition to the errors returned by
				.Fn unlinkat ,
				.Fn funlinkat
				may fail if:
				.Bl -tag -width Er
				.It Bq Er EDEADLK
				The file descriptor is not associated with the path.
				.El
	.Sh SEE ALSO			.Sh SEE ALSO
	.Xr chflags 2 ,			.Xr chflags 2 ,
	.Xr close 2 ,			.Xr close 2 ,
	.Xr link 2 ,			.Xr link 2 ,
	.Xr rmdir 2 ,			.Xr rmdir 2 ,
	.Xr symlink 7			.Xr symlink 7
	.Sh STANDARDS			.Sh STANDARDS
	The			The
	.Fn unlinkat			.Fn unlinkat
	system call follows The Open Group Extended API Set 2 specification.			system call follows The Open Group Extended API Set 2 specification.
	.Sh HISTORY			.Sh HISTORY
	The			The
	.Fn unlink			.Fn unlink
	function appeared in			function appeared in
	.At v1 .			.At v1 .
	The			The
	.Fn unlinkat			.Fn unlinkat
	system call appeared in			system call appeared in
	.Fx 8.0 .			.Fx 8.0 .
				The
				.Fn funlinkat
				system call appeared in
				.Fx 13.0 .
	.Pp			.Pp
	The			The
	.Fn unlink			.Fn unlink
	system call traditionally allows the super-user to unlink directories which			system call traditionally allows the super-user to unlink directories which
	can damage the file system integrity.			can damage the file system integrity.
	This implementation no longer permits it.			This implementation no longer permits it.