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