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