usr/src/man/man3proc/Prelease.3proc

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