share/man/man9/pget.9

   1 .\" Copyright (c) 2011 Sergey Kandaurov
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .Dd May 3, 2014
  26 .Dt PGET 9
  27 .Os
  28 .Sh NAME
  29 .Nm pget
  30 .Nd locate a process by number
  31 .Sh SYNOPSIS
  32 .In sys/param.h
  33 .In sys/proc.h
  34 .Ft int
  35 .Fn pget "pid_t pid" "int flags" "struct proc **pp"
  36 .Sh DESCRIPTION
  37 This function
  38 takes a
  39 .Fa pid
  40 as its argument,
  41 which can be either a process or thread id,
  42 and fills a pointer to the
  43 .Vt proc
  44 structure in
  45 .Fa *pp .
  46 In the latter case, a process owning the specified thread is looked for.
  47 The operation is performed by invoking the
  48 .Xr pfind 9
  49 function.
  50 The found process is returned locked.
  51 For the
  52 .Dv PGET_HOLD
  53 case, it is returned unlocked (but held).
  54 The
  55 .Fn pget
  56 function can
  57 perform additional manipulations, depending on a
  58 .Fa flags
  59 argument.
  60 .Pp
  61 The
  62 .Fa flags
  63 argument is the logical OR of some subset of:
  64 .Bl -tag -width ".Dv PGET_NOTINEXEC"
  65 .It Dv PGET_HOLD
  66 If set, the found process will be held and unlocked.
  67 .It Dv PGET_CANSEE
  68 If set, the found process will be checked for its visibility.
  69 See
  70 .Xr p_cansee 9 .
  71 .It Dv PGET_CANDEBUG
  72 If set, the found process will be checked for its debuggability.
  73 See
  74 .Xr p_candebug 9 .
  75 .It Dv PGET_ISCURRENT
  76 If set, the found process will be checked that it matches the current
  77 process context.
  78 .It Dv PGET_NOTWEXIT
  79 If set, the found process will be checked that it does not have the process
  80 flag
  81 .Dv P_WEXIT
  82 set.
  83 .It Dv PGET_NOTINEXEC
  84 If set, the found process will be checked that it does not have the process
  85 flag
  86 .Dv P_INEXEC
  87 set.
  88 .It Dv PGET_NOTID
  89 If set,
  90 .Fa pid
  91 is not assumed as a thread id for values larger than
  92 .Dv PID_MAX .
  93 .It Dv PGET_WANTREAD
  94 If set, the found process will be checked that the caller may get
  95 a read access to its structure.
  96 A shorthand for
  97 .Pq Dv PGET_HOLD | PGET_CANDEBUG | PGET_NOTWEXIT .
  98 .El
  99 .Sh RETURN VALUES
 100 If the process is found in the specified way, then zero is returned,
 101 otherwise an appropriate error code is returned.
 102 .Sh SEE ALSO
 103 .Xr p_candebug 9 ,
 104 .Xr p_cansee 9 ,
 105 .Xr pfind 9