usr/src/man/man3c/port_alert.3c

   1 '\" te
   2 .\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PORT_ALERT 3C "April 9, 2016"
   7 .SH NAME
   8 port_alert \- set a port in alert mode
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <port.h>
  13
  14 \fBint\fR \fBport_alert\fR(\fBint\fR \fIport\fR, \fBint\fR \fIflags\fR, \fBint\fR \fIevents\fR, \fBvoid *\fR\fIuser\fR);
  15 .fi
  16
  17 .SH DESCRIPTION
  18 .LP
  19 The \fBport_alert()\fR function transitions a port into or out of alert mode.
  20 A port in alert mode immediately awakens all threads blocked in
  21 \fBport_get\fR(3C) or \fBport_getn\fR(3C). These threads return with an alert
  22 notification that consists of a single \fBport_event_t\fR structure with the
  23 source \fBPORT_SOURCE_ALERT\fR. Subsequent threads trying to retrieve events
  24 from a port that is in alert mode will return immediately with the alert
  25 notification.
  26 .sp
  27 .LP
  28 A port is transitioned into alert mode by calling the \fBport_alert()\fR
  29 function with a non-zero \fIevents\fR parameter.  The specified \fIevents\fR
  30 and \fIuser\fR parameters will be made available in the \fBportev_events\fR and
  31 the \fBportev_user\fR members of the alert notification, respectively. The
  32 \fIflags\fR argument determines the mode of operation of the alert mode:
  33 .RS +4
  34 .TP
  35 .ie t \(bu
  36 .el o
  37 If \fIflags\fR is set to \fBPORT_ALERT_SET\fR, \fBport_alert()\fR sets the port
  38 in alert mode independent of the current state of the port.  The
  39 \fBportev_events\fR and \fBportev_user\fR members are set or updated
  40 accordingly.
  41 .RE
  42 .RS +4
  43 .TP
  44 .ie t \(bu
  45 .el o
  46 If \fIflags\fR is set to \fBPORT_ALERT_UPDATE\fR and the port is not in alert
  47 mode, \fBport_alert()\fR transitions the port into alert mode.  The
  48 \fBportev_events\fR and \fBportev_user\fR members are set accordingly.
  49 .RE
  50 .RS +4
  51 .TP
  52 .ie t \(bu
  53 .el o
  54 If \fIflags\fR is set to \fBPORT_ALERT_UPDATE\fR and the port is already in
  55 alert mode, \fBport_alert()\fR returns with an error value of \fBEBUSY\fR.
  56 .RE
  57 .sp
  58 .LP
  59 \fBPORT_ALERT_SET\fR and \fBPORT_ALERT_UPDATE\fR are mutually exclusive.
  60 .sp
  61 .LP
  62 A port is transitioned out of alert mode by calling the \fBport_alert()\fR
  63 function with a zero \fIevents\fR parameter.
  64 .sp
  65 .LP
  66 Events can be queued to a port that is in alert mode, but they will not be
  67 retrievable until the port is transitioned out of alert mode.
  68 .SH RETURN VALUES
  69 .LP
  70 Upon successful completion, 0 is returned. Otherwise, -1 is returned and
  71 \fBerrno\fR is set to indicate the error.
  72 .SH ERRORS
  73 .LP
  74 The \fBport_alert()\fR function will fail if:
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBEBADF\fR\fR
  79 .ad
  80 .RS 10n
  81 The port identifier is not valid.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fBEBADFD\fR\fR
  88 .ad
  89 .RS 10n
  90 The \fIport\fR argument is not an event port file descriptor.
  91 .RE
  92
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fBEBUSY\fR\fR
  97 .ad
  98 .RS 10n
  99 The port is already in alert mode.
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fBEINVAL\fR\fR
 106 .ad
 107 .RS 10n
 108 Mutually exclusive \fIflags\fR are set.
 109 .RE
 110
 111 .SH ATTRIBUTES
 112 .LP
 113 See \fBattributes\fR(5) for descriptions of the following attributes:
 114 .sp
 115
 116 .sp
 117 .TS
 118 box;
 119 c | c
 120 l | l .
 121 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 122 _
 123 Architecture    all
 124 _
 125 Interface Stability     Evolving
 126 _
 127 MT-Level        Safe
 128 .TE
 129
 130 .SH SEE ALSO
 131 .LP
 132 \fBport_associate\fR(3C), \fBport_create\fR(3C), \fBport_get\fR(3C),
 133 \fBport_send\fR(3C), \fBattributes\fR(5)