'\" te
.\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH RPC_SVC_INPUT 3NSL "Jan 6, 2003"
.SH NAME
rpc_svc_input, svc_add_input, svc_remove_input \- declare or remove a callback
on a file descriptor
.SH SYNOPSIS
.LP
.nf
#include <rpc/rpc.h>

\fBtypedef void (*\fR\fBsvc_callback_t\fR)(\fBsvc_input_id_t\fR \fIid\fR, \fBint\fR \fIfd\fR,
     \fBunsigned int\fR \fIevents\fR, \fBvoid *\fR\fIcookie\fR);
.fi

.LP
.nf
\fBsvc_input_id_t\fR \fBsvc_add_input\fR(\fBint\fR \fIfd\fR, \fBunsigned int\fR \fIrevents\fR,
     \fBsvc_callback_t\fR \fIcallback\fR, \fBvoid *\fR\fIcookie\fR);
.fi

.LP
.nf
\fBint\fR \fBsvc_remove_input\fR(\fBsvc_input_t\fR \fIid\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The following RPC routines are used to declare or remove a callback on a file
descriptor.
.SS "Routines"
.sp
.LP
See \fBrpc\fR(3NSL) for the definition of the \fBSVCXPRT\fR data structure.
.sp
.ne 2
.na
\fBsvc_add_input\fB()\fR\fR
.ad
.RS 22n
This function is used to register a \fIcallback\fR function on a file
descriptor, \fIfd\fR. The file descriptor, \fIfd\fR, is the first parameter to
be passed to \fBsvc_add_input()\fR. This \fIcallback\fR function will be
automatically called if any of the events specified in the \fIevents\fR
parameter occur on this descriptor. The \fIevents\fR parameter is used to
specify when the callback is invoked. This parameter is a mask of poll events
to which the user wants to listen. See \fBpoll\fR(2) for further details of the
events that can be specified.
.sp
The callback to be invoked is specified using the \fIcallback\fR parameter. The
\fIcookie\fR parameter can be used to pass any data to the \fIcallback\fR
function. This parameter is a user-defined value which is passed as an argument
to the \fIcallback\fR function, and it is not used by the Sun RPC library
itself.
.sp
Several callbacks can be registered on the same file descriptor as long as each
callback registration specifies a separate set of event flags.
.sp
The \fIcallback\fR function is called with the registration \fIid\fR, the
\fIfd\fR file descriptor, an \fIrevents\fR value, which is a bitmask of all
events concerning the file descriptor, and the \fIcookie\fR user-defined value.
.sp
Upon successful completion, the function returns a unique identifier for this
registration, that can be used later to remove this callback. Upon failure,
\fB-1\fR is returned and \fBerrno\fR is set to indicate the error.
.sp
The \fBsvc_add_input()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The \fIfd\fR or \fIevents\fR parameters are invalid.
.RE

.sp
.ne 2
.na
\fB\fBEEXIST\fR\fR
.ad
.RS 10n
A callback is already registered to the file descriptor with one of the
specified events.
.RE

.sp
.ne 2
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 10n
Memory is exhausted.
.RE

.RE

.sp
.ne 2
.na
\fB\fBsvc_remove_input()\fR\fR
.ad
.RS 22n
This function is used to unregister a callback function on a file descriptor,
\fIfd\fR. The \fIid\fR parameter specifies the registration to be removed.
.sp
Upon successful completion, the function returns zero. Upon failure, \fB-1\fR
is returned and \fBerrno\fR is set to indicate the error.
.sp
The \fBsvc_remove_input()\fR function will fail if:
.sp
.ne 2
.na
\fBEINVAL\fR
.ad
.RS 10n
The \fIid\fR parameter is invalid.
.RE

.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Architecture	All
_
Interface Stability	Evolving
_
MT-Level	MT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBpoll\fR(2), \fBrpc\fR(3NSL), \fBattributes\fR(5)