lib/libpthread/pthread_suspend_np.3

   1 .\" $NetBSD: pthread_suspend_np.3,v 1.2 2003/11/12 11:58:34 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2003 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Christos Zoulas.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd November 12, 2003
  31 .Dt PTHREAD_SUSPEND_NP 3
  32 .Os
  33 .Sh NAME
  34 .Nm pthread_suspend_np ,
  35 .Nm pthread_resume_np
  36 .Nd suspend/resume the given thread
  37 .Sh LIBRARY
  38 .Lb libpthread
  39 .Sh SYNOPSIS
  40 .In pthread.h
  41 .Ft int
  42 .Fn pthread_suspend_np "pthread_t thread"
  43 .Ft int
  44 .Fn pthread_resume_np "pthread_t thread"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn pthread_suspend_np
  48 function suspends the
  49 .Ar thread
  50 given as argument.
  51 If
  52 .Ar thread
  53 is the currently running thread as returned by
  54 .Xr pthread_self 3 ,
  55 the function fails and returns
  56 .Er EDEADLK .
  57 Otherwise, it removes the named thread from the running queue, and
  58 adds it to the suspended queue.
  59 The
  60 .Ar thread
  61 will remain blocked until
  62 .Fn pthread_resume_np
  63 is called on it.
  64 .Pp
  65 .Fn pthread_resume_np
  66 resumes the
  67 .Ar thread
  68 given as argument, if it was suspended.
  69 .Sh RETURN VALUES
  70 The
  71 .Fn pthread_suspend_np
  72 function returns 0 on success and an error number indicating the
  73 reason for the failure.
  74 The
  75 .Fn pthread_resume_np
  76 function always returns 0.
  77 .Sh ERRORS
  78 .Fn pthread_suspend_np
  79 shall fail if:
  80 .Bl -tag -width Er
  81 .It Bq Er EDEADLK
  82 The thread requested to suspend was the currently running thread.
  83 .El
  84 .Pp
  85 .Fn pthread_resume_np
  86 never fails.
  87 .Sh NOTES
  88 Some
  89 .Fn pthread_suspend_np
  90 implementations may allow suspending the current thread.
  91 This is dangerous, because the semantics of the function would then
  92 require the scheduler to schedule another thread, causing a thread
  93 context switch.
  94 Since that context switch can happen in a signal handler by someone
  95 calling
  96 .Fn pthread_suspend_np
  97 in a signal handler, this is currently not allowed.
  98 .Pp
  99 In
 100 .Fn pthread_resume_np
 101 we don't check if the
 102 .Ar thread
 103 argument is not already suspended.
 104 Some implementations might return an error condition if
 105 .Fn pthread_resume_np
 106 is called on a non-suspended thread.
 107 .Sh SEE ALSO
 108 .Xr pthread_attr_setcreatesuspend_np 3 ,
 109 .Xr pthread_self 3