path: root/usr/src/man/man3dat/dat_ep_modify.3dat

'\" te
.\" This manual page is derived from the DAT/uDAPL 1.2 specification.
.\" Portions Copyright (c) 2007, 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 DAT_EP_MODIFY 3DAT "Jul 16, 2004"
.SH NAME
dat_ep_modify \- change parameters of an Endpoint
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <\fBdat/udat.h\fR>

DAT_RETURN
    dat_ep_modify (
    IN    DAT_EP_HANDLE        ep_handle,
    IN    DAT_EP_PARAM_MASK    ep_param_mask,
    IN    DAT_EP_PARAM         *ep_param
    )
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIep_handle\fR\fR
.ad
.RS 17n
Handle for an instance of the Endpoint.
.RE

.sp
.ne 2
.na
\fB\fIep_param_mask\fR\fR
.ad
.RS 17n
Mask for Endpoint parameters.
.RE

.sp
.ne 2
.na
\fB\fIep_param\fR\fR
.ad
.RS 17n
Pointer to the Consumer-allocated structure that contains Consumer-requested
Endpoint parameters.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBdat_ep_modify()\fR function provides the Consumer a way to change
parameters of an Endpoint.
.sp
.LP
The \fIep_param_mask\fR parameter allows Consumers to specify which parameters
to modify. Providers modify values for \fIep_param_mask\fR requested parameters
only.
.sp
.LP
Not all the parameters of the Endpoint can be modified. Some can be modified
only when the Endpoint is in a specific state. The following list specifies
which parameters can be modified and when they can be modified.
.sp
.ne 2
.na
\fBInterface Adapter\fR
.ad
.sp .6
.RS 4n
Cannot be modified.
.sp
Endpoint belongs to an open instance of IA and that association cannot be
changed.
.RE

.sp
.ne 2
.na
\fBEndpoint State\fR
.ad
.sp .6
.RS 4n
Cannot be modified.
.sp
State of Endpoint cannot be changed by a \fBdat_ep_modify()\fR operation.
.RE

.sp
.ne 2
.na
\fBLocal IA Address\fR
.ad
.sp .6
.RS 4n
Cannot be modified.
.sp
Local IA Address cannot be changed by a \fBdat_ep_modify()\fR operation.
.RE

.sp
.ne 2
.na
\fBLocal Port Qualifier\fR
.ad
.sp .6
.RS 4n
Cannot be modified.
.sp
Local port qualifier cannot be changed by a \fBdat_ep_modify()\fR operation.
.RE

.sp
.ne 2
.na
\fBRemote IA Address\fR
.ad
.sp .6
.RS 4n
Cannot be modified.
.sp
Remote IA Address cannot be changed by a \fBdat_ep_modify()\fR operation.
.RE

.sp
.ne 2
.na
\fBRemote Port Qualifier\fR
.ad
.sp .6
.RS 4n
Cannot be modified.
.sp
Remote port qualifier cannot be changed by a \fBdat_ep_modify()\fR operation
.RE

.sp
.ne 2
.na
\fBProtection Zone\fR
.ad
.sp .6
.RS 4n
Can be modified when in Quiescent, Unconnected, and Tentative Connection
Pending states.
.sp
Protection Zone can be changed only when the Endpoint is in quiescent state.
The only Endpoint states that isare quiescent isare
\fBDAT_EP_STATE_UNCONNECTED\fR and
\fBDAT_EP_STATE_TENTATIVE_CONNECTION_PENDING\fR. Consumers should be aware that
any Receive DTOs currently posted to the Endpoint that do not match the new
Protection Zone fail with a \fBDAT_PROTECTION_VIOLATION\fR return.
.RE

.sp
.ne 2
.na
\fBIn DTO Event Dispatcher\fR
.ad
.sp .6
.RS 4n
Can be modified when in Unconnected, Reserved, Passive Connection Request
Pending, and Tentative Connection Pending states.
.sp
Event Dispatcher for incoming DTOs (Receive) can be changed only prior to a
request for a connection for an Active side or prior to accepting a Connection
Request for a Passive side.
.RE

