1 .\"
2 .\" Mach Operating System
3 .\" Copyright (c) 1991,1990 Carnegie Mellon University
4 .\" All Rights Reserved.
5 .\"
6 .\" Permission to use, copy, modify and distribute this software and its
7 .\" documentation is hereby granted, provided that both the copyright
8 .\" notice and this permission notice appear in all copies of the
9 .\" software, derivative works or modified versions, and any portions
10 .\" thereof, and that both notices appear in supporting documentation.
11 .\"
12 .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
13 .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
14 .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
15 .\"
16 .\" Carnegie Mellon requests users of this software to return to
17 .\"
18 .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
19 .\" School of Computer Science
20 .\" Carnegie Mellon University
21 .\" Pittsburgh PA 15213-3890
22 .\"
23 .\" any improvements or extensions that they make and grant Carnegie Mellon
24 .\" the rights to redistribute these changes.
25 .\"
26 .\"
27 .\" HISTORY
28 .\" $Log: thread_abort.man,v $
29 .\" Revision 2.5 93/03/18 15:15:34 mrt
30 .\" corrected types
31 .\" [93/03/12 16:53:42 lli]
32 .\"
33 .\" Revision 2.4 91/05/14 17:13:39 mrt
34 .\" Correcting copyright
35 .\"
36 .\" Revision 2.3 91/02/14 14:15:03 mrt
37 .\" Changed to new Mach copyright
38 .\" [91/02/12 18:15:53 mrt]
39 .\"
40 .\" Revision 2.2 90/08/07 18:44:58 rpd
41 .\" Created.
42 .\"
43 .TH thread_abort 2 1/22/88
44 .CM 4
45 .SH NAME
46 .nf
47 thread_abort \- interrupts the specified thread
48 .SH SYNOPSIS
49 .nf
50 .ft B
51 #include <mach.h>
52
53 .nf
54 .ft B
55 kern_return_t thread_abort(target_thread)
56 mach_port_t target_thread;
57
58
59 .fi
60 .ft P
61 .SH ARGUMENTS
62 .TP 15
63 .B
64 target_thread
65 The thread to be interrupted.
66
67 .SH DESCRIPTION
68
69 .B thread_abort
70 aborts the kernel primitives:
71 .B msg_send, msg_receive
72 and
73 .B msg_rpc
74 and page-faults, making the call return a
75 code indicating that it was interrupted. The call is interrupted
76 whether or not the thread (or task containing it) is currently suspended.
77 If it is supsended, the thread receives the interupt when it is resumed.
78
79 A thread will retry an aborted page-fault if its state is not modified
80 before it is resumed.
81 .B Msg_send
82 returns
83 .B SEND_INTERRUPTED
84 ;
85 .B msg_receive
86 returns
87 .B RCV_INTERRUPTED
88 ;
89 .B msg_rpc
90 returns either
91 .B SEND_INTERRUPTED
92 or
93 .B RCV_INTERRUPTED
94 , depending on
95 which half of the RPC was interrupted.
96
97 The main reason for this primitive is to allow one thread to cleanly stop
98 another thread in a manner that will allow the future execution of the
99 target thread to be controlled in a predictable way.
100 .B thread_suspend
101 keeps the target thread from executing any further instructions at the
102 user level, including the return from a system call.
103 .B thread_get/set_state
104 allows the examination or modification of the user state of a target
105 thread. However, if a suspended thread was executing within a system call,
106 it also has associated with it a kernel state. This kernel state can not be
107 modified by
108 .B thread_set_state
109 with the result that when the thread is resumed
110 the system call may return changing the user state and possibly user memory.
111 .B thread_abort
112 aborts the kernel call from the target thread's point of view
113 by resetting the kernel state so that the thread will resume execution
114 at the system call return with the return code value set to one of the
115 interrupted codes. The system call itself will either be entirely completed or
116 entirely aborted, depending on the precise moment at which the abort was received.
117 Thus if the thread's user state has been changed by
118 .B thread_set_state
119 , it will not be modified by any unexpected system
120 call side effects.
121
122
123 For example to simulate a Unix signal, the following sequence of calls may be used:
124
125 .B thread_suspend
126 Stops the thread
127
128 .B thread_abort
129 Interrupts any system call in progress,
130 setting the return value to 'interrupted'.
131 Since the thread is stopped, it will not
132 return to user code.
133
134 .B thread_set_state
135 Alters thread's state to simulate a
136 procedure call to the signal handler
137
138 .B thread_resume
139 Resumes execution at the signal handler.
140 If the thread's stack has been correctly
141 set up, the thread may return to the
142 interrupted system call.
143
144 (of course, the code to push an extra stack frame and change the registers
145 is VERY machine-dependent.)
146
147 Calling
148 .B thread_abort
149 on a non-suspended thread is pretty risky, since
150 it is very difficult to know exactly what system trap, if any, the thread might be
151 executing and whether an interrupt return would cause the thread to do
152 something useful.
153
154 .SH DIAGNOSTICS
155 .TP 25
156 KERN_SUCCESS
157 The thread received an interrupt
158 .TP 25
159 KERN_INVALID_ARGUMENT
160 .B target_thread
161 is not a thread.
162
163 .SH SEE ALSO
164 .B thread_info, thread_state, thread_terminate, thread_suspend
165
166
Cache object: 00cea3ca33e065921462ef39e47d27e3
|