logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

pthread_kill.3p (3786B)

    

  1. '\" et
  2. .TH PTHREAD_KILL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. pthread_kill
  12. \(em send a signal to a thread
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <signal.h>
  17. .P
  18. int pthread_kill(pthread_t \fIthread\fP, int \fIsig\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIpthread_kill\fR()
  23. function shall request that a signal be delivered to the specified
  24. thread.
  25. .P
  26. As in
  27. \fIkill\fR(),
  28. if
  29. .IR sig
  30. is zero, error checking shall be performed but no signal shall
  31. actually be sent.
  32. .SH "RETURN VALUE"
  33. Upon successful completion, the function shall return a value of zero.
  34. Otherwise, the function shall return an error number. If the
  35. \fIpthread_kill\fR()
  36. function fails, no signal shall be sent.
  37. .SH ERRORS
  38. The
  39. \fIpthread_kill\fR()
  40. function shall fail if:
  41. .TP
  42. .BR EINVAL
  43. The value of the
  44. .IR sig
  45. argument is an invalid or unsupported signal number.
  46. .P
  47. The
  48. \fIpthread_kill\fR()
  49. function shall not return an error code of
  50. .BR [EINTR] .
  51. .LP
  52. .IR "The following sections are informative."
  53. .SH EXAMPLES
  54. None.
  55. .SH "APPLICATION USAGE"
  56. The
  57. \fIpthread_kill\fR()
  58. function provides a mechanism for asynchronously directing a signal at
  59. a thread in the calling process. This could be used, for example, by
  60. one thread to affect broadcast delivery of a signal to a set of
  61. threads.
  62. .P
  63. Note that
  64. \fIpthread_kill\fR()
  65. only causes the signal to be handled in the context of the given
  66. thread; the signal action (termination or stopping) affects the
  67. process as a whole.
  68. .SH RATIONALE
  69. If an implementation detects use of a thread ID after the end of its
  70. lifetime, it is recommended that the function should fail and report an
  71. .BR [ESRCH] 
  72. error.
  73. .P
  74. Existing implementations vary on the result of a
  75. \fIpthread_kill\fR()
  76. with a thread ID indicating an inactive thread (a terminated thread
  77. that has not been detached or joined). Some indicate success on such
  78. a call, while others give an error of
  79. .BR [ESRCH] .
  80. Since the definition of thread lifetime in this volume of POSIX.1\(hy2017 covers inactive
  81. threads, the
  82. .BR [ESRCH] 
  83. error as described is inappropriate in this case. In particular, this
  84. means that an application cannot have one thread check for termination
  85. of another with
  86. \fIpthread_kill\fR().
  87. .SH "FUTURE DIRECTIONS"
  88. A future version of this standard may require that
  89. \fIpthread_kill\fR()
  90. not fail with
  91. .BR [ESRCH] 
  92. in the case of sending signals to an inactive thread (a terminated
  93. thread not yet detached or joined), even though no signal will be
  94. delivered because the thread is no longer running.
  95. .SH "SEE ALSO"
  96. .IR "\fIkill\fR\^(\|)",
  97. .IR "\fIpthread_self\fR\^(\|)",
  98. .IR "\fIraise\fR\^(\|)"
  99. .P
  100. The Base Definitions volume of POSIX.1\(hy2017,
  101. .IR "\fB<signal.h>\fP"
  102. .\"
  103. .SH COPYRIGHT
  104. Portions of this text are reprinted and reproduced in electronic form
  105. from IEEE Std 1003.1-2017, Standard for Information Technology
  106. -- Portable Operating System Interface (POSIX), The Open Group Base
  107. Specifications Issue 7, 2018 Edition,
  108. Copyright (C) 2018 by the Institute of
  109. Electrical and Electronics Engineers, Inc and The Open Group.
  110. In the event of any discrepancy between this version and the original IEEE and
  111. The Open Group Standard, the original IEEE and The Open Group Standard
  112. is the referee document. The original Standard can be obtained online at
  113. http://www.opengroup.org/unix/online.html .
  114. .PP
  115. Any typographical or formatting errors that appear
  116. in this page are most likely
  117. to have been introduced during the conversion of the source files to
  118. man page format. To report such errors, see
  119. https://www.kernel.org/doc/man-pages/reporting_bugs.html .