lib/libc/sys/thr_self.2

   1 .\" Copyright (c) 2016 The FreeBSD Foundation, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This documentation was written by
   5 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
   6 .\" from the FreeBSD Foundation.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd May 5, 2020
  32 .Dt THR_SELF 2
  33 .Os
  34 .Sh NAME
  35 .Nm thr_self
  36 .Nd return thread identifier for the calling thread
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/thr.h
  41 .Ft int
  42 .Fn thr_self "long *id"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn thr_self
  46 system call stores the system-wide thread identifier for the current
  47 kernel-scheduled thread in the variable pointed by the argument
  48 .Va id .
  49 .Pp
  50 The thread identifier is an integer in the range from
  51 .Dv PID_MAX + 2
  52 (100001) to
  53 .Dv INT_MAX .
  54 The thread identifier is guaranteed to be unique at any given time,
  55 for each running thread in the system.
  56 After the thread exits, the identifier may be reused.
  57 .Sh RETURN VALUES
  58 If successful,
  59 .Fn thr_self
  60 will return zero, otherwise \-1 is returned, and
  61 .Va errno
  62 is set to indicate the error.
  63 .Sh ERRORS
  64 The
  65 .Fn thr_self
  66 operation may return the following errors:
  67 .Bl -tag -width Er
  68 .It Bq Er EFAULT
  69 The memory pointed to by the
  70 .Fa id
  71 argument is not valid.
  72 .El
  73 .Sh SEE ALSO
  74 .Xr _umtx_op 2 ,
  75 .Xr thr_exit 2 ,
  76 .Xr thr_kill 2 ,
  77 .Xr thr_kill2 2 ,
  78 .Xr thr_new 2 ,
  79 .Xr thr_set_name 2 ,
  80 .Xr pthread_getthreadid_np 3 ,
  81 .Xr pthread_self 3
  82 .Sh STANDARDS
  83 The
  84 .Fn thr_self
  85 system call is non-standard and is used by
  86 .Lb libthr
  87 to implement
  88 .St -p1003.1-2001
  89 .Xr pthread 3
  90 functionality.
  91 .Sh HISTORY
  92 The
  93 .Fn thr_self
  94 system call first appeared in
  95 .Fx 5.2 .