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