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 .\" $FreeBSD$
  26 .\"
  27 .Dd May 3, 2014
  28 .Dt PGET 9
  29 .Os
  30 .Sh NAME
  31 .Nm pget
  32 .Nd locate a process by number
  33 .Sh SYNOPSIS
  34 .In sys/param.h
  35 .In sys/proc.h
  36 .Ft int
  37 .Fn pget "pid_t pid" "int flags" "struct proc **pp"
  38 .Sh DESCRIPTION
  39 This function
  40 takes a
  41 .Fa pid
  42 as its argument,
  43 which can be either a process or thread id,
  44 and fills a pointer to the
  45 .Vt proc
  46 structure in
  47 .Fa *pp .
  48 In the latter case, a process owning the specified thread is looked for.
  49 The operation is performed by invoking the
  50 .Xr pfind 9
  51 function.
  52 The found process is returned locked.
  53 For the
  54 .Dv PGET_HOLD
  55 case, it is returned unlocked (but held).
  56 The
  57 .Fn pget
  58 function can
  59 perform additional manipulations, depending on a
  60 .Fa flags
  61 argument.
  62 .Pp
  63 The
  64 .Fa flags
  65 argument is the logical OR of some subset of:
  66 .Bl -tag -width ".Dv PGET_NOTINEXEC"
  67 .It Dv PGET_HOLD
  68 If set, the found process will be held and unlocked.
  69 .It Dv PGET_CANSEE
  70 If set, the found process will be checked for its visibility.
  71 See
  72 .Xr p_cansee 9 .
  73 .It Dv PGET_CANDEBUG
  74 If set, the found process will be checked for its debuggability.
  75 See
  76 .Xr p_candebug 9 .
  77 .It Dv PGET_ISCURRENT
  78 If set, the found process will be checked that it matches the current
  79 process context.
  80 .It Dv PGET_NOTWEXIT
  81 If set, the found process will be checked that it does not have the process
  82 flag
  83 .Dv P_WEXIT
  84 set.
  85 .It Dv PGET_NOTINEXEC
  86 If set, the found process will be checked that it does not have the process
  87 flag
  88 .Dv P_INEXEC
  89 set.
  90 .It Dv PGET_NOTID
  91 If set,
  92 .Fa pid
  93 is not assumed as a thread id for values larger than
  94 .Dv PID_MAX .
  95 .It Dv PGET_WANTREAD
  96 If set, the found process will be checked that the caller may get
  97 a read access to its structure.
  98 A shorthand for
  99 .Pq Dv PGET_HOLD | PGET_CANDEBUG | PGET_NOTWEXIT .
 100 .El
 101 .Sh RETURN VALUES
 102 If the process is found in the specified way, then zero is returned,
 103 otherwise an appropriate error code is returned.
 104 .Sh SEE ALSO
 105 .Xr p_candebug 9 ,
 106 .Xr p_cansee 9 ,
 107 .Xr pfind 9