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