xref: /dflybsd-src/lib/libc/sys/extexit.2 (revision 86d7f5d305c6adaa56ff4582ece9859d73106103)

.\" Copyright (c) 2007 The DragonFly Project.  All rights reserved.
.\"
.\" This code is derived from software contributed to The DragonFly Project
.\" by Simon 'corecode' Schubert <corecode@fs.ei.tum.de>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\" 3. Neither the name of The DragonFly Project nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific, prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 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
.\" SUCH DAMAGE.
.\"
.\" $DragonFly: src/lib/libc/sys/extexit.2,v 1.5 2008/05/02 02:05:04 swildner Exp $
.\"
.Dd February 24, 2007
.Dt EXTEXIT 2
.Os
.Sh NAME
.Nm extexit
.Nd terminate the calling lwp or process and perform action
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In unistd.h
.Ft void
.Fn extexit "int how" "int status" "void *addr"
.Sh DESCRIPTION
The
.Fn extexit
function terminates a lwp or process and performs an action.
This is a low level service routine not intended to be used
from common user code.
.Pp
The
.Fn extexit
function can be used to either exit a lwp or a complete process.
This is done by specifying either
.Dv EXTEXIT_PROC
or
.Dv EXTEXIT_LWP
in
.Fa how .
If exiting the process or if exiting the last lwp of a process,
.Fn extexit
behaves like
.Xr _exit 2
called with the
.Fa status
argument.
.Pp
Additionally,
.Fn extexit
can be used to perform certain actions when exiting.
The following actions can be specified by
.Em or Ns 'ing
these values in the
.Fa how
argument:
.Bl -tag -width ".Dv EXTEXIT_SIMPLE"
.It Dv EXTEXIT_SETINT
Set the integer variable pointer to by
.Fa addr
to the value of
.Fa status .
This is intended to enable other threads or processes to
detect the termination of the calling lwp or process.
.El
.Sh RETURN VALUES
The
.Fn extexit
function will only return if it was invoked
with invalid arguments.  In this case,
.Va errno
will be set to
.Er EINVAL .
In the case of a successful invocation,
.Fn extexit
will not return.
.Pp
In case of an error, the action specified in
.Fa how
will not be performed.
If an error occurs while performing an action, the results are
undefined.
However,
.Fn extexit
will try hard to avoid such a situation.
In any case, if an error occurs while performing an action,
.Fn extexit
will return.
.Sh SEE ALSO
.Xr _exit 2 ,
.Xr wait 2 ,
.Xr exit 3
.Sh HISTORY
The
.Fn extexit
function first appeared in
.Dx 1.9 .