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 LIBRARY 22.Lb libproc 23.Sh SYNOPSIS 24.In libproc.h 25.Ft void 26.Fo Prelease 27.Fa "struct ps_prochandle *P" 28.Fa "int flags" 29.Fc 30.Ft void 31.Fo Pfree 32.Fa "struct ps_prochandle *P" 33.Fc 34.Sh DESCRIPTION 35The 36.Fn Prelease 37function is used to release all of the resources associated with a 38.Nm libproc 39handle. 40It is suitable for handles to core files, created processes, and grabbed 41processes from the 42.Xr Pgrab_core 3PROC , 43.Xr Pcreate 3PROC , 44.Xr Pgrab 3PROC , 45and 46.Xr Pgrab_file 3PROC 47functions. 48.Pp 49After calling the 50.Fn Prelease 51function, all data that was returned via the handle will no longer be 52valid. 53For example, the data from calls to 54.Xr Pctlfd 3PROC , 55.Xr Pgetauxvec 3PROC , 56.Xr Pstatus 3PROC , 57and others. 58.Pp 59The behavior of the released process is controlled by the 60.Fa flags 61argument. 62By default, if no flags are passed, then the process represented by 63.Fa P 64will be set running if it was created by 65.Xr Pcreate 3PROC 66or if it was not originally stopped or set to stop in /proc. 67The following values may be passed in to the 68.Fa flags 69argument. 70Multiple flags should be be combined with a bitwise-inclusive-OR. 71.Bl -tag -width Er -offset indent 72.It Dv PRELEASE_CLEAR 73When releasing the process, clear all tracing flags that are set on the 74process. 75.It Dv PRELEASE_RETAIN 76When releasing the process, retain all tracing flags that are currently 77active on the process. 78.It Dv PRELEASE_HANG 79Leave the process stopped. 80It will not resume execution unless it is explicitly enabled with 81.Xr prun 1 82or another process explicitly enables it. 83.It Dv PRELEASE_KILL 84Release the process and terminate it with 85.Dv SIGKILL . 86This option takes precedence over all other values that may be passed in to 87.Fa flags . 88.El 89.Pp 90The 91.Fn Pfree 92function is similar to the 93.Fn Prelease 94function in that it frees the resources associated with the process 95handle 96.Fa P ; 97however, unlike the 98.Fn Prelease 99function, it does not handle any logic to change or set the grabbed processes 100state. 101In general, prefer 102.Fn Prelease 103to 104.Fn Pfree . 105.Sh INTERFACE STABILITY 106.Sy Uncommitted 107.Sh MT-LEVEL 108See 109.Sy LOCKING 110in 111.Xr libproc 3LIB . 112.Sh SEE ALSO 113.Xr prun 1 , 114.Xr libproc 3LIB , 115.Xr Pcreate 3PROC , 116.Xr Pgrab 3PROC , 117.Xr Pgrab_core 3PROC , 118.Xr proc 4 119