1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2015 Joyent, Inc. 13.\" 14.Dd May 11, 2016 15.Dt PRELEASE 3PROC 16.Os 17.Sh NAME 18.Nm Prelease , 19.Nm Pfree 20.Nd release a process control handle 21.Sh SYNOPSIS 22.Lb libproc 23.In libproc.h 24.Ft void 25.Fo Prelease 26.Fa "struct ps_prochandle *P" 27.Fa "int flags" 28.Fc 29.Ft void 30.Fo Pfree 31.Fa "struct ps_prochandle *P" 32.Fc 33.Sh DESCRIPTION 34The 35.Fn Prelease 36function is used to release all of the resources associated with a 37.Nm libproc 38handle. 39It is suitable for handles to core files, created processes, and grabbed 40processes from the 41.Xr Pgrab_core 3PROC , 42.Xr Pcreate 3PROC , 43.Xr Pgrab 3PROC , 44and 45.Xr Pgrab_file 3PROC 46functions. 47.Pp 48After calling the 49.Fn Prelease 50function, all data that was returned via the handle will no longer be 51valid. 52For example, the data from calls to 53.Xr Pctlfd 3PROC , 54.Xr Pgetauxvec 3PROC , 55.Xr Pstatus 3PROC , 56and others. 57.Pp 58The behavior of the released process is controlled by the 59.Fa flags 60argument. 61By default, if no flags are passed, then the process represented by 62.Fa P 63will be set running if it was created by 64.Xr Pcreate 3PROC 65or if it was not originally stopped or set to stop in /proc. 66The following values may be passed in to the 67.Fa flags 68argument. 69Multiple flags should be be combined with a bitwise-inclusive-OR. 70.Bl -tag -width Er -offset indent 71.It Dv PRELEASE_CLEAR 72When releasing the process, clear all tracing flags that are set on the 73process. 74.It Dv PRELEASE_RETAIN 75When releasing the process, retain all tracing flags that are currently 76active on the process. 77.It Dv PRELEASE_HANG 78Leave the process stopped. 79It will not resume execution unless it is explicitly enabled with 80.Xr prun 1 81or another process explicitly enables it. 82.It Dv PRELEASE_KILL 83Release the process and terminate it with 84.Dv SIGKILL . 85This option takes precedence over all other values that may be passed in to 86.Fa flags . 87.El 88.Pp 89The 90.Fn Pfree 91function is similar to the 92.Fn Prelease 93function in that it frees the resources associated with the process 94handle 95.Fa P ; 96however, unlike the 97.Fn Prelease 98function, it does not handle any logic to change or set the grabbed processes 99state. 100In general, prefer 101.Fn Prelease 102to 103.Fn Pfree . 104.Sh INTERFACE STABILITY 105.Sy Uncommitted 106.Sh MT-LEVEL 107See 108.Sy LOCKING 109in 110.Xr libproc 3LIB . 111.Sh SEE ALSO 112.Xr prun 1 , 113.Xr libproc 3LIB , 114.Xr Pcreate 3PROC , 115.Xr Pgrab 3PROC , 116.Xr Pgrab_core 3PROC , 117.Xr proc 4 118