usr/src/man/man3proc/proc_lwp_in_set.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 PROC_LWP_IN_SET 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm proc_lwp_in_set ,
  19 .Nm proc_lwp_range_valid
  20 .Nd test and validate thread ranges
  21 .Sh SYNOPSIS
  22 .Lb libproc
  23 .Ft int
  24 .Fo proc_lwp_in_set
  25 .Fa "const char *set"
  26 .Fa "lwpid_t lwpid"
  27 .Fc
  28 .Ft int
  29 .Fo proc_lwp_range_valid
  30 .Fa "const char *set"
  31 .Fc
  32 .Sh DESCRIPTION
  33 The
  34 .Fn proc_lwp_in_set
  35 and
  36 .Fn proc_lwp_range_valid
  37 functions provide means for testing the validity of thread ranges and
  38 whether a thread is in a range.
  39 .Pp
  40 A thread range is a series of one or more series of range identifiers
  41 which describe a collection of threads.
  42 These are often used by programs such as
  43 .Xr pbind 1M ,
  44 .Xr pstack 1 ,
  45 .Xr prun 1 ,
  46 .Xr pstop 1 ,
  47 and others as a means for a user to specify a selection of threads from
  48 inside of a process.
  49 .Pp
  50 More formally, the thread range may be described as:
  51 .Bd -literal -offset indent
  52 lwp_range[,lwp_range]*
  53 .Ed
  54 .Pp
  55 An LWP range may be specified as one of the following four strings.
  56 The following table shows the string formats and the corresponding set of
  57 valid threads that match it:
  58 .Bl -column -offset indent ".Sy n-m" "n <= lwpid <= m"
  59 .It Sy -n Ta lwpid <= n
  60 .It Sy n-m Ta n <= lwpid <= m
  61 .It Sy n- Ta lwpid >= n
  62 .It Sy n Ta lwpid == n
  63 .El
  64 .Pp
  65 For example, the thread range
  66 .Sy -2,4-5,7,8-
  67 matches thread with IDs 0-2, 4-5, 7, and any thread id 8 or greater.
  68 .Pp
  69 The
  70 .Fn proc_lwp_range_valid
  71 function determines whether or not the character string
  72 .Fa set
  73 is a valid thread range based on the rules above.
  74 Note, the empty string, the
  75 .Dv NULL
  76 pointer, or otherwise are not valid.
  77 .Pp
  78 The
  79 .Fn proc_lwp_in_set
  80 function determines whether the thread identifier
  81 .Fa lwpid
  82 is contained in the set described by
  83 .Fa set .
  84 If
  85 .Fa set
  86 is the
  87 .Dv NULL
  88 pointer, then every thread matches the set.
  89 .Sh RETURN VALUES
  90 Upon successful completion, the
  91 .Fa proc_lwp_in_set
  92 function returns
  93 .Sy 1
  94 to indicate
  95 .Fa lwpid
  96 is in
  97 .Fa set .
  98 Otherwise,
  99 .Sy 0
 100 is returned to indicate that
 101 .Fa lwpid
 102 is not in
 103 .Fa set .
 104 .Pp
 105 Upon successful completion, the
 106 .Fa proc_lwp_range_valid
 107 function returns
 108 .Sy 0
 109 to indicate
 110 .Fa set
 111 is valid.
 112 Otherwise,
 113 .Sy -1
 114 is returned to indicate that the set is invalid.
 115 .Sh INTERFACE STABILITY
 116 .Sy Uncommitted
 117 .Sh MT-LEVEL
 118 .Sy MT-Safe
 119 .Sh SEE ALSO
 120 .Xr libproc 3LIB ,
 121 .Xr proc 4