usr/src/man/man3proc/Lgrab.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 LGRAB 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Lgrab
  19 .Nd obtain a handle to control a thread
  20 .Sh SYNOPSIS
  21 .Lb libproc
  22 .In libproc.h
  23 .Ft "struct ps_lwphandle *"
  24 .Fo Lgrab
  25 .Fa "struct ps_prochandle *P"
  26 .Fa "lwpid_t lwpid"
  27 .Fa "int *perr"
  28 .Fc
  29 .Sh DESCRIPTION
  30 The
  31 .Fn Lgrab
  32 function obtains a control handle to the thread identified by
  33 .Fa lwpid
  34 residing under the process
  35 .Fa P .
  36 This handle is then passed as argument to other
  37 .Sy libproc
  38 routines. The
  39 .Fa lwpid
  40 can be obtained from the
  41 .Sy pr_lwpid
  42 member of the
  43 .Sy lwpstatus_t
  44 structure.
  45 .Pp
  46 The
  47 .Fa perr
  48 argument must point to a valid pointer that will be used to store an
  49 error code in the event that
  50 .Fn Lgrab
  51 is unable to successfully obtain a handle to the process. The possible
  52 errors are defined below in the
  53 .Sx ERRORS
  54 section. The code may be transformed into a human readable string
  55 through the use of
  56 .Xr Lgrab_error 3PROC .
  57 .Pp
  58 The handle to the thread is valid until the
  59 .Xr Lfree 3PROC
  60 function is called, which also releases associated resources from the
  61 handle. Only a single handle to a specific thread may exist at any
  62 time. If the handle already exists and another caller attempts to grab
  63 that thread, it will result in an error. The caller must call
  64 .Fn Lfree
  65 before releasing the handle associated with
  66 .Fa P .
  67 .Pp
  68 Unlike grabbing a process, grabbing a thread does not change the current
  69 state of the thread. If it is running, it will remain running. If it is
  70 stopped, it will remain stopped.
  71 .Sh RETURN VALUES
  72 Upon successful completion, the
  73 .Fn Lgrab
  74 function returns a pointer to the control handle for the specified
  75 thread. Otherwise, the
  76 .Dv NULL
  77 pointer is returned and
  78 .Fa perr
  79 is set to indicate the error.
  80 .Sh ERRORS
  81 The
  82 .Fn Lgrab
  83 function will fail if:
  84 .Bl -tag -width Er
  85 .It Er G_BUSY
  86 Another handle already exists for the thread identified by
  87 .Fa lwpid .
  88 The handle need not exist in the current process and may exist in
  89 another process.
  90 .It Er G_NOPROC
  91 The thread identified by
  92 .Fa lwpid
  93 does not exist or has already become a zombie.
  94 .It Er G_STRANGE
  95 An unanticipated system error occurred while trying to create the
  96 handle. When this occurs, then the value of
  97 .Sy errno
  98 is meaningful. See
  99 .Xr errno 3C
 100 for more information and
 101 .Xr Intro 2
 102 for the list of possible errors.
 103 .El
 104 .Sh INTERFACE STABILITY
 105 .Sy Uncommitted
 106 .Sh MT-LEVEL
 107 .Sy MT-Safe
 108 .Sh SEE ALSO
 109 .Xr errno 3C ,
 110 .Xr libproc 3LIB ,
 111 .Xr Lfree 3PROC ,
 112 .Xr Lgrab_error 3PROC ,
 113 .Xr proc 4