.sp
.ne 2
.na
\fBOut DTO Event Dispatcher\fR
.ad
.sp .6
.RS 4n
Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
Tentative Connection Pending states.
.sp
Event Dispatcher for outgoing DTOs (Send, RDMA Read, and RDMA Write) can be
changed only prior to a request for a connection for an Active side or prior to
accepting a Connection Request for a Passive side.
.RE

.sp
.ne 2
.na
\fBConnection Event Dispatcher\fR
.ad
.sp .6
.RS 4n
Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
Tentative Connection Pending states.
.sp
Event Dispatcher for the Endpoint Connection events can be changed only prior
to a request for a connection for an Active side or accepting a Connection
Request for a Passive side.
.RE

.sp
.ne 2
.na
\fBService Type\fR
.ad
.sp .6
.RS 4n
Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
Tentative Connection Pending states.
.sp
Service Type can be changed only prior to a request for a connection for an
Active side or accepting a Connection Request for a Passive side.
.RE

.sp
.ne 2
.na
\fBMaximum Message Size\fR
.ad
.sp .6
.RS 4n
Can be modified when in Unconnected, Reserved, Passive Connection Request
Pending, and Tentative Connection Pending states.
.sp
Maximum Message Size can be changed only prior to a request for a connection
for an Active side or accepting a Connection Request for a Passive side.
.RE

.sp
.ne 2
.na
\fBMaximum RDMA Size\fR
.ad
.sp .6
.RS 4n
Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
Tentative Connection Pending states.
.sp
Maximum RDMA Size can be changed only prior to a request for a connection for
an Active side or accepting a Connection Request for a Passive side.
.RE

.sp
.ne 2
.na
\fBQuality of Service\fR
.ad
.sp .6
.RS 4n
Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
Tentative Connection Pending states.
.sp
QoS can be changed only prior to a request for a connection for an Active side
or accepting a Connection Request for a Passive side.
.RE

.sp
.ne 2
.na
\fBRecv Completion Flags\fR
.ad
.sp .6
.RS 4n
Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
Tentative Connection Pending states.
.sp
Recv Completion Flags specifies what DTO flags the Endpoint should support for
Receive DTO operations. The value can be
\fBDAT_COMPLETION_NOTIFICATION_SUPPRESS_FLAG\fR,
\fBDAT_COMPLETION_SOLICITED_WAIT_FLAG\fR, or
\fBDAT_COMPLETION_EVD_THRESHOLD_FLAG\fR. Recv posting does not support
\fBDAT_COMPLETION_SUPPRESS_FLAG\fR or \fBDAT_COMPLETION_BARRIER_FENCE_FLAG\fR
dat_completion_flags values that are only applicable to Request postings. Recv
Completion Flags can be changed only prior to a request for a connection for an
Active side or accepting a Connection Request for a Passive side, but before
posting of any Recvs.
.RE

.sp
.ne 2
.na
\fBRequest Completion Flags\fR
.ad
.sp .6
.RS 4n
Can be modified when in Unconnected, Reserved, Passive Connection Request
Pending, and Tentative Connection Pending states.
.sp
Request Completion Flags specifies what DTO flags the Endpoint should support
for Send, RDMA Read, RDMA Write, and RMR Bind operations. The value can be:
\fBDAT_COMPLETION_UNSIGNALLED_FLAG\fR or
\fBDAT_COMPLETION_EVD_THRESHOLD_FLAG\fR. Request postings always support
\fBDAT_COMPLETION_SUPPRESS_FLAG\fR, \fBDAT_COMPLETION_SOLICITED_WAIT_FLAG\fR,
or \fBDAT_COMPLETION_BARRIER_FENCE_FLAG\fR completion_flags values. Request
Completion Flags can be changed only prior to a request for a connection for an
Active side or accepting a Connection Request for a Passive side.
.RE

.sp
.ne 2
.na
\fBMaximum Recv DTO\fR
.ad
.sp .6
.RS 4n
Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
Tentative Connection Pending states.
.sp
Maximum Recv DTO specifies the maximum number of outstanding Consumer-submitted
Receive DTOs that a Consumer expects at any time at the Endpoint. Maximum Recv
DTO can be changed only prior to a request for a connection for an Active side
or accepting a Connection Request for a Passive side.
.RE

