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