1PTHREAD_CANCEL(3P)         POSIX Programmer's Manual        PTHREAD_CANCEL(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       pthread_cancel — cancel execution of a thread
13

SYNOPSIS

15       #include <pthread.h>
16
17       int pthread_cancel(pthread_t thread);
18

DESCRIPTION

20       The pthread_cancel() function shall request that  thread  be  canceled.
21       The  target  thread's  cancelability state and type determines when the
22       cancellation takes effect. When the cancellation is acted on, the  can‐
23       cellation  cleanup  handlers  for thread shall be called. When the last
24       cancellation cleanup handler returns, the thread-specific data destruc‐
25       tor  functions  shall  be  called for thread.  When the last destructor
26       function returns, thread shall be terminated.
27
28       The cancellation processing  in  the  target  thread  shall  run  asyn‐
29       chronously   with   respect   to  the  calling  thread  returning  from
30       pthread_cancel().
31

RETURN VALUE

33       If successful, the pthread_cancel() function shall return zero;  other‐
34       wise, an error number shall be returned to indicate the error.
35

ERRORS

37       The  pthread_cancel()  function  shall  not  return  an  error  code of
38       [EINTR].
39
40       The following sections are informative.
41

EXAMPLES

43       None.
44

APPLICATION USAGE

46       None.
47

RATIONALE

49       Two alternative functions were considered for sending the  cancellation
50       notification to a thread. One would be to define a new SIGCANCEL signal
51       that had the cancellation semantics when delivered; the  other  was  to
52       define  the new pthread_cancel() function, which would trigger the can‐
53       cellation semantics.
54
55       The advantage of a new signal was that so much of the delivery criteria
56       were identical to that used when trying to deliver a signal that making
57       cancellation notification a signal was seen as consistent. Indeed, many
58       implementations  implement  cancellation using a special signal. On the
59       other hand, there would be no signal functions that could be used  with
60       this  signal  except  pthread_kill(), and the behavior of the delivered
61       cancellation signal would be unlike  any  previously  existing  defined
62       signal.
63
64       The  benefits  of  a special function include the recognition that this
65       signal would be defined because of the similar  delivery  criteria  and
66       that  this  is  the only common behavior between a cancellation request
67       and a signal. In addition, the cancellation delivery mechanism does not
68       have  to  be  implemented  as  a  signal. There are also strong, if not
69       stronger, parallels with language exception mechanisms than  with  sig‐
70       nals that are potentially obscured if the delivery mechanism is visibly
71       closer to signals.
72
73       In the end, it was considered that as there were so many exceptions  to
74       the  use  of the new signal with existing signals functions it would be
75       misleading. A special function has resolved this problem.   This  func‐
76       tion was carefully defined so that an implementation wishing to provide
77       the cancellation functions on top of signals could do so.  The  special
78       function  also  means that implementations are not obliged to implement
79       cancellation with signals.
80
81       If an implementation detects use of a thread ID after the  end  of  its
82       lifetime, it is recommended that the function should fail and report an
83       [ESRCH] error.
84

FUTURE DIRECTIONS

86       None.
87

SEE ALSO

89       pthread_exit(), pthread_cond_timedwait(), pthread_join(), pthread_set‐
90       cancelstate()
91
92       The Base Definitions volume of POSIX.1‐2017, <pthread.h>
93
95       Portions  of  this text are reprinted and reproduced in electronic form
96       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
97       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
98       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
99       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
100       event of any discrepancy between this version and the original IEEE and
101       The  Open Group Standard, the original IEEE and The Open Group Standard
102       is the referee document. The original Standard can be  obtained  online
103       at http://www.opengroup.org/unix/online.html .
104
105       Any  typographical  or  formatting  errors that appear in this page are
106       most likely to have been introduced during the conversion of the source
107       files  to  man page format. To report such errors, see https://www.ker
108       nel.org/doc/man-pages/reporting_bugs.html .
109
110
111
112IEEE/The Open Group                  2017                   PTHREAD_CANCEL(3P)
Impressum