The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/man/thread_abort.man

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

    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: d4dcfea00207185347f5808246f7d865


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.