.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2015 Joyent, Inc.
.\"
.Dd May 11, 2016
.Dt PRELEASE 3PROC
.Os
.Sh NAME
.Nm Prelease ,
.Nm Pfree
.Nd release a process control handle
.Sh SYNOPSIS
.Lb libproc
.In libproc.h
.Ft void
.Fo Prelease
.Fa "struct ps_prochandle *P"
.Fa "int flags"
.Fc
.Ft void
.Fo Pfree
.Fa "struct ps_prochandle *P"
.Fc
.Sh DESCRIPTION
The
.Fn Prelease
function is used to release all of the resources associated with a
.Nm libproc
handle.
It is suitable for handles to core files, created processes, and grabbed
processes from the
.Xr Pgrab_core 3PROC ,
.Xr Pcreate 3PROC ,
.Xr Pgrab 3PROC ,
and
.Xr Pgrab_file 3PROC
functions.
.Pp
After calling the
.Fn Prelease
function, all data that was returned via the handle will no longer be
valid.
For example, the data from calls to
.Xr Pctlfd 3PROC ,
.Xr Pgetauxvec 3PROC ,
.Xr Pstatus 3PROC ,
and others.
.Pp
The behavior of the released process is controlled by the
.Fa flags
argument.
By default, if no flags are passed, then the process represented by
.Fa P
will be set running if it was created by
.Xr Pcreate 3PROC
or if it was not originally stopped or set to stop in /proc.
The following values may be passed in to the
.Fa flags
argument.
Multiple flags should be be combined with a bitwise-inclusive-OR.
.Bl -tag -width Er -offset indent
.It Dv PRELEASE_CLEAR
When releasing the process, clear all tracing flags that are set on the
process.
.It Dv PRELEASE_RETAIN
When releasing the process, retain all tracing flags that are currently
active on the process.
.It Dv PRELEASE_HANG
Leave the process stopped.
It will not resume execution unless it is explicitly enabled with
.Xr prun 1
or another process explicitly enables it.
.It Dv PRELEASE_KILL
Release the process and terminate it with
.Dv SIGKILL .
This option takes precedence over all other values that may be passed in to
.Fa flags .
.El
.Pp
The
.Fn Pfree
function is similar to the
.Fn Prelease
function in that it frees the resources associated with the process
handle
.Fa P ;
however, unlike the
.Fn Prelease
function, it does not handle any logic to change or set the grabbed processes
state.
In general, prefer
.Fn Prelease
to
.Fn Pfree .
.Sh INTERFACE STABILITY
.Sy Uncommitted
.Sh MT-LEVEL
See
.Sy LOCKING
in
.Xr libproc 3LIB .
.Sh SEE ALSO
.Xr prun 1 ,
.Xr libproc 3LIB ,
.Xr Pcreate 3PROC ,
.Xr Pgrab 3PROC ,
.Xr Pgrab_core 3PROC ,
.Xr proc 4