lib/libc/sys/thr_kill.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_kill 2
  33 .Os
  34 .Sh NAME
  35 .Nm thr_kill
  36 .Nd send signal to thread
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/thr.h
  41 .Ft int
  42 .Fn thr_kill "long id" "int sig"
  43 .Ft int
  44 .Fn thr_kill2 "pid_t pid" "long id" "int sig"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn thr_kill
  48 and
  49 .Fn thr_kill2
  50 system calls allow sending a signal, specified by the
  51 .Fa sig
  52 argument, to some threads in a process.
  53 For the
  54 .Fn thr_kill
  55 function, signalled threads are always limited to the current process.
  56 For the
  57 .Fn thr_kill2
  58 function, the
  59 .Fa pid
  60 argument specifies the process with threads to be signalled.
  61 .Pp
  62 The
  63 .Fa id
  64 argument specifies which threads get the signal.
  65 If
  66 .Fa id
  67 is equal to \-1, all threads in the specified process are signalled.
  68 Otherwise, only the thread with the thread identifier equal to the
  69 argument is signalled.
  70 .Pp
  71 The
  72 .Fa sig
  73 argument defines the delivered signal.
  74 It must be a valid signal number or zero.
  75 In the latter case no signal is actually sent, and the call is used to
  76 verify the liveness of the thread.
  77 .Pp
  78 The signal is delivered with
  79 .Dv siginfo
  80 .Dv si_code
  81 set to
  82 .Dv SI_LWP .
  83 .Sh RETURN VALUES
  84 If successful,
  85 .Fn thr_kill
  86 and
  87 .Fn thr_kill2
  88 will return zero, otherwise \-1 is returned, and
  89 .Va errno
  90 is set to indicate the error.
  91 .Sh ERRORS
  92 The
  93 .Fn thr_kill
  94 and
  95 .Fn thr_kill2
  96 operations return the following errors:
  97 .Bl -tag -width Er
  98 .It Bq Er EINVAL
  99 The
 100 .Fa sig
 101 argument is not zero and does not specify valid signal.
 102 .It Bq Er ESRCH
 103 The specified process or thread was not found.
 104 .El
 105 .Pp
 106 Additionally, the
 107 .Fn thr_kill2
 108 may return the following errors:
 109 .Bl -tag -width Er
 110 .It Bq Er EPERM
 111 The current process does not have sufficient privilege to check existence or
 112 send a signal to the specified process.
 113 .El
 114 .Sh SEE ALSO
 115 .Xr kill 2 ,
 116 .Xr thr_exit 2 ,
 117 .Xr thr_new 2 ,
 118 .Xr thr_self 2 ,
 119 .Xr thr_set_name 2 ,
 120 .Xr _umtx_op 2 ,
 121 .Xr pthread_kill 3 ,
 122 .Xr signal 3
 123 .Sh STANDARDS
 124 The
 125 .Fn thr_kill
 126 and
 127 .Fn thr_kill2
 128 system calls are non-standard and are used by the
 129 .Lb libthr
 130 to implement
 131 .St -p1003.1-2001
 132 .Xr pthread 3
 133 functionality.
 134 .Sh HISTORY
 135 The
 136 .Fn thr_kill
 137 and
 138 .Fn thr_kill2
 139 system calls first appeared in
 140 .Fx 5.2 .