man/XtAppAddSignal.man

   1 .\" Copyright (c) 1993, 1994  X Consortium
   2 .\"
   3 .\" Permission is hereby granted, free of charge, to any person obtaining a
   4 .\" copy of this software and associated documentation files (the "Software"),
   5 .\" to deal in the Software without restriction, including without limitation
   6 .\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
   7 .\" and/or sell copies of the Software, and to permit persons to whom the
   8 .\" Software furnished to do so, subject to the following conditions:
   9 .\"
  10 .\" The above copyright notice and this permission notice shall be included in
  11 .\" all copies or substantial portions of the Software.
  12 .\"
  13 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  14 .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  15 .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  16 .\" THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  17 .\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
  18 .\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  19 .\" SOFTWARE.
  20 .\"
  21 .\" Except as contained in this notice, the name of the X Consortium shall not
  22 .\" be used in advertising or otherwise to promote the sale, use or other
  23 .\" dealing in this Software without prior written authorization from the
  24 .\" X Consortium.
  25 .\"
  26 .ds tk X Toolkit
  27 .ds xT X Toolkit Intrinsics \- C Language Interface
  28 .ds xI Intrinsics
  29 .ds xW X Toolkit Athena Widgets \- C Language Interface
  30 .ds xL Xlib \- C Language X Interface
  31 .ds xC Inter-Client Communication Conventions Manual
  32 .ds Rn 3
  33 .ds Vn 2.2
  34 .hw XtApp-Add-Signal wid-get
  35 .na
  36 .de Ds
  37 .nf
  38 .\\$1D \\$2 \\$1
  39 .ft CW
  40 .ps \\n(PS
  41 .\".if \\n(VS>=40 .vs \\n(VSu
  42 .\".if \\n(VS<=39 .vs \\n(VSp
  43 ..
  44 .de De
  45 .ce 0
  46 .if \\n(BD .DF
  47 .nr BD 0
  48 .in \\n(OIu
  49 .if \\n(TM .ls 2
  50 .sp \\n(DDu
  51 .fi
  52 ..
  53 .de IN          \" send an index entry to the stderr
  54 ..
  55 .de Pn
  56 .ie t \\$1\fB\^\\$2\^\fR\\$3
  57 .el \\$1\fI\^\\$2\^\fP\\$3
  58 ..
  59 .de ZN
  60 .ie t \fB\^\\$1\^\fR\\$2
  61 .el \fI\^\\$1\^\fP\\$2
  62 ..
  63 .ny0
  64 .TH XtAppAddSignal __libmansuffix__ __xorgversion__ "XT FUNCTIONS"
  65 .SH NAME
  66 XtAppAddSignal, XtRemoveSignal, XtNoticeSignal \- register and remove a signal source
  67 .SH SYNTAX
  68 .HP
  69 XtSignalId XtAppAddSignal(XtAppContext \fIapp_context\fP, XtSignalCallbackProc
  70 \fIproc\fP, XtPointer \fIclient_data\fP);
  71 .HP
  72 void XtRemoveSignal(XtSignalId \fIid\fP);
  73 .HP
  74 void XtNoticeSignal(XtSignalId \fIid\fP);
  75 .SH ARGUMENTS
  76 .IP \fIapp_context\fP 1i
  77 Specifies the application context.
  78 .IP \fIclient_data\fP 1i
  79 Specifies the argument that is to be passed to the specified procedure
  80 when a signal has been raised.
  81 .IP \fIid\fP 1i
  82 Specifies the ID returned from the corresponding
  83 .ZN XtAppAddSignal
  84 call.
  85 .IP \fIproc\fP 1i
  86 Specifies the procedure that is to be called when the signal has been
  87 raised.
  88 .SH DESCRIPTION
  89 The
  90 .ZN XtAppAddSignal
  91 function initiates a mechanism for handling signals within the context
  92 of the Intrinsics. Prior to establishing an operating system dependent
  93 signal handler the application may call
  94 .ZN XtAppAddSignal
  95 and store the returned \fIid\fP in a place accessible to the signal
  96 handler.
  97 .LP
  98 Upon receipt of a signal from the operating system, the application may
  99 call
 100 .ZN XtNoticeSignal
 101 passing the \fIid\fP returned by the call to
 102 .ZN XtAppAddSignal .
 103 .LP
 104 .ZN XtNoticeSignal
 105 is the only Intrinsics function that can safely be called from a signal
 106 handler. If
 107 .ZN XtNoticeSignal
 108 is called multiple times before the Intrinsics are able to invoke the
 109 registered callback, the callback is only called once. Logically the
 110 Intrinsics maintain ``pending'' for each registered callback. This
 111 flag is initially
 112 .ZN False
 113 and is set to
 114 .ZN True
 115 by
 116 .ZN XtNoticeSignal ;
 117 the Intrinsics invoke the callback whenever the flag is
 118 .ZN True ,
 119 and the flag is set to
 120 .ZN False
 121 just before the callback is invoked.
 122 .LP
 123 The
 124 .ZN XtRemoveSignal
 125 function is called to remove the specified Intrinsics signal handler. The
 126 client should disable the source of the signal before calling
 127 .ZN XtRemoveSignal .
 128 .SH "SEE ALSO"
 129 XtAppAddTimeOut(__libmansuffix__),XtAppAddInput(__libmansuffix__),XtAppAddWorkProc(__libmansuffix__)
 130 .br
 131 \fI\*(xT\fP
 132 .br
 133 \fI\*(xL\fP