.sp
.ne 2
.na
\fBMaximum Request DTO\fR
.ad
.sp .6
.RS 4n
Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
Tentative Connection Pending states.
.sp
Maximum Request DTO specifies the maximum number of outstanding
Consumer-submitted send and RDMA DTOs and RMR Binds that a Consumer expects at
any time at the Endpoint. Maximum Out DTO can be changed only prior to a
request for a connection for an Active side or accepting a Connection Request
for a Passive side.
.RE

.sp
.ne 2
.na
\fBMaximum Recv IOV\fR
.ad
.sp .6
.RS 4n
Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
Tentative Connection Pending states.
.sp
Maximum Recv IOV specifies the maximum number of elements in IOV that a
Consumer specifies for posting a Receive DTO for the Endpoint. Maximum Recv IOV
can be changed only prior to a request for a connection for an Active side or
accepting a Connection Request for a Passive side.
.RE

.sp
.ne 2
.na
\fBMaximum Request IOV\fR
.ad
.sp .6
.RS 4n
Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
Tentative Connection Pending states.
.sp
Maximum Request IOV specifies the maximum number of elements in IOV that a
Consumer specifies for posting a Send, RDMA Read, or RDMA Write DTO for the
Endpoint. Maximum Request IOV can be changed only prior to a request for a
connection for an Active side or accepting a Connection Request for a Passive
side.
.RE

.sp
.ne 2
.na
\fBMaximum outstanding RDMA Read as target\fR
.ad
.sp .6
.RS 4n
Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
Tentative Connection Pending states.
.sp
Maximum number of outstanding RDMA Reads for which the Endpoint is the target.
.RE

.sp
.ne 2
.na
\fBMaximum outstanding RDMA Read as originator\fR
.ad
.sp .6
.RS 4n
Can be modified when in Unconnected, Reserved, Passive Connection Pending, and
Tentative Connection Pending states.
.sp
Maximum number of outstanding RDMA Reads for which the Endpoint is the
originator.
.RE

.sp
.ne 2
.na
\fBNum transport-specific attributes\fR
.ad
.sp .6
.RS 4n
Can be modified when in Quiescent (unconnected) state.
.sp
Number of transport-specific attributes to be modified.
.RE

.sp
.ne 2
.na
\fBTransport-specific endpoint attributes\fR
.ad
.sp .6
.RS 4n
Can be modified when in Quiescent (unconnected) state.
.sp
Transport-specific attributes can be modified only in the transport-defined
Endpoint state. The only guaranteed safe state in which to modify
transport-specific Endpoint attributes is the quiescent state
\fBDAT_EP_STATE_UNCONNECTED\fR.
.RE

.sp
.ne 2
.na
\fBNum provider-specific attributes\fR
.ad
.sp .6
.RS 4n
Can be modified when in Quiescent (unconnected) state.
.sp
 Number of Provider-specific attributes to be modified.
.RE

.sp
.ne 2
.na
\fBProvider-specific endpoint attributes\fR
.ad
.sp .6
.RS 4n
Can be modified when in Quiescent (unconnected) state.
.sp
Provider-specific attributes can be modified only in the Provider-defined
Endpoint state. The only guaranteed safe state in which to modify
Provider-specific Endpoint attributes is the quiescent state
\fBDAT_EP_STATE_UNCONNECTED\fR.
.RE

.SH RETURN VALUES
.sp
.ne 2
.na
\fB\fBDAT_SUCCESS\fR\fR
.ad
.RS 25n
The operation was successful.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_HANDLE\fR\fR
.ad
.RS 25n
The \fIep_handle\fR parameter is invalid.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_PARAMETER\fR\fR
.ad
.RS 25n
The \fIep_param_mask\fR parameter is invalid, or one of the requested Endpoint
parameters or attributes was invalid, not supported, or cannot be modified.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_STATE\fR\fR
.ad
.RS 25n
Parameter in an invalid state. The Endpoint was not in the state that allows
one of the parameters or attributes to be modified.
.RE

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

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard: uDAPL, 1.1, 1.2
_
MT-Level	Unsafe
.TE

.SH SEE ALSO
.sp
.LP
.BR libdat (3LIB),
.BR attributes (7)