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