usr/src/man/man3socket/sctp_bindx.3socket

   1 '\" te
   2 .\" Copyright (c) 2007, 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 SCTP_BINDX 3SOCKET "Aug 22, 2007"
   7 .SH NAME
   8 sctp_bindx \- add or remove IP addresses to or from an SCTP socket
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR \fB -lsctp \fR [ \fIlibrary\fR... ]
  13 #include <sys/types.h>
  14 #include <sys/socket.h>
  15 #include <netinet/sctp.h>
  16
  17 \fBint\fR \fBsctp_bindx\fR(\fBint\fR \fIsock\fR, \fBvoid *\fR\fIaddrs\fR, \fBint\fR \fIaddrcnt\fR, \fBint\fR \fIflags\fR);
  18 .fi
  19
  20 .SH DESCRIPTION
  21 .LP
  22 The \fBsctp_bindx()\fR function adds or removes addresses to or from an SCTP
  23 socket. If \fIsock\fR is an Internet Protocol Version 4 (IPv4) socket,
  24 \fIaddrs\fR should be an array of \fBsockaddr_in\fR structures containing IPv4
  25 addresses. If \fIsock\fR is an Internet Protocol Version 6 (IPv6) socket,
  26 \fIaddrs\fR should be an array of \fBsockaddr_in6\fR structures containing IPv6
  27 or IPv4-mapped IPv6 addresses. The \fIaddrcnt\fR is the number of array
  28 elements in \fIaddrs\fR. The family of the address type is used with
  29 \fIaddrcnt\fR to determine the size of the array.
  30 .sp
  31 .LP
  32 The \fIflags\fR parameter is a bitmask that indicates whether addresses are to
  33 be added or removed from a socket. The \fIflags\fR parameter is formed by
  34 bitwise OR of zero or more of the following flags:
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fBSCTP_BINDX_ADD_ADDR\fR\fR
  39 .ad
  40 .RS 23n
  41 Indicates that addresses from \fIaddrs\fR should be added to the SCTP socket.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fBSCTP_BINDX_REM_ADDR\fR\fR
  48 .ad
  49 .RS 23n
  50 Indicates that addresses from \fIaddrs\fR should be removed from the SCTP
  51 socket.
  52 .RE
  53
  54 .sp
  55 .LP
  56 These two flags are mutually exclusive. If \fIflags\fR is formed by a bitwise
  57 OR of both \fBSCTP_BINDX_ADD_ADDR\fR and \fBSCTP_BINDX_REM_ADDR\fR, the
  58 \fBsctp_bindx()\fR function will fail.
  59 .sp
  60 .LP
  61 Prior to calling \fBsctp_bindx()\fR on an SCTP endpoint, the endpoint should be
  62 bound using \fBbind\fR(3SOCKET). On a listening socket, a special
  63 \fBINADDR_ANY\fR value for IP or an unspecified address of all zeros for IPv6
  64 can be used in \fIaddrs\fR to add all IPv4 or IPv6 addresses on the system to
  65 the socket. The \fBsctp_bindx()\fR function can also be used to add or remove
  66 addresses to or from an established association. In such a case, messages are
  67 exchanged between the SCTP endpoints to update the address lists for that
  68 association if both endpoints support dynamic address reconfiguration.
  69 .SH RETURN VALUES
  70 .LP
  71 Upon successful completion, the \fBsctp_bindx()\fR function returns \fB0\fR.
  72 Otherwise, the function returns \fB-1\fR and sets \fBerrno\fR to indicate the
  73 error.
  74 .SH ERRORS
  75 .LP
  76 The \fBsctp_bindx()\fR call fails under the following conditions.
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fBEBADF\fR\fR
  81 .ad
  82 .RS 12n
  83 The \fIsock\fR argument is an invalid file descriptor.
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBENOTSOCK\fR\fR
  90 .ad
  91 .RS 12n
  92 The \fIsock\fR argument is not a socket.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBEINVAL\fR\fR
  99 .ad
 100 .RS 12n
 101 One or more of the IPv4 or IPv6 addresses is invalid.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBEINVAL\fR\fR
 108 .ad
 109 .RS 12n
 110 The endpoint is not bound.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fBEINVAL\fR\fR
 117 .ad
 118 .RS 12n
 119 The last address is requested to be removed from an established association.
 120 .RE
 121
 122 .SH ATTRIBUTES
 123 .LP
 124 See \fBattributes\fR(5) for descriptions of the following attributes:
 125 .sp
 126
 127 .sp
 128 .TS
 129 box;
 130 c | c
 131 l | l .
 132 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 133 _
 134 Interface Stability     Committed
 135 _
 136 MT-Level        Safe
 137 .TE
 138
 139 .SH SEE ALSO
 140 .LP
 141 \fBbind\fR(3SOCKET), \fBin.h\fR(3HEAD), \fBlibsctp\fR(3LIB),
 142 \fBlisten\fR(3SOCKET), \fBsctp_freeladdrs\fR(3SOCKET),
 143 \fBsctp_freepaddrs\fR(3SOCKET), \fBsctp_getladdrs\fR(3SOCKET),
 144 \fBsctp_getpaddrs\fR(3SOCKET), \fBsockaddr\fR(3SOCKET), \fBsocket\fR(3SOCKET),
 145 \fBinet\fR(7P), \fBinet6\fR(7P), \fBip\fR(7P), \fBip6\fR(7P), \fBsctp\fR(7P)
 146
 147 .SH NOTES
 148 .LP
 149 IPv4-mapped addresses are not recommended.