diff options
Diffstat (limited to 'usr/src/man/man3socket')
37 files changed, 8711 insertions, 0 deletions
diff --git a/usr/src/man/man3socket/Makefile b/usr/src/man/man3socket/Makefile new file mode 100644 index 0000000000..8f45ee3e02 --- /dev/null +++ b/usr/src/man/man3socket/Makefile @@ -0,0 +1,237 @@ +# +# This file and its contents are supplied under the terms of the +# Common Development and Distribution License ("CDDL"), version 1.0. +# You may only use this file in accordance with the terms of version +# 1.0 of the CDDL. +# +# A full copy of the text of the CDDL should have accompanied this +# source. A copy of the CDDL is also available via the Internet +# at http://www.illumos.org/license/CDDL. +# + +# Copyright 2011, Richard Lowe + +include ../../Makefile.master + +MANSECT = 3socket + +MANFILES = accept.3socket \ + bind.3socket \ + byteorder.3socket \ + connect.3socket \ + ethers.3socket \ + getaddrinfo.3socket \ + getipnodebyname.3socket \ + getnetbyname.3socket \ + getpeername.3socket \ + getprotobyname.3socket \ + getservbyname.3socket \ + getsockname.3socket \ + getsockopt.3socket \ + getsourcefilter.3socket \ + icmp6_filter.3socket \ + if_nametoindex.3socket \ + inet.3socket \ + inet6_opt.3socket \ + inet6_rth.3socket \ + listen.3socket \ + rcmd.3socket \ + recv.3socket \ + rexec.3socket \ + sctp_bindx.3socket \ + sctp_getladdrs.3socket \ + sctp_getpaddrs.3socket \ + sctp_opt_info.3socket \ + sctp_peeloff.3socket \ + sctp_recvmsg.3socket \ + sctp_send.3socket \ + sctp_sendmsg.3socket \ + send.3socket \ + shutdown.3socket \ + socket.3socket \ + socketpair.3socket \ + spray.3socket + +MANSOFILES = endnetent.3socket \ + endprotoent.3socket \ + endservent.3socket \ + ether_aton.3socket \ + ether_hostton.3socket \ + ether_line.3socket \ + ether_ntoa.3socket \ + ether_ntohost.3socket \ + freeaddrinfo.3socket \ + freehostent.3socket \ + gai_strerror.3socket \ + getipnodebyaddr.3socket \ + getipv4sourcefilter.3socket \ + getnameinfo.3socket \ + getnetbyaddr.3socket \ + getnetbyaddr_r.3socket \ + getnetbyname_r.3socket \ + getnetent.3socket \ + getnetent_r.3socket \ + getprotobyname_r.3socket \ + getprotobynumber.3socket \ + getprotobynumber_r.3socket \ + getprotoent.3socket \ + getprotoent_r.3socket \ + getservbyname_r.3socket \ + getservbyport.3socket \ + getservbyport_r.3socket \ + getservent.3socket \ + getservent_r.3socket \ + htonl.3socket \ + htonll.3socket \ + htons.3socket \ + if_freenameindex.3socket \ + if_indextoname.3socket \ + if_nameindex.3socket \ + inet6.3socket \ + inet6_opt_append.3socket \ + inet6_opt_find.3socket \ + inet6_opt_finish.3socket \ + inet6_opt_get_val.3socket \ + inet6_opt_init.3socket \ + inet6_opt_next.3socket \ + inet6_opt_set_val.3socket \ + inet6_rth_add.3socket \ + inet6_rth_getaddr.3socket \ + inet6_rth_init.3socket \ + inet6_rth_reverse.3socket \ + inet6_rth_segments.3socket \ + inet6_rth_space.3socket \ + inet_addr.3socket \ + inet_aton.3socket \ + inet_lnaof.3socket \ + inet_makeaddr.3socket \ + inet_netof.3socket \ + inet_network.3socket \ + inet_ntoa.3socket \ + inet_ntop.3socket \ + inet_pton.3socket \ + ntohl.3socket \ + ntohll.3socket \ + ntohs.3socket \ + rcmd_af.3socket \ + recvfrom.3socket \ + recvmsg.3socket \ + rexec_af.3socket \ + rresvport.3socket \ + rresvport_af.3socket \ + ruserok.3socket \ + sctp_freeladdrs.3socket \ + sctp_freepaddrs.3socket \ + sendmsg.3socket \ + sendto.3socket \ + setipv4sourcefilter.3socket \ + setnetent.3socket \ + setprotoent.3socket \ + setservent.3socket \ + setsockopt.3socket \ + setsourcefilter.3socket + +MANFILES += $(MANSOFILES) + +htonl.3socket := SOSRC = man3socket/byteorder.3socket +htonll.3socket := SOSRC = man3socket/byteorder.3socket +htons.3socket := SOSRC = man3socket/byteorder.3socket +ntohl.3socket := SOSRC = man3socket/byteorder.3socket +ntohll.3socket := SOSRC = man3socket/byteorder.3socket +ntohs.3socket := SOSRC = man3socket/byteorder.3socket + +ether_aton.3socket := SOSRC = man3socket/ethers.3socket +ether_hostton.3socket := SOSRC = man3socket/ethers.3socket +ether_line.3socket := SOSRC = man3socket/ethers.3socket +ether_ntoa.3socket := SOSRC = man3socket/ethers.3socket +ether_ntohost.3socket := SOSRC = man3socket/ethers.3socket + +freeaddrinfo.3socket := SOSRC = man3socket/getaddrinfo.3socket +gai_strerror.3socket := SOSRC = man3socket/getaddrinfo.3socket +getnameinfo.3socket := SOSRC = man3socket/getaddrinfo.3socket + +freehostent.3socket := SOSRC = man3socket/getipnodebyname.3socket +getipnodebyaddr.3socket := SOSRC = man3socket/getipnodebyname.3socket + +endnetent.3socket := SOSRC = man3socket/getnetbyname.3socket +getnetbyaddr.3socket := SOSRC = man3socket/getnetbyname.3socket +getnetbyaddr_r.3socket := SOSRC = man3socket/getnetbyname.3socket +getnetbyname_r.3socket := SOSRC = man3socket/getnetbyname.3socket +getnetent.3socket := SOSRC = man3socket/getnetbyname.3socket +getnetent_r.3socket := SOSRC = man3socket/getnetbyname.3socket +setnetent.3socket := SOSRC = man3socket/getnetbyname.3socket + +endprotoent.3socket := SOSRC = man3socket/getprotobyname.3socket +getprotobyname_r.3socket := SOSRC = man3socket/getprotobyname.3socket +getprotobynumber.3socket := SOSRC = man3socket/getprotobyname.3socket +getprotobynumber_r.3socket := SOSRC = man3socket/getprotobyname.3socket +getprotoent.3socket := SOSRC = man3socket/getprotobyname.3socket +getprotoent_r.3socket := SOSRC = man3socket/getprotobyname.3socket +setprotoent.3socket := SOSRC = man3socket/getprotobyname.3socket + +endservent.3socket := SOSRC = man3socket/getservbyname.3socket +getservbyname_r.3socket := SOSRC = man3socket/getservbyname.3socket +getservbyport.3socket := SOSRC = man3socket/getservbyname.3socket +getservbyport_r.3socket := SOSRC = man3socket/getservbyname.3socket +getservent.3socket := SOSRC = man3socket/getservbyname.3socket +getservent_r.3socket := SOSRC = man3socket/getservbyname.3socket +setservent.3socket := SOSRC = man3socket/getservbyname.3socket + +setsockopt.3socket := SOSRC = man3socket/getsockopt.3socket + +getipv4sourcefilter.3socket := SOSRC = man3socket/getsourcefilter.3socket +setipv4sourcefilter.3socket := SOSRC = man3socket/getsourcefilter.3socket +setsourcefilter.3socket := SOSRC = man3socket/getsourcefilter.3socket + +if_freenameindex.3socket := SOSRC = man3socket/if_nametoindex.3socket +if_indextoname.3socket := SOSRC = man3socket/if_nametoindex.3socket +if_nameindex.3socket := SOSRC = man3socket/if_nametoindex.3socket + +inet6.3socket := SOSRC = man3socket/inet.3socket +inet_addr.3socket := SOSRC = man3socket/inet.3socket +inet_aton.3socket := SOSRC = man3socket/inet.3socket +inet_lnaof.3socket := SOSRC = man3socket/inet.3socket +inet_makeaddr.3socket := SOSRC = man3socket/inet.3socket +inet_netof.3socket := SOSRC = man3socket/inet.3socket +inet_network.3socket := SOSRC = man3socket/inet.3socket +inet_ntoa.3socket := SOSRC = man3socket/inet.3socket +inet_ntop.3socket := SOSRC = man3socket/inet.3socket +inet_pton.3socket := SOSRC = man3socket/inet.3socket + +inet6_opt_append.3socket := SOSRC = man3socket/inet6_opt.3socket +inet6_opt_find.3socket := SOSRC = man3socket/inet6_opt.3socket +inet6_opt_finish.3socket := SOSRC = man3socket/inet6_opt.3socket +inet6_opt_get_val.3socket := SOSRC = man3socket/inet6_opt.3socket +inet6_opt_init.3socket := SOSRC = man3socket/inet6_opt.3socket +inet6_opt_next.3socket := SOSRC = man3socket/inet6_opt.3socket +inet6_opt_set_val.3socket := SOSRC = man3socket/inet6_opt.3socket + +inet6_rth_add.3socket := SOSRC = man3socket/inet6_rth.3socket +inet6_rth_getaddr.3socket := SOSRC = man3socket/inet6_rth.3socket +inet6_rth_init.3socket := SOSRC = man3socket/inet6_rth.3socket +inet6_rth_reverse.3socket := SOSRC = man3socket/inet6_rth.3socket +inet6_rth_segments.3socket := SOSRC = man3socket/inet6_rth.3socket +inet6_rth_space.3socket := SOSRC = man3socket/inet6_rth.3socket + +rcmd_af.3socket := SOSRC = man3socket/rcmd.3socket +rresvport.3socket := SOSRC = man3socket/rcmd.3socket +rresvport_af.3socket := SOSRC = man3socket/rcmd.3socket +ruserok.3socket := SOSRC = man3socket/rcmd.3socket + +recvfrom.3socket := SOSRC = man3socket/recv.3socket +recvmsg.3socket := SOSRC = man3socket/recv.3socket + +rexec_af.3socket := SOSRC = man3socket/rexec.3socket + +sctp_freeladdrs.3socket := SOSRC = man3socket/sctp_getladdrs.3socket + +sctp_freepaddrs.3socket := SOSRC = man3socket/sctp_getpaddrs.3socket + +sendmsg.3socket := SOSRC = man3socket/send.3socket +sendto.3socket := SOSRC = man3socket/send.3socket + +.KEEP_STATE: + +include ../Makefile.man + +install: $(ROOTMANFILES) diff --git a/usr/src/man/man3socket/accept.3socket b/usr/src/man/man3socket/accept.3socket new file mode 100644 index 0000000000..c6ad97671a --- /dev/null +++ b/usr/src/man/man3socket/accept.3socket @@ -0,0 +1,228 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (C) 2002, 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 accept 3SOCKET "24 Jan 2002" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +accept \- accept a connection on a socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ] +#include <sys/types.h> +#include <sys/socket.h> + +\fBint\fR \fBaccept\fR(\fBint\fR \fIs\fR, \fBstruct sockaddr *\fR\fIaddr\fR, \fBsocklen_t *\fR\fIaddrlen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The argument \fIs\fR is a socket that has been created with +\fBsocket\fR(3SOCKET) and bound to an address with \fBbind\fR(3SOCKET), and +that is listening for connections after a call to \fBlisten\fR(3SOCKET). The +\fBaccept()\fR function extracts the first connection on the queue of pending +connections, creates a new socket with the properties of \fIs\fR, and allocates +a new file descriptor, \fIns\fR, for the socket. If no pending connections are +present on the queue and the socket is not marked as non-blocking, +\fBaccept()\fR blocks the caller until a connection is present. If the socket +is marked as non-blocking and no pending connections are present on the queue, +\fBaccept()\fR returns an error as described below. The \fBaccept()\fR +function uses the \fBnetconfig\fR(4) file to determine the \fBSTREAMS\fR device +file name associated with \fIs\fR. This is the device on which the connect +indication will be accepted. The accepted socket, \fIns\fR, is used to read and +write data to and from the socket that connected to \fIns\fR. It is not used to +accept more connections. The original socket (\fIs\fR) remains open for +accepting further connections. +.sp +.LP +The argument \fIaddr\fR is a result parameter that is filled in with the +address of the connecting entity as it is known to the communications layer. +The exact format of the \fIaddr\fR parameter is determined by the domain in +which the communication occurs. +.sp +.LP +The argument \fIaddrlen\fR is a value-result parameter. Initially, it contains +the amount of space pointed to by \fIaddr\fR; on return it contains the length +in bytes of the address returned. +.sp +.LP +The \fBaccept()\fR function is used with connection-based socket types, +currently with \fBSOCK_STREAM\fR. +.sp +.LP +It is possible to \fBselect\fR(3C) or \fBpoll\fR(2) a socket for the purpose of +an \fBaccept()\fR by selecting or polling it for a read. However, this will +only indicate when a connect indication is pending; it is still necessary to +call \fBaccept()\fR. +.SH RETURN VALUES +.sp +.LP +The \fBaccept()\fR function returns \fB\(mi1\fR on error. If it succeeds, it +returns a non-negative integer that is a descriptor for the accepted socket. +.SH ERRORS +.sp +.LP +\fBaccept()\fR will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 16n +.rt +The descriptor is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECONNABORTED\fR\fR +.ad +.RS 16n +.rt +The remote side aborted the connection before the \fBaccept()\fR operation +completed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 16n +.rt +The \fIaddr\fR parameter or the \fIaddrlen\fR parameter is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 16n +.rt +The \fBaccept()\fR attempt was interrupted by the delivery of a signal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 16n +.rt +The per-process descriptor table is full. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENODEV\fR\fR +.ad +.RS 16n +.rt +The protocol family and type corresponding to \fIs\fR could not be found in +the \fBnetconfig\fR file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 16n +.rt +There was insufficient user memory available to complete the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 16n +.rt +There were insufficient \fBSTREAMS\fR resources available to complete the +operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 16n +.rt +The descriptor does not reference a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 16n +.rt +The referenced socket is not of type \fBSOCK_STREAM\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPROTO\fR\fR +.ad +.RS 16n +.rt +A protocol error has occurred; for example, the \fBSTREAMS\fR protocol stack +has not been initialized or the connection has already been released. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEWOULDBLOCK\fR\fR +.ad +.RS 16n +.rt +The socket is marked as non-blocking and no connections are present to be +accepted. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpoll\fR(2), \fBbind\fR(3SOCKET), \fBconnect\fR(3SOCKET), +\fBlisten\fR(3SOCKET), \fBselect\fR(3C), \fBsocket.h\fR(3HEAD), +\fBsocket\fR(3SOCKET), \fBnetconfig\fR(4), \fBattributes\fR(5) diff --git a/usr/src/man/man3socket/bind.3socket b/usr/src/man/man3socket/bind.3socket new file mode 100644 index 0000000000..0f98ab7014 --- /dev/null +++ b/usr/src/man/man3socket/bind.3socket @@ -0,0 +1,233 @@ +'\" te +.\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" 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 bind 3SOCKET "11 May 2009" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +bind \- bind a name to a socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ] +#include <sys/types.h> +#include <sys/socket.h> + + + +\fBint\fR \fBbind\fR(\fBint\fR \fIs\fR, \fBconst struct sockaddr *\fR\fIname\fR, \fBint\fR \fInamelen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBbind()\fR function assigns a name to an unnamed socket. When a socket is +created with \fBsocket\fR(3SOCKET), it exists in a name space (address family) +but has no name assigned. The \fBbind()\fR function requests that the name +pointed to by \fIname\fR be assigned to the socket. +.SH RETURN VALUES +.sp +.LP +Upon successful completion \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBbind()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 17n +.rt +The requested address is protected, and \fB{PRIV_NET_PRIVADDR}\fR is not +asserted in the effective set of the current process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEADDRINUSE\fR\fR +.ad +.RS 17n +.rt +The specified address is already in use. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEADDRNOTAVAIL\fR\fR +.ad +.RS 17n +.rt +The specified address is not available on the local machine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 17n +.rt +\fIs\fR is not a valid descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 17n +.rt +\fInamelen\fR is not the size of a valid address for the specified address +family. +.sp +The socket is already bound to an address. +.sp +Socket options are inconsistent with port attributes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 17n +.rt +There were insufficient \fBSTREAMS\fR resources for the operation to complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 17n +.rt +\fIs\fR is a descriptor for a file, not a socket. +.RE + +.sp +.LP +The following errors are specific to binding names in the UNIX domain: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 11n +.rt +Search permission is denied for a component of the path prefix of the pathname +in \fIname\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 11n +.rt +An I/O error occurred while making the directory entry or allocating the inode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEISDIR\fR\fR +.ad +.RS 11n +.rt +A null pathname was specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 11n +.rt +Too many symbolic links were encountered in translating the pathname in +\fIname\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 11n +.rt +A component of the path prefix of the pathname in \fIname\fR does not exist. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 11n +.rt +A component of the path prefix of the pathname in \fIname\fR is not a +directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEROFS\fR\fR +.ad +.RS 11n +.rt +The inode would reside on a read-only file system. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBunlink\fR(2), \fBsocket\fR(3SOCKET), \fBattributes\fR(5), +\fBprivileges\fR(5), \fBsocket.h\fR(3HEAD) +.SH NOTES +.sp +.LP +Binding a name in the UNIX domain creates a socket in the file system that must +be deleted by the caller when it is no longer needed by using \fBunlink\fR(2). +.sp +.LP +The rules used in name binding vary between communication domains. diff --git a/usr/src/man/man3socket/byteorder.3socket b/usr/src/man/man3socket/byteorder.3socket new file mode 100644 index 0000000000..63984a833f --- /dev/null +++ b/usr/src/man/man3socket/byteorder.3socket @@ -0,0 +1,81 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" 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 byteorder 3SOCKET "10 Sep 2008" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +byteorder, htonl, htonll, htons, ntohl, ntohll, ntohs \- convert values between +host and network byte order +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR... ] +#include <sys/types.h> +#include <netinet/in.h> +#include <inttypes.h> + +\fBuint32_t\fR \fBhtonl\fR(\fBuint32_t\fR \fIhostlong\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBhtonll\fR(\fBuint64_t\fR \fIhostlonglong\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBhtons\fR(\fBuint16_t\fR \fIhostshort\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBntohl\fR(\fBuint32_t\fR \fInetlong\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBntonll\fR(\fBuint64_t\fR \fIhostlonglong\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBntohs\fR(\fBuint16_t\fR \fInetshort\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions convert 16-bit, 32-bit, and 64-bit quantities between network +byte order and host byte order. On some architectures these routines are +defined as \fINULL\fR macros in the include file <\fBnetinet/in.h\fR>. On other +architectures, the routines are functional when the host byte order is +different from network byte order. +.sp +.LP +These functions are most often used in conjunction with Internet addresses and +ports as returned by \fBgethostent()\fR and \fBgetservent()\fR. See +\fBgethostbyname\fR(3NSL) and \fBgetservbyname\fR(3SOCKET). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgethostbyname\fR(3NSL), \fBgetservbyname\fR(3SOCKET), \fBinet.h\fR(3HEAD), +\fBattributes\fR(5) diff --git a/usr/src/man/man3socket/connect.3socket b/usr/src/man/man3socket/connect.3socket new file mode 100644 index 0000000000..4a47bf0515 --- /dev/null +++ b/usr/src/man/man3socket/connect.3socket @@ -0,0 +1,362 @@ +'\" te +.\" Copyright (C) 2005, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" Copyright 1989 AT&T 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 connect 3SOCKET "08 Mar 2005" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +connect \- initiate a connection on a socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ] +#include <sys/types.h> +#include <sys/socket.h> + + + +\fBint\fR \fBconnect\fR(\fBint\fR \fIs\fR, \fBconst struct sockaddr *\fR\fIname\fR, \fBint\fR \fInamelen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The parameter \fIs\fR is a socket. If it is of type \fBSOCK_DGRAM\fR, +\fBconnect()\fR specifies the peer with which the socket is to be associated. +This address is the address to which datagrams are to be sent if a receiver is +not explicitly designated. This address is the only address from which +datagrams are to be received. If the socket \fIs\fR is of type +\fBSOCK_STREAM\fR, \fBconnect()\fR attempts to make a connection to another +socket. The other socket is specified by \fIname\fR. \fIname\fR is an address +in the communication space of the socket. Each communication space interprets +the \fIname\fR parameter in its own way. If \fIs\fR is not bound, then \fIs\fR +will be bound to an address selected by the underlying transport provider. +Generally, stream sockets can successfully \fBconnect()\fR only once. Datagram +sockets can use \fBconnect()\fR multiple times to change their association. +Datagram sockets can dissolve the association by connecting to a null address. +.SH RETURN VALUES +.sp +.LP +If the connection or binding succeeds, \fB0\fR is returned. Otherwise, +\fB\(mi1\fR is returned and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The call fails if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 17n +.rt +Search permission is denied for a component of the path prefix of the pathname +in \fIname\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEADDRINUSE\fR\fR +.ad +.RS 17n +.rt +The address is already in use. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEADDRNOTAVAIL\fR\fR +.ad +.RS 17n +.rt +The specified address is not available on the remote machine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAFNOSUPPORT\fR\fR +.ad +.RS 17n +.rt +Addresses in the specified address family cannot be used with this socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEALREADY\fR\fR +.ad +.RS 17n +.rt +The socket is non-blocking, and a previous connection attempt has not yet been +completed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 17n +.rt +\fIs\fR is not a valid descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECONNREFUSED\fR\fR +.ad +.RS 17n +.rt +The attempt to connect was forcefully rejected. The calling program should +\fBclose\fR(2) the socket descriptor, and issue another \fBsocket\fR(3SOCKET) +call to obtain a new descriptor before attempting another \fBconnect()\fR call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINPROGRESS\fR\fR +.ad +.RS 17n +.rt +The socket is non-blocking, and the connection cannot be completed immediately. +You can use \fBselect\fR(3C) to complete the connection by selecting the +socket for writing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 17n +.rt +The connection attempt was interrupted before any data arrived by the delivery +of a signal. The connection, however, will be established asynchronously. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 17n +.rt +\fInamelen\fR is not the size of a valid address for the specified address +family. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 17n +.rt +An I/O error occurred while reading from or writing to the file system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEISCONN\fR\fR +.ad +.RS 17n +.rt +The socket is already connected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 17n +.rt +Too many symbolic links were encountered in translating the pathname in +\fIname\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENETUNREACH\fR\fR +.ad +.RS 17n +.rt +The network is not reachable from this host. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEHOSTUNREACH\fR\fR +.ad +.RS 17n +.rt +The remote host is not reachable from this host. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 17n +.rt +A component of the path prefix of the pathname in \fIname\fR does not exist. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 17n +.rt +The socket referred to by the pathname in \fIname\fR does not exist. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 17n +.rt +There were insufficient \fBSTREAMS\fR resources available to complete the +operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 17n +.rt +The server exited before the connection was complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBETIMEDOUT\fR\fR +.ad +.RS 17n +.rt +Connection establishment timed out without establishing a connection. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEWOULDBLOCK\fR\fR +.ad +.RS 17n +.rt +The socket is marked as non-blocking, and the requested operation would block. +.RE + +.sp +.LP +The following errors are specific to connecting names in the UNIX domain. +These errors might not apply in future versions of the UNIX \fBIPC\fR domain. +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 14n +.rt +A component of the path prefix of the pathname in \fIname\fR is not a +directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 14n +.rt +\fIs\fR is not a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 14n +.rt +\fIname\fR is not a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPROTOTYPE\fR\fR +.ad +.RS 14n +.rt +The file that is referred to by \fIname\fR is a socket of a type other than +type \fIs\fR. For example, \fIs\fR is a \fBSOCK_DGRAM\fR socket, while +\fIname\fR refers to a \fBSOCK_STREAM\fR socket. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBaccept\fR(3SOCKET), \fBgetsockname\fR(3SOCKET), +\fBselect\fR(3C), \fBsocket\fR(3SOCKET), \fBsocket.h\fR(3HEAD), +\fBattributes\fR(5) diff --git a/usr/src/man/man3socket/ethers.3socket b/usr/src/man/man3socket/ethers.3socket new file mode 100644 index 0000000000..cf48452411 --- /dev/null +++ b/usr/src/man/man3socket/ethers.3socket @@ -0,0 +1,120 @@ +'\" te +.\" Copyright 1989 AT&T. +.\" Copyright (C) 2004, 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 ethers 3SOCKET "5 Apr 2004" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +ethers, ether_ntoa, ether_aton, ether_ntohost, ether_hostton, ether_line \- +Ethernet address mapping operations +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ] +#include <sys/types.h> +#include <sys/ethernet.h> + +\fBchar *\fR\fBether_ntoa\fR(\fBconst struct ether_addr *\fR\fIe\fR); +.fi + +.LP +.nf +\fBstruct ether_addr *\fR\fBether_aton\fR(\fBconst char *\fR\fIs\fR); +.fi + +.LP +.nf +\fBint\fR \fBether_ntohost\fR(\fBchar *\fR\fIhostname\fR, \fBconst struct ether_addr *\fR\fIe\fR); +.fi + +.LP +.nf +\fBint\fR \fBether_hostton\fR(\fBconst char *\fR\fIhostname\fR, \fBstruct ether_addr *\fR\fIe\fR); +.fi + +.LP +.nf +\fBint\fR \fBether_line\fR(\fBconst char *\fR\fIl\fR, \fBstruct ether_addr *\fR\fIe\fR, \fBchar *\fR\fIhostname\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These routines are useful for mapping 48 bit Ethernet numbers to their ASCII +representations or their corresponding host names, and vice versa. +.sp +.LP +The function \fBether_ntoa()\fR converts a 48 bit Ethernet number pointed to by +\fIe\fR to its standard \fBASCII\fR representation; it returns a pointer to +the \fBASCII\fR string. The representation is of the form +\fIx\fR\|:\|\fIx\fR\|:\|\fIx\fR\|:\| \fIx\fR\|:\|\fIx\fR\|:\|\fIx\fR where +\fIx\fR is a hexadecimal number between \fB0\fR and \fBff\fR. The function +\fBether_aton()\fR converts an \fBASCII\fR string in the standard +representation back to a 48 bit Ethernet number; the function returns +\fINULL\fR if the string cannot be scanned successfully. +.sp +.LP +The function \fBether_ntohost()\fR maps an Ethernet number (pointed to by +\fIe\fR) to its associated hostname. The string pointed to by hostname must be +long enough to hold the hostname and a \fINULL\fR character. The function +returns zero upon success and non-zero upon failure. Inversely, the function +\fBether_hostton()\fR maps a hostname string to its corresponding Ethernet +number; the function modifies the Ethernet number pointed to by \fIe\fR. The +function also returns zero upon success and non-zero upon failure. In order to +do the mapping, both these functions may lookup one or more of the following +sources: the ethers file, the \fBNIS\fR maps \fBethers.byname\fR and +\fBethers.byaddr\fR and the \fBNIS+\fR table \fBethers\fR. The sources and +their lookup order are specified in the \fB/etc/nsswitch.conf\fR file. See +\fBnsswitch.conf\fR(4) for details. +.sp +.LP +The function \fBether_line()\fR scans a line, pointed to by \fIl\fR, and sets +the hostname and the Ethernet number, pointed to by \fIe\fR. The string pointed +to by hostname must be long enough to hold the hostname and a \fINULL\fR +character. The function returns zero upon success and non-zero upon failure. +The format of the scanned line is described by \fBethers\fR(4). +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/ethers\fR\fR +.ad +.RS 22n +.rt +Ethernet address to hostname database or domain +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/nsswitch.conf\fR\fR +.ad +.RS 22n +.rt +configuration file for the name service switch +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBethers\fR(4), \fBnsswitch.conf\fR(4), \fBattributes\fR(5) diff --git a/usr/src/man/man3socket/getaddrinfo.3socket b/usr/src/man/man3socket/getaddrinfo.3socket new file mode 100644 index 0000000000..a322d10c44 --- /dev/null +++ b/usr/src/man/man3socket/getaddrinfo.3socket @@ -0,0 +1,580 @@ +'\" te +.\" Copyright (c) 2009, 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 getaddrinfo 3SOCKET "8 May 2009" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +getaddrinfo, getnameinfo, freeaddrinfo, gai_strerror \- translate between node +name and address +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR \&.\|.\|. \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR \&.\|.\|. ] +#include <sys/socket.h> +#include <netdb.h> + +\fBint\fR \fBgetaddrinfo\fR(\fBconst char *\fR\fInodename\fR, \fBconst char *\fR\fIservname\fR, + \fBconst struct addrinfo *\fR\fIhints\fR, \fBstruct addrinfo **\fR\fIres\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetnameinfo\fR(\fBconst struct sockaddr *\fR\fIsa\fR, \fBsocklen_t\fR \fIsalen\fR, + \fBchar *\fR\fIhost\fR, \fBsize_t\fR \fIhostlen\fR, \fBchar *\fR\fIserv\fR, \fBsize_t\fR \fIservlen\fR, + \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBfreeaddrinfo\fR(\fBstruct addrinfo *\fR\fIai\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBgai_strerror\fR(\fBint\fR \fIerrcode\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions perform translations from node name to address and from address +to node name in a protocol-independent manner. +.sp +.LP +The \fBgetaddrinfo()\fR function performs the node name to address translation. +The \fInodename\fR and \fIservname\fR arguments are pointers to null-terminated +strings or \fINULL\fR. One or both of these arguments must be a non-null +pointer. In the normal client scenario, both the \fInodename\fR and +\fIservname\fR are specified. In the normal server scenario, only the +\fIservname\fR is specified. +.sp +.LP +A non-null \fInodename\fR string can be a node name or a numeric host address +string. The \fInodename\fR can also be an IPv6 zone-id in the form: +.sp +.in +2 +.nf +<address>%<zone-id> +.fi +.in -2 + +.sp +.LP +The address is the literal IPv6 link-local address or host name of the +destination. The zone-id is the interface ID of the IPv6 link used to send the +packet. The zone-id can either be a numeric value, indicating a literal zone +value, or an interface name such as \fBhme0\fR. +.sp +.LP +A non-null \fIservname\fR string can be either a service name or a decimal port +number. +.sp +.LP +The caller can optionally pass an \fBaddrinfo\fR structure, pointed to by the +\fIhints\fR argument, to provide hints concerning the type of socket that the +caller supports. +.sp +.LP +The \fBaddrinfo\fR structure is defined as: +.sp +.in +2 +.nf +struct addrinfo { +int ai_flags; /* AI_PASSIVE, AI_CANONNAME, + AI_NUMERICHOST, AI_NUMERICSERV + AI_V4MAPPED, AI_ALL, + AI_ADDRCONFIG */ +int ai_family; /* PF_xxx */ +int ai_socktype; /* SOCK_xxx */ +int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 & IPv6 */ +socklen_t ai_addrlen; /* length of ai_addr */ +char *ai_canonname; /* canonical name for nodename */ +struct sockaddr *ai_addr; /* binary address */ +struct addrinfo *ai_next; /* next structure in linked list */ +}; +.fi +.in -2 + +.sp +.LP +In this \fIhints\fR structure, all members other than \fBai_flags\fR, +\fBai_family\fR, \fBai_socktype\fR, and \fBai_protocol\fR must be 0 or a null +pointer. A value of \fBPF_UNSPEC\fR for \fBai_family\fR indicates that the +caller will accept any protocol family. A value of 0 for \fBai_socktype\fR +indicates that the caller will accept any socket type. A value of 0 for +\fBai_protocol\fR indicates that the caller will accept any protocol. For +example, if the caller handles only TCP and not UDP, then the \fBai_socktype\fR +member of the \fIhints\fR structure should be set to \fBSOCK_STREAM\fR when +\fBgetaddrinfo()\fR is called. If the caller handles only IPv4 and not IPv6, +then the \fBai_family\fR member of the \fIhints\fR structure should be set to +\fBPF_INET\fR when \fBgetaddrinfo()\fR is called. If the third argument to +\fBgetaddrinfo()\fR is a null pointer, it is as if the caller had filled in an +\fBaddrinfo\fR structure initialized to 0 with \fBai_family\fR set to +\fBPF_UNSPEC\fR. +.sp +.LP +Upon success, a pointer to a linked list of one or more \fBaddrinfo\fR +structures is returned through the final argument. The caller can process each +\fBaddrinfo\fR structure in this list by following the \fBai_next\fR pointer, +until a null pointer is encountered. In each returned \fBaddrinfo\fR structure +the three members \fBai_family\fR, \fBai_socktype\fR, and \fBai_protocol\fR are +the corresponding arguments for a call to the \fBsocket\fR(3SOCKET) function. +In each \fBaddrinfo\fR structure the \fBai_addr\fR member points to a filled-in +socket address structure whose length is specified by the \fBai_addrlen\fR +member. +.sp +.LP +If the \fBAI_PASSIVE\fR bit is set in the \fBai_flags\fR member of the +\fIhints\fR structure, the caller plans to use the returned socket address +structure in a call to \fBbind\fR(3SOCKET). In this case, if the \fInodename\fR +argument is a null pointer, the IP address portion of the socket address +structure will be set to \fBINADDR_ANY\fR for an IPv4 address or +\fBIN6ADDR_ANY_INIT\fR for an IPv6 address. +.sp +.LP +If the \fBAI_PASSIVE\fR bit is not set in the \fBai_flags\fR member of the +\fIhints\fR structure, then the returned socket address structure will be ready +for a call to \fBconnect\fR(3SOCKET) (for a connection-oriented protocol) or +either \fBconnect\fR(3SOCKET), \fBsendto\fR(3SOCKET), or \fBsendmsg\fR(3SOCKET) +(for a connectionless protocol). If the \fInodename\fR argument is a null +pointer, the IP address portion of the socket address structure will be set to +the loopback address. +.sp +.LP +If the \fBAI_CANONNAME\fR bit is set in the \fBai_flags\fR member of the +\fIhints\fR structure, then upon successful return the \fBai_canonname\fR +member of the first \fBaddrinfo\fR structure in the linked list will point to a +null-terminated string containing the canonical name of the specified +\fInodename\fR. A numeric host address string is not a name, and thus does not +have a canonical name form; no address to host name translation is performed. +.sp +.LP +If the \fBAI_NUMERICHOST\fR bit is set in the \fBai_flags\fR member of the +\fIhints\fR structure, then a non-null \fInodename\fR string must be a numeric +host address string. Otherwise an error of \fBEAI_NONAME\fR is returned. This +flag prevents any type of name resolution service (such as DNS) from being +called. +.sp +.LP +If the \fBAI_NUMERICSERV\fR flag is specified, then a non-null servname string +supplied will be a numeric port string. Otherwise, an [\fBEAI_NONAME\fR] error +is returned. This flag prevents any type of name resolution service (for +example, NIS+) from being invoked. +.sp +.LP +If the \fBAI_V4MAPPED\fR flag is specified along with an \fBai_family\fR of +\fBAF_INET6\fR, then \fBgetaddrinfo()\fR returns IPv4-mapped IPv6 addresses on +finding no matching IPv6 addresses (\fBai_addrlen\fR shall be 16). For example, +if no AAAA records are found when using DNS, a query is made for A records. Any +found records are returned as IPv4-mapped IPv6 addresses. +.sp +.LP +The \fBAI_V4MAPPED\fR flag is ignored unless \fBai_family\fR equals +\fBAF_INET6\fR. +.sp +.LP +If the \fBAI_ALL\fR flag is used with the AI_V4MAPPED flag, then +\fBgetaddrinfo()\fR returns all matching IPv6 and IPv4 addresses. For example, +when using the DNS, queries are made for both AAAA records and A records, and +\fBgetaddrinfo()\fR returns the combined results of both queries. Any IPv4 +addresses found are returned as IPv4-mapped IPv6 addresses. +.sp +.LP +The \fBAI_ALL\fR flag without the \fBAI_V4MAPPED\fR flag is ignored. +.sp +.LP +When \fBai_family\fR is not specified (\fBAF_UNSPEC\fR), \fBAI_V4MAPPED\fR and +\fBAI_ALL\fR flags are used only if \fBAF_INET6\fR is supported. +.sp +.LP +If the \fBAI_ADDRCONFIG\fR flag is specified, IPv4 addresses are returned only +if an IPv4 address is configured on the local system, and IPv6 addresses are +returned only if an IPv6 address is configured on the local system. For this +case, the loopback address is not considered to be as valid as a configured +address. For example, when using the DNS, a query for AAAA records should occur +only if the node has at least one IPv6 address configured (other than IPv6 +loopback) and a query for A records should occur only if the node has at least +one IPv4 address configured (other than the IPv4 loopback). +.sp +.LP +All of the information returned by \fBgetaddrinfo()\fR is dynamically +allocated: the \fBaddrinfo\fR structures as well as the socket address +structures and canonical node name strings pointed to by the \fBaddrinfo\fR +structures. The \fBfreeaddrinfo()\fR function is called to return this +information to the system. For \fBfreeaddrinfo()\fR, the \fBaddrinfo\fR +structure pointed to by the \fIai\fR argument is freed, along with any dynamic +storage pointed to by the structure. This operation is repeated until a null +\fBai_next\fR pointer is encountered. +.sp +.LP +To aid applications in printing error messages based on the \fBEAI_\fR* codes +returned by \fBgetaddrinfo()\fR, the \fBgai_strerror()\fR is defined. The +argument is one of the \fBEAI_\fR* values defined below and the return value +points to a string describing the error. If the argument is not one of the +\fBEAI_\fR* values, the function still returns a pointer to a string whose +contents indicate an unknown error. +.sp +.LP +The \fBgetnameinfo()\fR function looks up an IP address and port number +provided by the caller in the name service database and system-specific +database, and returns text strings for both in buffers provided by the caller. +The function indicates successful completion by a 0 return value; a non-zero +return value indicates failure. +.sp +.LP +The first argument, \fIsa\fR, points to either a \fBsockaddr_in\fR structure +(for IPv4) or a \fBsockaddr_in6\fR structure (for IPv6) that holds the IP +address and port number. The \fIsalen\fR argument gives the length of the +\fBsockaddr_in\fR or \fBsockaddr_in6\fR structure. +.sp +.LP +The function returns the node name associated with the IP address in the buffer +pointed to by the \fIhost\fR argument. +.sp +.LP +The function can also return the IPv6 zone-id in the form: +.sp +.in +2 +.nf +<address>%<zone-id> +.fi +.in -2 + +.sp +.LP +The caller provides the size of this buffer with the \fIhostlen\fR argument. +The service name associated with the port number is returned in the buffer +pointed to by \fIserv\fR, and the \fIservlen\fR argument gives the length of +this buffer. The caller specifies not to return either string by providing a 0 +value for the \fIhostlen\fR or \fIservlen\fR arguments. Otherwise, the caller +must provide buffers large enough to hold the node name and the service name, +including the terminating null characters. +.sp +.LP +To aid the application in allocating buffers for these two returned strings, +the following constants are defined in <\fBnetdb.h\fR>: +.sp +.in +2 +.nf +#define NI_MAXHOST 1025 +#define NI_MAXSERV 32 +.fi +.in -2 + +.sp +.LP +The final argument is a flag that changes the default actions of this function. +By default, the fully-qualified domain name (\fBFQDN\fR) for the host is looked +up in the name service database and returned. If the flag bit \fBNI_NOFQDN\fR +is set, only the node name portion of the \fBFQDN\fR is returned for local +hosts. +.sp +.LP +If the flag bit \fBNI_NUMERICHOST\fR is set, or if the host's name cannot be +located in the name service, the numeric form of the host's address is returned +instead of its name, for example, by calling \fBinet_ntop()\fR (see +\fBinet\fR(3SOCKET)) instead of \fBgetipnodebyname\fR(3SOCKET). If the flag bit +\fBNI_NAMEREQD\fR is set, an error is returned if the host's name cannot be +located in the name service database. +.sp +.LP +If the flag bit \fBNI_NUMERICSERV\fR is set, the numeric form of the service +address is returned (for example, its port number) instead of its name. The two +\fBNI_NUMERIC\fR* flags are required to support the \fB-n\fR flag that many +commands provide. +.sp +.LP +A fifth flag bit, \fBNI_DGRAM\fR, specifies that the service is a datagram +service, and causes \fBgetservbyport\fR(3SOCKET) to be called with a second +argument of \fBudp\fR instead of the default \fBtcp\fR. This is required for +the few ports (for example, 512-514) that have different services for UDP and +TCP. +.sp +.LP +These \fBNI_\fR* flags are defined in <\fBnetdb.h\fR> along with the \fBAI_\fR* +flags already defined for \fBgetaddrinfo()\fR. +.SH RETURN VALUES +.sp +.LP +For \fBgetaddrinfo()\fR, if the query is successful, a pointer to a linked list +of one or more \fBaddrinfo\fR structures is returned by the fourth argument and +the function returns \fB0\fR. The order of the addresses returned i nthe fourth +argument is discussed in the ADDRESS ORDERING section. If the query fails, a +non-zero error code will be returned. For \fBgetnameinfo()\fR, if successful, +the strings hostname and service are copied into \fIhost\fR and \fIserv\fR, +respectively. If unsuccessful, zero values for either \fIhostlen\fR or +\fIservlen\fR will suppress the associated lookup; in this case no data is +copied into the applicable buffer. If \fBgai_strerror()\fR is successful, a +pointer to a string containing an error message appropriate for the \fBEAI_\fR* +errors is returned. If \fIerrcode\fR is not one of the \fBEAI_\fR* values, a +pointer to a string indicating an unknown error is returned. +.SS "Address Ordering" +.sp +.LP +AF_INET6 addresses returned by the fourth argument of \fBgetaddrinfo()\fR are +ordered according to the algorithm described in \fIRFC 3484, Default Address +Selection for Internet Protocol version 6 (IPv6)\fR. The addresses are ordered +using a list of pair-wise comparison rules which are applied in order. If a +rule determines that one address is better than another, the remaining rules +are irrelevant to the comparison of those two addresses. If two addresses are +equivalent according to one rule, the remaining rules act as a tie-breaker. The +address ordering list of pair-wise comparison rules follow below: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +Avoid unusable destinations.T{ +Prefer a destination that is reachable through the IP routing table. +T} +_ +Prefer matching scope.T{ +Prefer a destination whose scope is equal to the scope of its source address. See \fBinet6\fR(7P) for the definition of scope used by this rule. +T} +_ +Avoid link-local source.T{ +Avoid selecting a link-local source address when the destination address is not a link-local address. +T} +_ +Avoid deprecated addresses.T{ +Prefer a destination that is not deprecated (\fBIFF_DEPRECATED\fR). +T} +_ +T{ +Prefer matching label. This rule uses labels that are obtained through the IPv6 default address selection policy table. See \fBipaddrsel\fR(1M) for a description of the default contents of the table and how the table is configured. +T}T{ +Prefer a destination whose label is equal to the label of its source address. +T} +_ +T{ +Prefer higher precedence. This rule uses precedence values that are obtained through the IPv6 default address selection policy table. See \fBipaddrsel\fR(1M) for a description of the default contents of the table and how the table is configured. +T}T{ +Prefer the destination whose precedence is higher than the other destination. +T} +_ +Prefer native transport.T{ +Prefer a destination if the interface that is used for sending packets to that destination is not an IP over IP tunnel. +T} +_ +T{ +Prefer smaller scope. See \fBinet6\fR(7P) for the definition of this rule. +T}T{ +Prefer the destination whose scope is smaller than the other destination. +T} +_ +Use longest matching prefix.T{ +When the two destinations belong to the same address family, prefer the destination that has the longer matching prefix with its source address. +T} +.TE + +.SH ERRORS +.sp +.LP +The following names are the error values returned by \fBgetaddrinfo()\fR and +are defined in <\fBnetdb.h\fR>: +.sp +.ne 2 +.mk +.na +\fB\fBEAI_ADDRFAMILY\fR\fR +.ad +.RS 18n +.rt +Address family for nodename is not supported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_AGAIN\fR\fR +.ad +.RS 18n +.rt +Temporary failure in name resolution has occurred . +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_BADFLAGS\fR\fR +.ad +.RS 18n +.rt +Invalid value specified for \fBai_flags\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_FAIL\fR\fR +.ad +.RS 18n +.rt +Non-recoverable failure in name resolution has occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_FAMILY\fR\fR +.ad +.RS 18n +.rt +The \fBai_family\fR is not supported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_MEMORY\fR\fR +.ad +.RS 18n +.rt +Memory allocation failure has occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_NODATA\fR\fR +.ad +.RS 18n +.rt +No address is associated with \fInodename\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_NONAME\fR\fR +.ad +.RS 18n +.rt +Neither \fInodename\fR nor \fIservname\fR is provided or known. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_SERVICE\fR\fR +.ad +.RS 18n +.rt +The \fIservname\fR is not supported for \fBai_socktype\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_SOCKTYPE\fR\fR +.ad +.RS 18n +.rt +The \fBai_socktype\fR is not supported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_OVERFLOW\fR\fR +.ad +.RS 18n +.rt +Argument buffer has overflowed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_SYSTEM\fR\fR +.ad +.RS 18n +.rt +System error was returned in \fIerrno\fR. +.RE + +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/inet/hosts\fR\fR +.ad +.RS 22n +.rt +local database that associates names of nodes with IP addresses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/netconfig\fR\fR +.ad +.RS 22n +.rt +network configuration database +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/nsswitch.conf\fR\fR +.ad +.RS 22n +.rt +configuration file for the name service switch +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee \fBstandards\fR(5). +.TE + +.SH SEE ALSO +.sp +.LP +\fBipaddrsel\fR(1M), \fBgethostbyname\fR(3NSL), \fBgetipnodebyname\fR(3SOCKET), +\fBhtonl\fR(3SOCKET), \fBinet\fR(3SOCKET), \fBnetdb.h\fR(3HEAD), +\fBsocket\fR(3SOCKET), \fBhosts\fR(4), \fBnsswitch.conf\fR(4), +\fBattributes\fR(5), \fBstandards\fR(5), \fBinet6\fR(7P) +.sp +.LP +Draves, R. \fIRFC 3484, Default Address Selection for Internet Protocol version +6 (IPv6)\fR. Network Working Group. February 2003. +.SH NOTES +.sp +.LP +IPv4-mapped addresses are not recommended. diff --git a/usr/src/man/man3socket/getipnodebyname.3socket b/usr/src/man/man3socket/getipnodebyname.3socket new file mode 100644 index 0000000000..446d4580c6 --- /dev/null +++ b/usr/src/man/man3socket/getipnodebyname.3socket @@ -0,0 +1,582 @@ +'\" te +.\" 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 getipnodebyname 3SOCKET "22 Aug 2007" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +getipnodebyname, getipnodebyaddr, freehostent \- get IP node entry +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR... ] +#include <sys/socket.h> +#include <netdb.h> + +\fBstruct hostent *\fR\fBgetipnodebyname\fR(\fBconst char *\fR\fIname\fR, \fBint\fR \fIaf\fR, + \fBint\fR \fIflags\fR, \fBint *\fR\fIerror_num\fR); +.fi + +.LP +.nf +\fBstruct hostent *\fR\fBgetipnodebyaddr\fR(\fBconst void *\fR\fIsrc\fR, \fBsize_t\fR \fIlen\fR, + \fBint\fR \fIaf\fR, \fBint *\fR\fIerror_num\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBfreehostent\fR(\fBstruct hostent *\fR\fIptr\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIaf\fR\fR +.ad +.RS 13n +.rt +Address family +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 13n +.rt +Various flags +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 13n +.rt +Name of host +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerror_num\fR\fR +.ad +.RS 13n +.rt +Error storage +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsrc\fR\fR +.ad +.RS 13n +.rt +Address for lookup +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 13n +.rt +Length of address +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIptr\fR\fR +.ad +.RS 13n +.rt +Pointer to \fBhostent\fR structure +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBgetipnodebyname()\fR function searches the \fBipnodes\fR database from +the beginning. The function finds the first \fBh_name\fR member that matches +the hostname specified by \fIname\fR. The function takes an \fIaf\fR argument +that specifies the address family. The address family can be \fBAF_INET\fR for +IPv4 addresses or \fBAF_INET6\fR for IPv6 addresses. The \fIflags\fR argument +determines what results are returned based on the value of \fIflags\fR. If the +\fIflags\fR argument is set to \fB0\fR (zero), the default operation of the +function is specified as follows: +.RS +4 +.TP +.ie t \(bu +.el o +If the \fIaf\fR argument is \fBAF_INET\fR, a query is made for an IPv4 address. +If successful, IPv4 addresses are returned and the \fBh_length\fR member of the +\fBhostent\fR structure is 4. Otherwise, the function returns a \fINULL\fR +pointer. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the \fIaf\fR argument is \fBAF_INET6\fR, a query is made for an IPv6 +address. If successful, IPv6 addresses are returned and the \fBh_length\fR +member of the \fBhostent\fR structure is 16. Otherwise, the function returns a +\fINULL\fR pointer. +.RE +.sp +.LP +The \fIflags\fR argument changes the default actions of the function. Set the +\fIflags\fR argument with a logical \fBOR\fR operation on any of combination of +the following values: +.RS +4 +.TP +.ie t \(bu +.el o +\fBAI_V4MAPPED\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBAI_ALL\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBAI_ADDRCONFIG\fR +.RE +.sp +.LP +The special flags value, \fBAI_DEFAULT\fR, should handle most applications. +Porting simple applications to use IPv6 replaces the call +.sp +.in +2 +.nf +hptr = gethostbyname(name); +.fi +.in -2 + +.sp +.LP +with +.sp +.in +2 +.nf +hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num); +.fi +.in -2 + +.sp +.LP +The \fIflags\fR value \fB0\fR (zero) implies a strict interpretation of the +\fIaf\fR argument: +.RS +4 +.TP +.ie t \(bu +.el o +If \fIflags\fR is \fB0\fR and \fIaf\fR is \fBAF_INET\fR, the caller wants only +IPv4 addresses. A query is made for \fBA\fR records. If successful, IPv4 +addresses are returned and the \fBh_length\fR member of the \fBhostent\fR +structure is 4. Otherwise, the function returns a \fINULL\fR pointer. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If \fIflags\fR is \fB0\fR and \fIaf\fR is \fBAF_INET6\fR, the caller wants only +IPv6 addresses. A query is made for \fBAAAA\fR records. If successful, IPv6 +addresses are returned and the \fBh_length\fR member of the \fBhostent\fR +structure is 16. Otherwise, the function returns a \fINULL\fR pointer. +.RE +.sp +.LP +Logically \fBOR\fR other constants into the \fIflags\fR argument to modify the +behavior of the \fBgetipnodebyname()\fR function. +.RS +4 +.TP +.ie t \(bu +.el o +If the \fBAI_V4MAPPED\fR flag is specified with \fIaf\fR set to \fBAF_INET6\fR, +the caller can accept IPv4-mapped IPv6 addresses. If no \fBAAAA\fR records are +found, a query is made for \fBA\fR records. Any \fBA\fR records found are +returned as IPv4-mapped IPv6 addresses and the \fBh_length\fR is 16. The +\fBAI_V4MAPPED\fR flag is ignored unless \fIaf\fR equals \fBAF_INET6\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The \fBAI_ALL\fR flag is used in conjunction with the \fBAI_V4MAPPED\fR flag, +exclusively with the IPv6 address family. When \fBAI_ALL\fR is logically +\fBOR\fRed with \fBAI_V4MAPPED\fR flag, the caller wants all addresses: IPv6 +and IPv4-mapped IPv6 addresses. A query is first made for \fBAAAA\fR records +and, if successful, IPv6 addresses are returned. Another query is then made for +\fBA\fR records. Any \fBA\fR records found are returned as IPv4-mapped IPv6 +addresses and the \fBh_length\fR is 16. Only when both queries fail does the +function return a \fINULL\fR pointer. The \fBAI_ALL\fR flag is ignored unless +\fIaf\fR is set to \fBAF_INET6\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The \fBAI_ADDRCONFIG\fR flag specifies that a query for \fBAAAA\fR records +should occur only when the node is configured with at least one IPv6 source +address. A query for \fBA\fR records should occur only when the node is +configured with at least one IPv4 source address. For example, if a node is +configured with no IPv6 source addresses, \fIaf\fR equals \fBAF_INET6\fR, and +the node name queried has both \fBAAAA\fR and \fBA\fR records, then: +.RS +4 +.TP +.ie t \(bu +.el o +A \fINULL\fR pointer is returned when only the \fBAI_ADDRCONFIG\fR value is +specified. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The \fBA\fR records are returned as IPv4-mapped IPv6 addresses when the +\fBAI_ADDRCONFIG\fR and \fBAI_V4MAPPED\fR values are specified. +.RE +.RE +.sp +.LP +The special flags value, \fBAI_DEFAULT\fR, is defined as +.sp +.in +2 +.nf +#define AI_DEFAULT (AI_V4MAPPED | AI_ADDRCONFIG) +.fi +.in -2 + +.sp +.LP +The \fBgetipnodebyname()\fR function allows the \fIname\fR argument to be a +node name or a literal address string: a dotted-decimal IPv4 address or an IPv6 +hex address. Applications do not have to call \fBinet_pton\fR(3SOCKET) to +handle literal address strings. +.sp +.LP +Four scenarios arise based on the type of literal address string and the value +of the \fIaf\fR argument. The two simple cases occur when \fIname\fR is a +dotted-decimal IPv4 address and \fIaf\fR equals \fBAF_INET\fR and when +\fIname\fR is an IPv6 hex address and \fIaf\fR equals \fBAF_INET6\fR. The +members of the returned \fBhostent\fR structure are: +.sp +.ne 2 +.mk +.na +\fB\fBh_name\fR\fR +.ad +.RS 15n +.rt +Pointer to a copy of the name argument +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBh_aliases\fR\fR +.ad +.RS 15n +.rt +\fINULL\fR pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBh_addrtype\fR\fR +.ad +.RS 15n +.rt +Copy of the \fIaf\fR argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBh_length\fR\fR +.ad +.RS 15n +.rt +4 for \fBAF_INET\fR or 16 for \fBAF_INET6\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBh_addr_list\fR\fR +.ad +.RS 15n +.rt +Array of pointers to 4-byte or 16-byte binary addresses. The array is +terminated by a \fINULL\fR pointer. +.RE + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBgetipnodebyname()\fR and \fBgetipnodebyaddr()\fR +return a \fBhostent\fR structure. Otherwise they return \fINULL\fR. +.sp +.LP +The \fBhostent\fR structure does not change from the existing definition when +used with \fBgethostbyname\fR(3NSL). For example, host entries are represented +by the \fBstruct hostent\fR structure defined in <\fBnetdb.h\fR>: +.sp +.in +2 +.nf +struct hostent { + char *h_name; /* canonical name of host */ + char **h_aliases; /* alias list */ + int h_addrtype; /* host address type */ + int h_length; /* length of address */ + char **h_addr_list; /* list of addresses */ +}; +.fi +.in -2 + +.sp +.LP +An error occurs when \fIname\fR is an IPv6 hex address and \fIaf\fR equals +\fBAF_INET\fR. The return value of the function is a \fINULL\fR pointer and +\fBerror_num\fR equals \fBHOST_NOT_FOUND\fR. +.sp +.LP +The \fBgetipnodebyaddr()\fR function has the same arguments as the existing +\fBgethostbyaddr\fR(3NSL) function, but adds an error number. As with +\fBgetipnodebyname()\fR, \fBgetipnodebyaddr()\fR is thread-safe. The +\fBerror_num\fR value is returned to the caller with the appropriate error code +to support thread-safe error code returns. The following error conditions can +be returned for \fBerror_num\fR: +.sp +.ne 2 +.mk +.na +\fB\fBHOST_NOT_FOUND\fR\fR +.ad +.RS 18n +.rt +Host is unknown. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNO_DATA\fR\fR +.ad +.RS 18n +.rt +No address is available for the \fIname\fR specified in the server request. +This error is not a soft error. Another type of \fIname\fR server request might +be successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNO_RECOVERY\fR\fR +.ad +.RS 18n +.rt +An unexpected server failure occurred, which is a non-recoverable error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTRY_AGAIN\fR\fR +.ad +.RS 18n +.rt +This error is a soft error that indicates that the local server did not receive +a response from an authoritative server. A retry at some later time might be +successful. +.RE + +.sp +.LP +One possible source of confusion is the handling of IPv4-mapped IPv6 addresses +and IPv4-compatible IPv6 addresses, but the following logic should apply: +.RS +4 +.TP +1. +If \fIaf\fR is \fBAF_INET6\fR, and if \fIlen\fR equals 16, and if the IPv6 +address is an IPv4-mapped IPv6 address or an IPv4-compatible IPv6 address, then +skip over the first 12 bytes of the IPv6 address, set \fIaf\fR to +\fBAF_INET\fR, and set \fIlen\fR to 4. +.RE +.RS +4 +.TP +2. +If \fIaf\fR is \fBAF_INET\fR, lookup the \fIname\fR for the given IPv4 +address. +.RE +.RS +4 +.TP +3. +If \fIaf\fR is \fBAF_INET6\fR, lookup the \fIname\fR for the given IPv6 +address. +.RE +.RS +4 +.TP +4. +If the function is returning success, then the single address that is +returned in the \fBhostent\fR structure is a copy of the first argument to the +function with the same address family that was passed as an argument to this +function. +.RE +.sp +.LP +All four steps listed are performed in order. +.sp +.LP +This structure, and the information pointed to by this structure, are +dynamically allocated by \fBgetipnodebyname()\fR and \fBgetipnodebyaddr()\fR. +The \fBfreehostent()\fR function frees this memory. +.SH EXAMPLES +.LP +\fBExample 1 \fRGetting the Canonical Name, Aliases, and Internet IP Addresses +for a Given Hostname +.sp +.LP +The following is a sample program that retrieves the canonical name, aliases, +and all Internet IP addresses, both version 6 and version 4, for a given +hostname. + +.sp +.in +2 +.nf + #include <stdio.h> + #include <string.h> + #include <sys/types.h> + #include <sys/socket.h> + #include <netinet/in.h> + #include <arpa/inet.h> + #include <netdb.h> + + main(int argc, const char **argv) + { + char abuf[INET6_ADDRSTRLEN]; + int error_num; + struct hostent *hp; + char **p; + + if (argc != 2) { + (void) printf("usage: %s hostname\n", argv[0]); + exit (1); + } + + /* argv[1] can be a pointer to a hostname or literal IP address */ + hp = getipnodebyname(argv[1], AF_INET6, AI_ALL | AI_ADDRCONFIG | + AI_V4MAPPED, &error_num); + if (hp == NULL) { + if (error_num == TRY_AGAIN) { + printf("%s: unknown host or invalid literal address " + "(try again later)\n", argv[1]); + } else { + printf("%s: unknown host or invalid literal address\n", + argv[1]); + } + exit (1); + } + for (p = hp->h_addr_list; *p != 0; p++) { + struct in6_addr in6; + char **q; + + bcopy(*p, (caddr_t)&in6, hp->h_length); + (void) printf("%s\t%s", inet_ntop(AF_INET6, (void *)&in6, + abuf, sizeof(abuf)), hp->h_name); + for (q = hp->h_aliases; *q != 0; q++) + (void) printf(" %s", *q); + (void) putchar('\n'); + } + freehostent(hp); + exit (0); + } +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetaddrinfo\fR(3SOCKET), \fBgethostbyname\fR(3NSL), \fBhtonl\fR(3SOCKET), +\fBinet\fR(3SOCKET), \fBnetdb.h\fR(3HEAD), \fBhosts\fR(4), +\fBnsswitch.conf\fR(4), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +No enumeration functions are provided for IPv6. Existing enumeration functions +such as \fBsethostent\fR(3NSL) do not work in combination with the +\fBgetipnodebyname()\fR and \fBgetipnodebyaddr()\fR functions. +.sp +.LP +All the functions that return a \fBstruct hostent\fR must always return the +canonical in the \fBh_name\fR field. This name, by definition, is the +well-known and official hostname shared between all aliases and all addresses. +The underlying source that satisfies the request determines the mapping of the +input name or address into the set of names and addresses in \fBhostent\fR. +Different sources might make such as determination in different ways. If more +than one alias and more than one address in \fBhostent\fR exist, no pairing is +implied between the alias and address. +.sp +.LP +The current implementations of these functions return or accept only addresses +for the Internet address family (type \fBAF_INET\fR) or the Internet address +family Version 6 (type \fBAF_INET6\fR). +.sp +.LP +IPv4-mapped addresses are not recommended. The \fBgetaddrinfo\fR(3SOCKET) +function is preferred over \fBgetipnodebyaddr()\fR because it allows +applications to lookup IPv4 and IPv6 addresses without relying on IPv4-mapped +addresses. +.sp +.LP +The form for an address of type \fBAF_INET\fR is a \fBstruct in_addr\fR defined +in <\fBnetinet/in.h\fR>. The form for an address of type \fBAF_INET6\fR is a +\fBstruct in6_addr\fR, also defined in <\fBnetinet/in.h\fR>. The functions +described in \fBinet_ntop\fR(3SOCKET) and \fBinet_pton\fR(3SOCKET) that are +illustrated in the EXAMPLES section are helpful in constructing and +manipulating addresses in either of these forms. diff --git a/usr/src/man/man3socket/getnetbyname.3socket b/usr/src/man/man3socket/getnetbyname.3socket new file mode 100644 index 0000000000..f456d9f848 --- /dev/null +++ b/usr/src/man/man3socket/getnetbyname.3socket @@ -0,0 +1,298 @@ +'\" te +.\" Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.TH getnetbyname 3SOCKET "4 Nov 2004" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +getnetbyname, getnetbyname_r, getnetbyaddr, getnetbyaddr_r, getnetent, +getnetent_r, setnetent, endnetent \- get network entry +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ] +#include <netdb.h> + +\fBstruct netent *\fR\fBgetnetbyname\fR(\fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBstruct netent *\fR\fBgetnetbyname_r\fR(\fBconst char *\fR\fIname\fR, \fBstruct netent *\fR\fIresult\fR, + \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBstruct netent *\fR\fBgetnetbyaddr\fR(\fBlong\fR \fInet\fR, \fBint\fR \fItype\fR); +.fi + +.LP +.nf +\fBstruct netent *\fR\fBgetnetbyaddr_r\fR(\fBlong\fR \fInet\fR, \fBint\fR \fItype\fR, \fBstruct netent *\fR\fIresult\fR, + \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBstruct netent *\fR\fBgetnetent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBstruct netent *\fR\fBgetnetent_r\fR(\fBstruct netent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, + \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBint\fR \fBsetnetent\fR(\fBint\fR \fIstayopen\fR); +.fi + +.LP +.nf +\fBint\fR \fBendnetent\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are used to obtain entries for networks. An entry may come from +any of the sources for \fBnetworks\fR specified in the \fB/etc/nsswitch.conf\fR +file. See \fBnsswitch.conf\fR(4). +.sp +.LP +\fBgetnetbyname()\fR searches for a network entry with the network name +specified by the character string parameter \fIname\fR. +.sp +.LP +\fBgetnetbyaddr()\fR searches for a network entry with the network address +specified by \fInet\fR. The parameter \fBtype\fR specifies the family of the +address. This should be one of the address families defined in +<\fBsys/socket.h\fR>. See the \fBNOTES\fR section below for more information. +.sp +.LP +Network numbers and local address parts are returned as machine format integer +values, that is, in host byte order. See also \fBinet\fR(3SOCKET). +.sp +.LP +The \fBnetent.n_net\fR member in the \fBnetent\fR structure pointed to by the +return value of the above functions is calculated by \fBinet_network()\fR. The +\fBinet_network()\fR function returns a value in host byte order that is +aligned based upon the input string. For example: +.sp + +.sp +.TS +tab(); +cw(2.75i) cw(2.75i) +lw(2.75i) lw(2.75i) +. +TextValue +\fB"10"\fR\fB0x0000000a\fR +\fB"10.0"\fR\fB0x00000a00\fR +\fB"10.0.1"\fR\fB0a000a0001\fR +\fB"10.0.1.28\fR"\fB0x0a000180\fR +.TE + +.sp +.LP +Commonly, the alignment of the returned value is used as a crude approximate of +pre-CIDR (Classless Inter-Domain Routing) subnet mask. For example: +.sp +.in +2 +.nf +in_addr_t addr, mask; + +addr = inet_network(net_name); +mask= ~(in_addr_t)0; +if ((addr & IN_CLASSA_NET) == 0) + addr <<= 8, mask <<= 8; +if ((addr & IN_CLASSA_NET) == 0) + addr <<= 8, mask <<= 8; +if ((addr & IN_CLASSA_NET) == 0) + addr <<= 8, mask <<= 8; +.fi +.in -2 + +.sp +.LP +This usage is deprecated by the CIDR requirements. See Fuller, V., Li, T., Yu, +J., and Varadhan, K. \fIRFC 1519, Classless Inter-Domain Routing (CIDR): an +Address Assignment and Aggregation Strategy\fR. Network Working Group. +September 1993. +.sp +.LP +The functions \fBsetnetent()\fR, \fBgetnetent()\fR, and \fBendnetent()\fR are +used to enumerate network entries from the database. +.sp +.LP +\fBsetnetent()\fR sets (or resets) the enumeration to the beginning of the set +of network entries. This function should be called before the first call to +\fBgetnetent()\fR. Calls to \fBgetnetbyname()\fR and \fBgetnetbyaddr()\fR leave +the enumeration position in an indeterminate state. If the \fIstayopen\fR flag +is non-zero, the system may keep allocated resources such as open file +descriptors until a subsequent call to \fBendnetent()\fR. +.sp +.LP +Successive calls to \fBgetnetent()\fR return either successive entries or +\fBNULL\fR, indicating the end of the enumeration. +.sp +.LP +\fBendnetent()\fR may be called to indicate that the caller expects to do no +further network entry retrieval operations; the system may then deallocate +resources it was using. It is still allowed, but possibly less efficient, for +the process to call more network entry retrieval functions after calling +\fBendnetent()\fR. +.SS "Reentrant Interfaces" +.sp +.LP +The functions \fBgetnetbyname()\fR, \fBgetnetbyaddr()\fR, and \fBgetnetent()\fR +use static storage that is reused in each call, making these routines unsafe +for use in multi-threaded applications. +.sp +.LP +The functions \fBgetnetbyname_r()\fR, \fBgetnetbyaddr_r()\fR, and +\fBgetnetent_r()\fR provide reentrant interfaces for these operations. +.sp +.LP +Each reentrant interface performs the same operation as its non-reentrant +counterpart, named by removing the ``\fB_r\fR'' suffix. The reentrant +interfaces, however, use buffers supplied by the caller to store returned +results, and are safe for use in both single-threaded and multi-threaded +applications. +.sp +.LP +Each reentrant interface takes the same parameters as its non-reentrant +counterpart, as well as the following additional parameters. The parameter +\fIresult\fR must be a pointer to a \fBstruct netent\fR structure allocated by +the caller. On successful completion, the function returns the network entry in +this structure. The parameter \fIbuffer\fR must be a pointer to a buffer +supplied by the caller. This buffer is used as storage space for the network +entry data. All of the pointers within the returned \fBstruct netent\fR +\fIresult\fR point to data stored within this buffer. See \fBRETURN VALUES\fR. +The buffer must be large enough to hold all of the data associated with the +network entry. The parameter \fIbuflen\fR should give the size in bytes of the +buffer indicated by \fIbuffer\fR. +.sp +.LP +For enumeration in multi-threaded applications, the position within the +enumeration is a process-wide property shared by all threads. \fBsetnetent()\fR +may be used in a multi-threaded application but resets the enumeration position +for all threads. If multiple threads interleave calls to \fBgetnetent_r()\fR, +the threads will enumerate disjointed subsets of the network database. +.sp +.LP +Like their non-reentrant counterparts, \fBgetnetbyname_r()\fR and +\fBgetnetbyaddr_r()\fR leave the enumeration position in an indeterminate +state. +.SH RETURN VALUES +.sp +.LP +Network entries are represented by the \fBstruct netent\fR structure defined in +\fB<netdb.h>\fR\&. +.sp +.LP +The functions \fBgetnetbyname()\fR, \fBgetnetbyname_r\fR, \fBgetnetbyaddr\fR, +and \fBgetnetbyaddr_r()\fR each return a pointer to a \fBstruct netent\fR if +they successfully locate the requested entry; otherwise they return \fBNULL\fR. +.sp +.LP +The functions \fBgetnetent()\fR and \fBgetnetent_r()\fR each return a pointer +to a \fBstruct netent\fR if they successfully enumerate an entry; otherwise +they return \fBNULL\fR, indicating the end of the enumeration. +.sp +.LP +The functions \fBgetnetbyname()\fR, \fBgetnetbyaddr()\fR, and \fBgetnetent()\fR +use static storage, so returned data must be copied before a subsequent call to +any of these functions if the data is to be saved. +.sp +.LP +When the pointer returned by the reentrant functions \fBgetnetbyname_r()\fR, +\fBgetnetbyaddr_r()\fR, and \fBgetnetent_r()\fR is non-\fBNULL\fR, it is always +equal to the \fIresult\fR pointer that was supplied by the caller. +.sp +.LP +The functions \fBsetnetent()\fR and \fBendnetent()\fR return \fB0\fR on +success. +.SH ERRORS +.sp +.LP +The reentrant functions \fBgetnetbyname_r()\fR, \fBgetnetbyaddr_r\fR and +\fBgetnetent_r()\fR will return \fBNULL\fR and set \fIerrno\fR to \fBERANGE\fR +if the length of the buffer supplied by caller is not large enough to store the +result. See \fBIntro\fR(2) for the proper usage and interpretation of +\fIerrno\fR in multi-threaded applications. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/networks\fR\fR +.ad +.RS 22n +.rt +network name database +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/nsswitch.conf\fR\fR +.ad +.RS 22n +.rt +configuration file for the name service switch +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(2), \fBIntro\fR(3), \fBbyteorder\fR(3SOCKET), \fBinet\fR(3SOCKET), +\fBnetdb.h\fR(3HEAD), \fBnetworks\fR(4), \fBnsswitch.conf\fR(4), +\fBattributes\fR(5) +.sp +.LP +Fuller, V., Li, T., Yu, J., and Varadhan, K. \fIRFC 1519, Classless +Inter-Domain Routing (CIDR): an Address Assignment and Aggregation Strategy\fR. +Network Working Group. September 1993. +.SH WARNINGS +.sp +.LP +The reentrant interfaces \fBgetnetbyname_r()\fR, \fBgetnetbyaddr_r()\fR, and +\fBgetnetent_r()\fR are included in this release on an uncommitted basis only, +and are subject to change or removal in future minor releases. +.SH NOTES +.sp +.LP +The current implementation of these functions only return or accept network +numbers for the Internet address family (type \fBAF_INET\fR). The functions +described in \fBinet\fR(3SOCKET) may be helpful in constructing and +manipulating addresses and network numbers in this form. +.sp +.LP +When compiling multi-threaded applications, see \fBIntro\fR(3), \fINotes On +Multithread Applications\fR, for information about the use of the +\fB_REENTRANT\fR flag. +.sp +.LP +Use of the enumeration interfaces \fBgetnetent()\fR and \fBgetnetent_r()\fR is +discouraged; enumeration may not be supported for all database sources. The +semantics of enumeration are discussed further in \fBnsswitch.conf\fR(4). diff --git a/usr/src/man/man3socket/getpeername.3socket b/usr/src/man/man3socket/getpeername.3socket new file mode 100644 index 0000000000..6879fa1dcc --- /dev/null +++ b/usr/src/man/man3socket/getpeername.3socket @@ -0,0 +1,113 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1998, 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 getpeername 3SOCKET "26 Mar 1998" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +getpeername \- get name of connected peer +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ] +#include <sys/types.h> +#include <sys/socket.h> + +\fBint\fR \fBgetpeername\fR(\fBint\fR \fIs\fR, \fBstruct sockaddr *\fR\fIname\fR, \fBsocklen_t *\fR\fInamelen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBgetpeername()\fR returns the name of the peer connected to socket \fIs\fR. +The \fBint\fR pointed to by the \fInamelen\fR parameter should be initialized +to indicate the amount of space pointed to by \fIname\fR. On return it contains +the actual size of the name returned (in bytes), prior to any truncation. The +name is truncated if the buffer provided is too small. +.SH RETURN VALUES +.sp +.LP +If successful, \fBgetpeername()\fR returns \fB0\fR; otherwise it returns +\fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The call succeeds unless: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 12n +.rt +The argument \fIs\fR is not a valid descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 12n +.rt +There was insufficient user memory for the operation to complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 12n +.rt +There were insufficient STREAMS resources available for the operation to +complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTCONN\fR\fR +.ad +.RS 12n +.rt +The socket is not connected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 12n +.rt +The argument \fIs\fR is not a socket. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBaccept\fR(3SOCKET), \fBbind\fR(3SOCKET), \fBgetsockname\fR(3SOCKET), +\fBsocket\fR(3SOCKET), \fBattributes\fR(5), \fBsocket.h\fR(3HEAD) diff --git a/usr/src/man/man3socket/getprotobyname.3socket b/usr/src/man/man3socket/getprotobyname.3socket new file mode 100644 index 0000000000..bfaac47db5 --- /dev/null +++ b/usr/src/man/man3socket/getprotobyname.3socket @@ -0,0 +1,235 @@ +'\" te +.\" Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. Copyright 1989 AT&T Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved. +.TH getprotobyname 3SOCKET "5 Apr 2004" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +getprotobyname, getprotobyname_r, getprotobynumber, getprotobynumber_r, +getprotoent, getprotoent_r, setprotoent, endprotoent \- get protocol entry +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ] +#include <netdb.h> + +\fBstruct protoent *\fR\fBgetprotobyname\fR(\fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBstruct protoent *\fR\fBgetprotobyname_r\fR(\fBconst char *\fR\fIname\fR, + \fBstruct protoent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, + \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBstruct protoent *\fR\fBgetprotobynumber\fR(\fBint\fR \fIproto\fR); +.fi + +.LP +.nf +\fBstruct protoent *\fR\fBgetprotobynumber_r\fR(\fBint\fR \fIproto\fR, \fBstruct protoent *\fR\fIresult\fR, + \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBstruct protoent *\fR\fBgetprotoent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBstruct protoent *\fR\fBgetprotoent_r\fR(\fBstruct protoent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, + \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBint\fR \fBsetprotoent\fR(\fBint\fR \fIstayopen\fR); +.fi + +.LP +.nf +\fBint\fR \fBendprotoent\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions return a protocol entry. Two types of interfaces are supported: +reentrant (\fBgetprotobyname_r()\fR, \fBgetprotobynumber_r()\fR, and +\fBgetprotoent_r()\fR) and non-reentrant (\fBgetprotobyname()\fR, +\fBgetprotobynumber()\fR, and \fBgetprotoent()\fR). The reentrant functions can +be used in single-threaded applications and are safe for multithreaded +applications, making them the preferred interfaces. +.sp +.LP +The reentrant routines require additional parameters which are used to return +results data. \fIresult\fR is a pointer to a \fBstruct protoent\fR structure +and will be where the returned results will be stored. \fIbuffer\fR is used as +storage space for elements of the returned results. \fIbuflen\fR is the size of +\fIbuffer\fR and should be large enough to contain all returned data. +\fIbuflen\fR must be at least 1024 bytes. +.sp +.LP +\fBgetprotobyname_r()\fR, \fBgetprotobynumber_r()\fR, and \fBgetprotoent_r()\fR +each return a protocol entry. +.sp +.LP +The entry may come from one of the following sources: the protocols file (see +\fBprotocols\fR(4)), the \fBNIS\fR maps ``protocols.byname'' and +``protocols.bynumber'', and the \fBNIS+\fR table ``protocols''. The sources and +their lookup order are specified in the \fB/etc/nsswitch.conf\fR file (see +\fBnsswitch.conf\fR(4) for details). Some name services such as NIS will return +only one name for a host, whereas others such as NIS+ or DNS will return all +aliases. +.sp +.LP +The \fBgetprotobyname_r()\fR and \fBgetprotobynumber_r()\fR functions +sequentially search from the beginning of the file until a matching protocol +name or protocol number is found, or until an EOF is encountered. +.sp +.LP +\fBgetprotobyname()\fR and \fBgetprotobynumber()\fR have the same functionality +as \fBgetprotobyname_r()\fR and \fBgetprotobynumber_r()\fR except that a static +buffer is used to store returned results. These functions are Unsafe in a +multithreaded application. +.sp +.LP +\fBgetprotoent_r()\fR enumerates protocol entries: successive calls to +\fBgetprotoent_r()\fR will return either successive protocol entries or +\fINULL\fR. Enumeration might not be supported by some sources. If multiple +threads call \fBgetprotoent_r()\fR, each will retrieve a subset of the protocol +database. +.sp +.LP +\fBgetprotent()\fR has the same functionality as \fBgetprotent_r()\fR except +that a static buffer is used to store returned results. This routine is unsafe +in a multithreaded application. +.sp +.LP +\fBsetprotoent()\fR "rewinds" to the beginning of the enumeration of protocol +entries. If the \fIstayopen\fR flag is non-zero, resources such as open file +descriptors are not deallocated after each call to \fBgetprotobynumber_r()\fR +and \fBgetprotobyname_r()\fR. Calls to \fBgetprotobyname_r()\fR \fB,\fR The +\fBgetprotobyname()\fR, \fBgetprotobynumber_r()\fR, and +\fBgetprotobynumber()\fR functions might leave the enumeration in an +indeterminate state, so \fBsetprotoent()\fR should be called before the first +call to \fBgetprotoent_r()\fR or \fBgetprotoent()\fR. The \fBsetprotoent()\fR +function has process-wide scope, and ``rewinds'' the protocol entries for all +threads calling \fBgetprotoent_r()\fR as well as main-thread calls to +\fBgetprotoent()\fR. +.sp +.LP +The \fBendprotoent()\fR function can be called to indicate that protocol +processing is complete; the system may then close any open protocols file, +deallocate storage, and so forth. It is legitimate, but possibly less +efficient, to call more protocol functions after \fBendprotoent()\fR. +.sp +.LP +The internal representation of a protocol entry is a \fBprotoent\fR structure +defined in <\fBnetdb.h\fR> with the following members: +.sp +.in +2 +.nf +char *p_name; +char **p_aliases; +int p_proto; +.fi +.in -2 + +.SH RETURN VALUES +.sp +.LP +The \fBgetprotobyname_r()\fR, \fBgetprotobyname()\fR, +\fBgetprotobynumber_r()\fR, and \fBgetprotobynumber()\fR functions return a +pointer to a \fBstruct protoent\fR if they successfully locate the requested +entry; otherwise they return \fBNULL.\fR +.sp +.LP +The \fBgetprotoent_r()\fR and \fBgetprotoent()\fR functions return a pointer to +a \fBstruct protoent\fR if they successfully enumerate an entry; otherwise they +return \fINULL\fR, indicating the end of the enumeration. +.SH ERRORS +.sp +.LP +The \fBgetprotobyname_r()\fR, \fBgetprotobynumber_r()\fR, and +\fBgetprotoent_r()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The length of the buffer supplied by the caller is not large enough to store +the result. +.RE + +.SH FILES +.sp +.LP +\fB/etc/protocols\fR +.sp +.LP +\fB/etc/nsswitch.conf\fR +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSee \fBNOTES\fR below. +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(3), \fBnsswitch.conf\fR(4), \fBprotocols\fR(4), +\fBattributes\fR(5), \fBnetdb.h\fR(3HEAD) +.SH NOTES +.sp +.LP +Although \fBgetprotobyname_r()\fR, \fBgetprotobynumber_r()\fR, and +\fBgetprotoent_r()\fR are not mentioned by POSIX 1003.1:2001, they were added +to complete the functionality provided by similar thread-safe functions. +.sp +.LP +When compiling multithreaded applications, see \fBIntro\fR(3), \fINotes On +Multithread Applications\fR, for information about the use of the +\fB_REENTRANT\fR flag. +.sp +.LP +The \fBgetprotobyname_r()\fR, \fBgetprotobynumber_r()\fR, and +\fBgetprotoent_r()\fR functions are reentrant and multithread safe. The +reentrant interfaces can be used in single-threaded as well as multithreaded +applications and are therefore the preferred interfaces. +.sp +.LP +The \fBgetprotobyname()\fR, \fBgetprotobyaddr()\fR, and \fBgetprotoent()\fR +functions use static storage, so returned data must be copied if it is to be +saved. Because of their use of static storage for returned data, these +functions are not safe for multithreaded applications. +.sp +.LP +The \fBsetprotoent()\fR and \fBendprotoent()\fR functions have process-wide +scope, and are therefore not safe in multi-threaded applications. +.sp +.LP +Use of \fBgetprotoent_r()\fR and \fBgetprotoent()\fR is discouraged; +enumeration is well-defined for the protocols file and is supported (albeit +inefficiently) for \fBNIS\fR and \fBNIS+,\fR but in general may not be +well-defined. The semantics of enumeration are discussed in +\fBnsswitch.conf\fR(4). +.SH BUGS +.sp +.LP +Only the Internet protocols are currently understood. diff --git a/usr/src/man/man3socket/getservbyname.3socket b/usr/src/man/man3socket/getservbyname.3socket new file mode 100644 index 0000000000..606ca35ff2 --- /dev/null +++ b/usr/src/man/man3socket/getservbyname.3socket @@ -0,0 +1,354 @@ +'\" te +.\" Copyright (c) 1983, Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. Copyright 1989 AT&T. Copyright (c) 2007, Sun Microsystems, Inc. +.\" All Rights Reserved. +.TH getservbyname 3SOCKET "31 Jan 2007" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +getservbyname, getservbyname_r, getservbyport, getservbyport_r, getservent, +getservent_r, setservent, endservent \- get service entry +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ] +#include <netdb.h> + +\fBstruct servent *\fR\fBgetservbyname\fR(\fBconst char *\fR\fIname\fR, \fBconst char *\fR\fIproto\fR); +.fi + +.LP +.nf +\fBstruct servent *\fR\fBgetservbyname_r\fR(\fBconst char *\fR\fIname\fR, \fBconst char *\fR\fIproto\fR, + \fBstruct servent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBstruct servent *\fR\fBgetservbyport\fR(\fBint\fR \fIport\fR, \fBconst char *\fR\fIproto\fR); +.fi + +.LP +.nf +\fBstruct servent *\fR\fBgetservbyport_r\fR(\fBint\fR \fIport\fR, \fBconst char *\fR\fIproto\fR, + \fBstruct servent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBstruct servent *\fR\fBgetservent\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBstruct servent *\fR\fBgetservent_r\fR(\fBstruct servent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, + \fBint\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBint\fR \fBsetservent\fR(\fBint\fR \fIstayopen\fR); +.fi + +.LP +.nf +\fBint\fR \fBendservent\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are used to obtain entries for Internet services. An entry may +come from any of the sources for \fBservices\fR specified in the +\fB/etc/nsswitch.conf\fR file. See \fBnsswitch.conf\fR(4). +.sp +.LP +The \fBgetservbyname()\fR and \fBgetservbyport()\fR functions sequentially +search from the beginning of the file until a matching protocol name or port +number is found, or until end-of-file is encountered. If a protocol name is +also supplied (non-null), searches must also match the protocol. +.sp +.LP +The \fBgetservbyname()\fR function searches for an entry with the Internet +service name specified by the \fIname\fR parameter. +.sp +.LP +The \fBgetservbyport()\fR function searches for an entry with the Internet port +number \fIport\fR. +.sp +.LP +All addresses are returned in network order. In order to interpret the +addresses, \fBbyteorder\fR(3SOCKET) must be used for byte order conversion. The +string \fIproto\fR is used by both \fBgetservbyname()\fR and +\fBgetservbyport()\fR to restrict the search to entries with the specified +protocol. If \fIproto\fR is \fINULL\fR, entries with any protocol can be +returned. +.sp +.LP +The functions \fBsetservent()\fR, \fBgetservent()\fR, and \fBendservent()\fR +are used to enumerate entries from the services database. +.sp +.LP +The \fBsetservent()\fR function sets (or resets) the enumeration to the +beginning of the set of service entries. This function should be called before +the first call to \fBgetservent()\fR. Calls to the functions +\fBgetservbyname()\fR and \fBgetservbyport()\fR leave the enumeration position +in an indeterminate state. If the \fIstayopen\fR flag is non-zero, the system +may keep allocated resources such as open file descriptors until a subsequent +call to \fBendservent()\fR. +.sp +.LP +The \fBgetservent()\fR function reads the next line of the file, opening the +file if necessary. \fBgetservent()\fR opens and rewinds the file. If the +\fIstayopen\fR flag is non-zero, the net data base will not be closed after +each call to \fBgetservent()\fR (either directly, or indirectly through one of +the other "getserv"calls). +.sp +.LP +Successive calls to \fBgetservent()\fR return either successive entries or +\fINULL\fR, indicating the end of the enumeration. +.sp +.LP +The \fBendservent()\fR function closes the file. The \fBendservent()\fR +function can be called to indicate that the caller expects to do no further +service entry retrieval operations; the system can then deallocate resources it +was using. It is still allowed, but possibly less efficient, for the process +to call more service entry retrieval functions after calling +\fBendservent()\fR. +.SS "Reentrant Interfaces" +.sp +.LP +The functions \fBgetservbyname()\fR, \fBgetservbyport()\fR, and +\fBgetservent()\fR use static storage that is re-used in each call, making +these functions unsafe for use in multithreaded applications. +.sp +.LP +The functions \fBgetservbyname_r()\fR, \fBgetservbyport_r()\fR, and +\fBgetservent_r()\fR provide reentrant interfaces for these operations. +.sp +.LP +Each reentrant interface performs the same operation as its non-reentrant +counterpart, named by removing the "\fB_r\fR" suffix. The reentrant +interfaces, however, use buffers supplied by the caller to store returned +results, and are safe for use in both single-threaded and multithreaded +applications. +.sp +.LP +Each reentrant interface takes the same parameters as its non-reentrant +counterpart, as well as the following additional parameters. The parameter +\fIresult\fR must be a pointer to a \fBstruct servent\fR structure allocated by +the caller. On successful completion, the function returns the service entry +in this structure. The parameter \fIbuffer\fR must be a pointer to a buffer +supplied by the caller. This buffer is used as storage space for the service +entry data. All of the pointers within the returned \fBstruct servent\fR +\fIresult\fR point to data stored within this buffer. See the RETURN VALUES +section of this manual page. The buffer must be large enough to hold all of the +data associated with the service entry. The parameter \fIbuflen\fR should give +the size in bytes of the buffer indicated by \fIbuffer\fR. +.sp +.LP +For enumeration in multithreaded applications, the position within the +enumeration is a process-wide property shared by all threads. The +\fBsetservent()\fR function can be used in a multithreaded application but +resets the enumeration position for all threads. If multiple threads +interleave calls to \fBgetservent_r()\fR, the threads will enumerate disjoint +subsets of the service database. +.sp +.LP +Like their non-reentrant counterparts, \fBgetservbyname_r()\fR and +\fBgetservbyport_r()\fR leave the enumeration position in an indeterminate +state. +.SH RETURN VALUES +.sp +.LP +Service entries are represented by the \fBstruct servent\fR structure defined +in <\fBnetdb.h\fR>: +.sp +.in +2 +.nf +struct servent { + char *s_name; /* official name of service */ + char **s_aliases; /* alias list */ + int s_port; /* port service resides at */ + char *s_proto; /* protocol to use */ +}; +.fi +.in -2 + +.sp +.LP +The members of this structure are: +.sp +.ne 2 +.mk +.na +\fB\fBs_name\fR\fR +.ad +.RS 13n +.rt +The official name of the service. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBs_aliases\fR\fR +.ad +.RS 13n +.rt +A zero terminated list of alternate names for the service. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBs_port\fR\fR +.ad +.RS 13n +.rt +The port number at which the service resides. Port numbers are +returned in network byte order. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBs_proto\fR\fR +.ad +.RS 13n +.rt +The name of the protocol to use when contacting the service +.RE + +.sp +.LP +The functions \fBgetservbyname()\fR, \fBgetservbyname_r()\fR, +\fBgetservbyport()\fR, and \fBgetservbyport_r()\fR each return a pointer to a +\fBstruct servent\fR if they successfully locate the requested entry; otherwise +they return \fINULL\fR. +.sp +.LP +The functions \fBgetservent()\fR and \fBgetservent_r()\fR each return a pointer +to a \fBstruct servent\fR if they successfully enumerate an entry; otherwise +they return \fINULL,\fR indicating the end of the enumeration. +.sp +.LP +The functions \fBgetservbyname()\fR, \fBgetservbyport()\fR, and +\fBgetservent()\fR use static storage, so returned data must be copied before a +subsequent call to any of these functions if the data is to be saved. +.sp +.LP +When the pointer returned by the reentrant functions \fBgetservbyname_r()\fR, +\fBgetservbyport_r()\fR, and \fBgetservent_r()\fR is non-null, it is always +equal to the \fIresult\fR pointer that was supplied by the caller. +.SH ERRORS +.sp +.LP +The reentrant functions \fBgetservbyname_r()\fR, \fBgetservbyport_r()\fR, and +\fBgetservent_r()\fR return \fINULL\fR and set \fBerrno\fR to \fBERANGE\fR if +the length of the buffer supplied by caller is not large enough to store the +result. See \fBIntro\fR(2) for the proper usage and interpretation of +\fBerrno\fR in multithreaded applications. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/services\fR\fR +.ad +.RS 22n +.rt +Internet network services +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/netconfig\fR\fR +.ad +.RS 22n +.rt +network configuration file +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB/etc/nsswitch.conf\fR\fR +.ad +.RS 22n +.rt +configuration file for the name-service switch +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelT{ +See "Reentrant Interfaces" in \fBDESCRIPTION\fR. +T} +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(2), \fBIntro\fR(3), \fBbyteorder\fR(3SOCKET), \fBnetdir\fR(3NSL), +\fBnetconfig\fR(4), \fBnsswitch.conf\fR(4), \fBservices\fR(4), +\fBattributes\fR(5), \fBnetdb.h\fR(3HEAD) +.SH WARNINGS +.sp +.LP +The reentrant interfaces \fBgetservbyname_r()\fR, \fBgetservbyport_r()\fR, and +\fBgetservent_r()\fR are included in this release on an uncommitted basis only, +and are subject to change or removal in future minor releases. +.SH NOTES +.sp +.LP +The functions that return \fBstruct servent\fR return the least significant +16-bits of the \fIs_port\fR field in \fInetwork byte order\fR. +\fBgetservbyport()\fR and \fBgetservbyport_r()\fR also expect the input +parameter \fIport\fR in the \fInetwork byte order\fR. See \fBhtons\fR(3SOCKET) +for more details on converting between host and network byte orders. +.sp +.LP +To ensure that they all return consistent results, \fBgetservbyname()\fR, +\fBgetservbyname_r()\fR, and \fBnetdir_getbyname()\fR are implemented in terms +of the same internal library function. This function obtains the system-wide +source lookup policy based on the \fBinet\fR family entries in +\fBnetconfig\fR(4) and the \fBservices:\fR entry in \fBnsswitch.conf\fR(4). +Similarly, \fBgetservbyport()\fR, \fBgetservbyport_r()\fR, and +\fBnetdir_getbyaddr()\fR are implemented in terms of the same internal library +function. If the \fBinet\fR family entries in \fBnetconfig\fR(4) have a ``-'' +in the last column for nametoaddr libraries, then the entry for \fBservices\fR +in \fBnsswitch.conf\fR will be used; otherwise the nametoaddr libraries in that +column will be used, and \fBnsswitch.conf\fR will not be consulted. +.sp +.LP +There is no analogue of \fBgetservent()\fR and \fBgetservent_r()\fR in the +netdir functions, so these enumeration functions go straight to the +\fBservices\fR entry in \fBnsswitch.conf\fR. Thus enumeration may return +results from a different source than that used by \fBgetservbyname()\fR, +\fBgetservbyname_r()\fR, \fBgetservbyport()\fR, and \fBgetservbyport_r()\fR. +.sp +.LP +When compiling multithreaded applications, see \fBIntro\fR(3), \fINotes On +Multithread Applications\fR, for information about the use of the +\fB_REENTRANT\fR flag. +.sp +.LP +Use of the enumeration interfaces \fBgetservent()\fR and \fBgetservent_r()\fR +is discouraged; enumeration may not be supported for all database sources. The +semantics of enumeration are discussed further in \fBnsswitch.conf\fR(4). diff --git a/usr/src/man/man3socket/getsockname.3socket b/usr/src/man/man3socket/getsockname.3socket new file mode 100644 index 0000000000..f5e5194554 --- /dev/null +++ b/usr/src/man/man3socket/getsockname.3socket @@ -0,0 +1,101 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, 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 getsockname 3SOCKET "12 Dec 1997" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +getsockname \- get socket name +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ] +#include <sys/types.h> +#include <sys/socket.h> + +\fBint\fR \fBgetsockname\fR(\fBint\fR \fIs\fR, \fBstruct sockaddr *\fR\fIname\fR, \fBsocklen_t *\fR\fInamelen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBgetsockname()\fR returns the current \fIname\fR for socket \fIs\fR. The +\fInamelen\fR parameter should be initialized to indicate the amount of space +pointed to by \fIname\fR. On return it contains the actual size in bytes of the +name returned. +.SH RETURN VALUES +.sp +.LP +If successful, \fBgetsockname()\fR returns \fB0\fR; otherwise it returns +\fB\(mi1\fR and sets \fIerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The call succeeds unless: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 12n +.rt +The argument \fIs\fR is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 12n +.rt +There was insufficient memory available for the operation to complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 12n +.rt +There were insufficient STREAMS resources available for the operation to +complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 12n +.rt +The argument \fIs\fR is not a socket. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBbind\fR(3SOCKET), \fBgetpeername\fR(3SOCKET), \fBsocket\fR(3SOCKET), +\fBattributes\fR(5) diff --git a/usr/src/man/man3socket/getsockopt.3socket b/usr/src/man/man3socket/getsockopt.3socket new file mode 100644 index 0000000000..7aeaa140b3 --- /dev/null +++ b/usr/src/man/man3socket/getsockopt.3socket @@ -0,0 +1,602 @@ +'\" te +.\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" 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 getsockopt 3SOCKET "27 Jan 2009" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +getsockopt, setsockopt \- get and set options on sockets +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ] +#include <sys/types.h> +#include <sys/socket.h> + +\fBint\fR \fBgetsockopt\fR(\fBint\fR \fIs\fR, \fBint\fR \fIlevel\fR, \fBint\fR \fIoptname\fR, \fBvoid *\fR\fIoptval\fR, + \fBint *\fR\fIoptlen\fR); +.fi + +.LP +.nf +\fBint\fR \fBsetsockopt\fR(\fBint\fR \fIs\fR, \fBint\fR \fIlevel\fR, \fBint\fR \fIoptname\fR, \fBconst void *\fR\fIoptval\fR, + \fBint\fR \fIoptlen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetsockopt()\fR and \fBsetsockopt()\fR functions manipulate options +associated with a socket. Options may exist at multiple protocol levels; they +are always present at the uppermost "socket" level. +.sp +.LP +The \fIlevel\fR argument specifies the protocol level at which the option +resides. To manipulate options at the socket level, specify the \fIlevel\fR +argument as \fBSOL_SOCKET\fR. To manipulate options at the protocol level, +supply the appropriate protocol number for the protocol controlling the option. +For example, to indicate that an option will be interpreted by the \fBTCP\fR, +set \fIlevel\fR to the protocol number of \fBTCP\fR, as defined in the +\fB<netinet/in.h>\fR header, or as determined by using +\fBgetprotobyname\fR(3SOCKET). Some socket protocol families may also define +additional levels, such as \fBSOL_ROUTE\fR. Only socket-level options are +described here. +.sp +.LP +The parameters \fIoptval\fR and \fIoptlen\fR are used to access option values +for \fBsetsockopt()\fR. For \fBgetsockopt()\fR, they identify a buffer in which +the value(s) for the requested option(s) are to be returned. For +\fBgetsockopt()\fR, \fIoptlen\fR is a value-result parameter, initially +containing the size of the buffer pointed to by \fIoptval\fR, and modified on +return to indicate the actual size of the value returned. Use a 0 \fIoptval\fR +if no option value is to be supplied or returned. +.sp +.LP +The \fIoptname\fR and any specified options are passed uninterpreted to the +appropriate protocol module for interpretation. The include file +<\fBsys/socket.h\fR> contains definitions for the socket-level options +described below. Options at other protocol levels vary in format and name. +.sp +.LP +Most socket-level options take an \fBint\fR for \fIoptval\fR. For +\fBsetsockopt()\fR, the \fIoptval\fR parameter should be non-zero to enable a +boolean option, or zero if the option is to be disabled. \fBSO_LINGER\fR uses a +\fBstruct linger\fR parameter that specifies the desired state of the option +and the linger interval. \fBstruct linger\fR is defined in +<\fBsys/socket.h\fR>. \fBstruct\fR \fBlinger\fR contains the following members: +.sp +.ne 2 +.mk +.na +\fB\fBl_onoff\fR\fR +.ad +.RS 12n +.rt +on = 1/off = 0 +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBl_linger\fR\fR +.ad +.RS 12n +.rt +linger time, in seconds +.RE + +.sp +.LP +The following options are recognized at the socket level. Except as noted, each +may be examined with \fBgetsockopt()\fR and set with \fBsetsockopt()\fR. +.sp +.ne 2 +.mk +.na +\fB\fBSO_DEBUG\fR\fR +.ad +.RS 19n +.rt +enable/disable recording of debugging information +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_REUSEADDR\fR\fR +.ad +.RS 19n +.rt +enable/disable local address reuse +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_KEEPALIVE\fR\fR +.ad +.RS 19n +.rt +enable/disable keep connections alive +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_DONTROUTE\fR\fR +.ad +.RS 19n +.rt +enable/disable routing bypass for outgoing messages +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_LINGER\fR\fR +.ad +.RS 19n +.rt +linger on close if data is present +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_BROADCAST\fR\fR +.ad +.RS 19n +.rt +enable/disable permission to transmit broadcast messages +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_OOBINLINE\fR\fR +.ad +.RS 19n +.rt +enable/disable reception of out-of-band data in band +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_SNDBUF\fR\fR +.ad +.RS 19n +.rt +set buffer size for output +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_RCVBUF\fR\fR +.ad +.RS 19n +.rt +set buffer size for input +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_DGRAM_ERRIND\fR\fR +.ad +.RS 19n +.rt +application wants delayed error +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_TIMESTAMP\fR\fR +.ad +.RS 19n +.rt +enable/disable reception of timestamp with datagrams +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_EXCLBIND\fR\fR +.ad +.RS 19n +.rt +enable/disable exclusive binding of the socket +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_TYPE\fR\fR +.ad +.RS 19n +.rt +get the type of the socket (get only) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_ERROR\fR\fR +.ad +.RS 19n +.rt +get and clear error on the socket (get only) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_MAC_EXEMPT\fR\fR +.ad +.RS 19n +.rt +get or set mandatory access control on the socket. This option is available +only when the system is configured with Trusted Extensions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_ALLZONES\fR\fR +.ad +.RS 19n +.rt +bypass zone boundaries (privileged). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_DOMAIN\fR\fR +.ad +.RS 19n +.rt +get the domain used in the socket (get only) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_PROTOTYPE\fR\fR +.ad +.RS 19n +.rt +for socket in domains \fBPF_INET\fR and \fBPF_INET6\fR, get the underlying +protocol number used in the socket. For socket in domain \fBPF_ROUTE\fR, get +the address family used in the socket. +.RE + +.sp +.LP +The \fBSO_DEBUG\fR option enables debugging in the underlying protocol modules. +The \fBSO_REUSEADDR\fR option indicates that the rules used in validating +addresses supplied in a \fBbind\fR(3SOCKET) call should allow reuse of local +addresses. The \fBSO_KEEPALIVE\fR option enables the periodic transmission of +messages on a connected socket. If the connected party fails to respond to +these messages, the connection is considered broken and threads using the +socket are notified using a \fBSIGPIPE\fR signal. The \fBSO_DONTROUTE\fR option +indicates that outgoing messages should bypass the standard routing facilities. +Instead, messages are directed to the appropriate network interface according +to the network portion of the destination address. +.sp +.LP +The \fBSO_LINGER\fR option controls the action taken when unsent messages are +queued on a socket and a \fBclose\fR(2) is performed. If the socket promises +reliable delivery of data and \fBSO_LINGER\fR is set, the system will block the +thread on the \fBclose()\fR attempt until it is able to transmit the data or +until it decides it is unable to deliver the information (a timeout period, +termed the linger interval, is specified in the \fBsetsockopt()\fR call when +\fBSO_LINGER\fR is requested). If \fBSO_LINGER\fR is disabled and a +\fBclose()\fR is issued, the system will process the \fBclose()\fR in a manner +that allows the thread to continue as quickly as possible. +.sp +.LP +The option \fBSO_BROADCAST\fR requests permission to send broadcast datagrams +on the socket. With protocols that support out-of-band data, the +\fBSO_OOBINLINE\fR option requests that out-of-band data be placed in the +normal data input queue as received; it will then be accessible with +\fBrecv()\fR or \fBread()\fR calls without the \fBMSG_OOB\fR flag. +.sp +.LP +The \fBSO_SNDBUF\fR and \fBSO_RCVBUF\fR options adjust the normal buffer sizes +allocated for output and input buffers, respectively. The buffer size may be +increased for high-volume connections or may be decreased to limit the possible +backlog of incoming data. The maximum buffer size for \fBUDP\fR is determined +by the value of the \fBndd\fR variable \fBudp_max_buf\fR. The maximum buffer +size for \fBTCP\fR is determined the value of the \fBndd\fR variable +\fBtcp_max_buf\fR. Use the \fBndd\fR(1M) utility to determine the current +default values. See the \fISolaris Tunable Parameters Reference Manual\fR for +information on setting the values of \fBudp_max_buf\fR and \fBtcp_max_buf\fR. +At present, lowering \fBSO_RCVBUF\fR on a TCP connection after it has been +established has no effect. +.sp +.LP +By default, delayed errors (such as \fBICMP\fR port unreachable packets) are +returned only for connected datagram sockets. The \fBSO_DGRAM_ERRIND\fR option +makes it possible to receive errors for datagram sockets that are not +connected. When this option is set, certain delayed errors received after +completion of a \fBsendto()\fR or \fBsendmsg()\fR operation will cause a +subsequent \fBsendto()\fR or \fBsendmsg()\fR operation using the same +destination address (\fIto\fR parameter) to fail with the appropriate error. +See \fBsend\fR(3SOCKET). +.sp +.LP +If the \fBSO_TIMESTAMP\fR option is enabled on a \fBSO_DGRAM\fR or a +\fBSO_RAW\fR socket, the \fBrecvmsg\fR(3XNET) call will return a timestamp in +the native data format, corresponding to when the datagram was received. +.sp +.LP +The \fBSO_EXCLBIND\fR option is used to enable or disable the exclusive binding +of a socket. It overrides the use of the \fBSO_REUSEADDR\fR option to reuse an +address on \fBbind\fR(3SOCKET). The actual semantics of the \fBSO_EXCLBIND\fR +option depend on the underlying protocol. See \fBtcp\fR(7P) or \fBudp\fR(7P) +for more information. +.sp +.LP +The \fBSO_TYPE\fR and \fBSO_ERROR\fR options are used only with +\fBgetsockopt()\fR. The \fBSO_TYPE\fR option returns the type of the socket, +for example, \fBSOCK_STREAM\fR. It is useful for servers that inherit sockets +on startup. The \fBSO_ERROR\fR option returns any pending error on the socket +and clears the error status. It may be used to check for asynchronous errors on +connected datagram sockets or for other asynchronous errors. +.sp +.LP +The \fBSO_MAC_EXEMPT\fR option is used to toggle socket behavior with unlabeled +peers. A socket that has this option enabled can communicate with an unlabeled +peer if it is in the global zone or has a label that dominates the default +label of the peer. Otherwise, the socket must have a label that is equal to the +default label of the unlabeled peer. Calling \fBsetsockopt()\fR with this +option returns an \fBEACCES\fR error if the process lacks the +\fBNET_MAC_AWARE\fR privilege or if the socket is bound. The +\fBSO_MAC_EXEMPT\fR option is available only when the system is configured with +Trusted Extensions. +.sp +.LP +The \fBSO_ALLZONES\fR option can be used to bypass zone boundaries between +shared-IP zones. Normally, the system prevents a socket from being bound to an +address that is not assigned to the current zone. It also prevents a socket +that is bound to a wildcard address from receiving traffic for other zones. +However, some daemons which run in the global zone might need to send and +receive traffic using addresses that belong to other shared-IP zones. If set +before a socket is bound, \fBSO_ALLZONES\fR causes the socket to ignore zone +boundaries between shared-IP zones and permits the socket to be bound to any +address assigned to the shared-IP zones. If the socket is bound to a wildcard +address, it receives traffic intended for all shared-IP zones and behaves as if +an equivalent socket were bound in each active shared-IP zone. Applications +that use the \fBSO_ALLZONES\fR option to initiate connections or send datagram +traffic should specify the source address for outbound traffic by binding to a +specific address. There is no effect from setting this option in an +exclusive-IP zone. Setting this option requires the \fBsys_net_config\fR +privilege. See \fBzones\fR(5). +.SH RETURN VALUES +.sp +.LP +If successful, \fBgetsockopt()\fR and \fBsetsockopt()\fR return \fB0\fR. +Otherwise, the functions return \fB\(mi1\fR and set \fBerrno\fR to indicate the +error. +.SH ERRORS +.sp +.LP +The \fBgetsockopt()\fR and \fBsetsockopt()\fR calls succeed unless: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 17n +.rt +The argument \fIs\fR is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 17n +.rt +There was insufficient memory available for the operation to complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOPROTOOPT\fR\fR +.ad +.RS 17n +.rt +The option is unknown at the level indicated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 17n +.rt +There were insufficient STREAMS resources available for the operation to +complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 17n +.rt +The argument \fIs\fR is not a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 17n +.rt +\fBSO_SNDBUF\fR or \fBSO_RCVBUF\fR exceeds a system limit. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 17n +.rt +Invalid length for \fBIP_OPTIONS\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEHOSTUNREACH\fR\fR +.ad +.RS 17n +.rt +Invalid address for \fBIP_MULTICAST_IF\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 17n +.rt +Not a multicast address for \fBIP_ADD_MEMBERSHIP\fR and +\fBIP_DROP_MEMBERSHIP\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEADDRNOTAVAIL\fR\fR +.ad +.RS 17n +.rt +Bad interface address for \fBIP_ADD_MEMBERSHIP\fR and \fBIP_DROP_MEMBERSHIP\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEADDRINUSE\fR\fR +.ad +.RS 17n +.rt +Address already joined for \fBIP_ADD_MEMBERSHIP\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 17n +.rt +Address not joined for \fBIP_DROP_MEMBERSHIP\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPERM\fR\fR +.ad +.RS 17n +.rt +No permissions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 17n +.rt +Permission denied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 17n +.rt +The specified option is invalid at the specified socket level, or the socket +has been shut down. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBndd\fR(1M), \fBclose\fR(2), \fBioctl\fR(2), \fBread\fR(2), +\fBbind\fR(3SOCKET), \fBgetprotobyname\fR(3SOCKET), \fBrecv\fR(3SOCKET), +\fBrecvmsg\fR(3XNET), \fBsend\fR(3SOCKET), \fBsocket\fR(3SOCKET), +\fBsocket.h\fR(3HEAD), \fBattributes\fR(5), \fBzones\fR(5), \fBtcp\fR(7P), +\fBudp\fR(7P) +.sp +.LP +\fISolaris Tunable Parameters Reference Manual\fR diff --git a/usr/src/man/man3socket/getsourcefilter.3socket b/usr/src/man/man3socket/getsourcefilter.3socket new file mode 100644 index 0000000000..64707387d1 --- /dev/null +++ b/usr/src/man/man3socket/getsourcefilter.3socket @@ -0,0 +1,245 @@ +'\" te +.\" 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 getsourcefilter 3SOCKET "20 Aug 2007" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +getsourcefilter, setsourcefilter, getipv4sourcefilter, setipv4sourcefilter \- +retrieve and set a socket's multicast filter +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR [ \fIlibrary\fR... ] +#include <netinet/in.h> + +\fBint\fR \fBgetsourcefilter\fR(\fBint\fR \fIs\fR, \fBuint32_t\fR \fIinterface\fR, + \fBstruct sockaddr *\fR\fIgroup\fR, \fBsocklen_t\fR \fIgrouplen\fR, \fBuint32_t *\fR\fIfmode\fR, + \fBuint_t *\fR\fInumsrc\fR, \fBstruct sockaddr_storage *\fR\fIslist\fR); +.fi + +.LP +.nf +\fBint\fR \fBsetsourcefilter\fR(\fBint\fR \fIs\fR, \fBuint32_t\fR \fIinterface\fR, + \fBstruct sockaddr *\fR\fIgroup\fR, \fBsocklen_t\fR \fIgrouplen\fR, \fBuint32_t\fR \fIfmode\fR, + \fBuint_t\fR \fInumsrc\fR, \fBstruct sockaddr_storage *\fR\fIslist\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetipv4sourcefilter\fR(\fBint\fR \fIs\fR, \fBstruct in_addr\fR \fIinterface\fR, + \fBstruct in_addr\fR \fIgroup\fR, \fBuint32_t *\fR\fIfmode\fR, \fBuint32_t *\fR\fInumsrc\fR, + \fBstruct in_addr *\fR\fIslist\fR); +.fi + +.LP +.nf +\fBint\fR \fBsetipv4sourcefilter\fR(\fBint\fR \fIs\fR, \fBstruct in_addr\fR \fIinterface\fR, + \fBstruct in_addr\fR \fIgroup\fR,\fBuint32_t\fR \fIfmode\fR, \fBuint32_t\fR \fInumsrc\fR, + \fBstruct in_addr *\fR\fIslist\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions allow applications to retrieve and modify the multicast +filtering state for a tuple consisting of socket, interface, and multicast +group values. +.sp +.LP +A multicast filter is described by a filter mode, which is \fBMODE_INCLUDE\fR +or \fBMODE_EXCLUDE\fR, and a list of source addresses which are filtered. If a +group is simply joined with no source address restrictions, the filter mode is +\fBMODE_EXCLUDE\fR and the source list is empty. +.sp +.LP +The \fBgetsourcefilter()\fR and \fBsetsourcefilter()\fR functions are +protocol-independent. They can be used on either \fBPF_INET\fR or +\fBPF_INET6\fR sockets. The \fBgetipv4sourcefilter()\fR and +\fBsetipv4sourcefilter()\fR functions are IPv4-specific. They must be used only +on \fBPF_INET\fR sockets. +.sp +.LP +For the protocol-independent functions, the first four arguments identify the +socket, interface, multicast group tuple values. The argument \fIs\fR is an +open socket of type \fBSOCK_DGRAM\fR or \fBSOCK_RAW\fR. The \fIinterface\fR +argument is the interface index. The interface name can be mapped to the index +using \fBif_nametoindex\fR(3SOCKET). The \fIgroup\fR points to either a +\fBsockaddr_in\fR containing an IPv4 multicast address if the socket is +\fBPF_INET\fR or a \fBsockaddr_in6\fR containing an IPv6 multicast address if +the socket is \fBPF_INET6\fR. The \fIgrouplen\fR is the size of the structure +pointed to by \fIgroup\fR. +.sp +.LP +For the IPv4-specific functions, the first three arguments identify the same +socket, interface, multicast group tuple values. The argument \fIs\fR is an +open socket of type \fBSOCK_DGRAM\fR or \fBSOCK_RAW\fR and protocol family +\fBPF_INET\fR. The \fIinterface\fR argument is the IPv4 address assigned to the +local interface. The \fIgroup\fR argument is the IPv4 multicast address. +.sp +.LP +The \fBgetsourcefilter()\fR and \fBgetipv4sourcefilter()\fR functions retrieve +the current filter for the given tuple consisting of socket, interface, and +multicast group values. On successful return, \fIfmode\fR contains either +\fBMODE_INCLUDE\fR or \fBMODE_EXCLUDE\fR, indicating the filter mode. On input, +the \fInumsrc\fR argument holds the number of addresses that can fit in the +\fIslist\fR array. On return, \fIslist\fR contains as many addresses as fit, +while \fInumsrc\fR contains the total number of source addresses in the filter. +It is possible that \fInumsrc\fR can contain a number larger than the number of +addresses in the \fIslist\fR array. An application might determine the required +buffer size by calling \fBgetsourcefilter()\fR with \fInumsrc\fR containing +\fB0\fR and \fIslist\fR a \fBNULL\fR pointer. On return, \fInumsrc\fR contains +the number of elements that the \fIslist\fR buffer must be able to hold. +Alternatively, the maximum number of source addresses allowed by this +implementation is defined in \fB<netinet/in.h>\fR: +.sp +.in +2 +.nf +#define MAX_SRC_FILTER_SIZE 64 +.fi +.in -2 + +.sp +.LP +The \fBsetsourcefilter()\fR and \fBsetipv4sourcefilter\fR functions replace the +current filter with the filter specified in the arguments \fIfmode\fR, +\fInumsrc\fR, and \fIslist\fR. The \fIfmode\fR argument must be set to either +\fBMODE_INCLUDE\fR or \fBMODE_EXCLUDE\fR. The \fInumsrc\fR argument is the +number of addresses in the \fIslist\fR array. The \fIslist\fR argument points +to the array of source addresses to be included or excluded, depending on the +\fIfmode\fR value. +.SH RETURN VALUES +.sp +.LP +If successful, all four functions return \fB0\fR. Otherwise, they return +\fB\(mi1\fR and set \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +These functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 16n +.rt +The \fIs\fR argument is not a valid descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAFNOSUPPORT\fR\fR +.ad +.RS 16n +.rt +The address family of the passed-in \fIsockaddr\fR is not \fBAF_INET\fR or +\fBAF_INET6\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOPROTOOPT\fR\fR +.ad +.RS 16n +.rt +The socket \fIs\fR is not of type \fBSOCK_DGRAM\fR or \fBSOCK_RAW\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOPROTOOPT\fR\fR +.ad +.RS 16n +.rt +The address family of the group parameter does not match the protocol family of +the socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 16n +.rt +Insufficient \fBSTREAMS\fR resources available for the operation to complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 16n +.rt +The \fIinterface\fR argument, either an index or an IPv4 address, does not +identify a valid interface. +.RE + +.sp +.LP +The \fBgetsourcefilter()\fR and \fBgetipv4sourcefilter()\fR functions will fail +if: +.sp +.ne 2 +.mk +.na +\fB\fBEADDRNOTAVAIL\fR\fR +.ad +.RS 17n +.rt +The tuple consisting of socket, interface, and multicast group values does not +exist; \fIgroup\fR is not being listened to on \fIinterface\fR by \fIsocket\fR. +.RE + +.sp +.LP +The functions \fBsetsourcefilter()\fRand \fBsetipv4sourcefilter()\fR can fail +in the following additional case: +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 11n +.rt +The source filter list is larger than that allowed by the implementation. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBif_nametoindex\fR(3SOCKET), \fBsocket\fR(3SOCKET), \fBattributes\fR(5) +.sp +.LP +RFC 3678 diff --git a/usr/src/man/man3socket/icmp6_filter.3socket b/usr/src/man/man3socket/icmp6_filter.3socket new file mode 100644 index 0000000000..b6dd176012 --- /dev/null +++ b/usr/src/man/man3socket/icmp6_filter.3socket @@ -0,0 +1,98 @@ +'\" te +.\" Copyright 2003 AT&T +.\" 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 icmp6_filter 3SOCKET "13 Dec 2003" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +icmp6_filter \- Variable allocation datatype +.SH SYNOPSIS +.LP +.nf +\fBvoid\fR \fBICMP6_FILTER_SETPASSALL\fR (\fBstruct icmp6_filter *\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBICMP6_FILTER_SETBLOCKALL\fR (\fBstruct icmp6_filter *\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBICMP6_FILTER_SETPASS\fR (\fBint,\fR \fIstruct icmp6_filter *\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBICMP6_FILTER_SETBLOCK\fR (\fBint,\fR \fIstruct icmp6_filter *\fR); +.fi + +.LP +.nf +\fBint\fR \fBICMP6_FILTER_WILLPASS\fR (\fBint,\fR \fIconst struct icmp6_filter *\fR); +.fi + +.LP +.nf +\fBint\fR \fBICMP6_FILTER_WILLBLOCK\fR (\fBint,\fR \fIconst struct icmp6_filter *\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBicmp6_filter\fR structure is similar to the \fBfd_set\fR datatype used +with the \fBselect()\fR function in the sockets API. The \fBicmp6_filter\fR +structure is an opaque datatype and the application should not care how it is +implemented. The application allocates a variable of this type, then passes a +pointer to it. Next it passes a pointer to a variable of this type to +\fBgetsockopt()\fR and \fBsetsockopt()\fR and operates on a variable of this +type using the six macros defined below. +.sp +.LP +The \fBSETPASSALL\fR and \fBSETBLOCKALL\fR functions enable you to specify that +all ICMPv6 messages are passed to the application or that all ICMPv6 messages +are blocked from being passed. +.sp +.LP +The \fBSETPASS\fR and \fBSETBLOCKALL\fR functions enable you to specify that +messages of a given ICMPv6 type should be passed to the application or not +passed to the application (blocked). +.sp +.LP +The \fBWILLPASS\fR and \fBWILLBLOCK\fR return true or false depending whether +the specified message type is passed to the application or blocked from being +passed to the application by the filter pointed to by the second argument. +.sp +.LP +The pointer argument to all six \fBicmp6_filter\fR macros is a pointer to a +filter that is modified by the first four macros and is examined by +\fBICMP6_FILTER_SETBLOCK\fR and \fBICMP6_FILTER_WILLBLOCK\fR. The first +argument, (an integer), to the \fBICMP6_FILTER_BLOCKALL\fR, +\fBICMP6_FILTER_SETPASS\fR, \fBICMP6_FILTER_SETBLOCK\fR, and +\fBICMP6_FILTER_WILLBLOCK\fR macros is an ICMPv6 message type, between 0 and +255. +.sp +.LP +The current filter is fetched and stored using \fBgetsockopt()\fR and +\fBsetsockopt()\fR with a level of IPPROTO_ICMPV6 and an option name of +ICMP6_FILTER. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +_ +Interface StabilityStandard +.TE + diff --git a/usr/src/man/man3socket/if_nametoindex.3socket b/usr/src/man/man3socket/if_nametoindex.3socket new file mode 100644 index 0000000000..3bcb115718 --- /dev/null +++ b/usr/src/man/man3socket/if_nametoindex.3socket @@ -0,0 +1,181 @@ +'\" te +.\" Copyright (C) 2009, 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 if_nametoindex 3SOCKET "28 Jan 2009" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +if_nametoindex, if_indextoname, if_nameindex, if_freenameindex \- routines to +map Internet Protocol network interface names and interface indexes +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR [ \fIlibrary\fR... ] +#include <net/if.h> + +\fBunsigned int\fR \fBif_nametoindex\fR(\fBconst char *\fR\fIifname\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBif_indextoname\fR(\fBunsigned int\fR \fIifindex\fR, \fBchar *\fR\fIifname\fR); +.fi + +.LP +.nf +\fBstruct if_nameindex *\fR\fBif_nameindex\fR(void) +.fi + +.LP +.nf +\fBvoid\fR \fBif_freenameindex\fR(\fBstruct if_nameindex *\fR\fIptr\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIifname\fR\fR +.ad +.RS 11n +.rt +interface name +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIifindex\fR\fR +.ad +.RS 11n +.rt +interface index +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIptr\fR\fR +.ad +.RS 11n +.rt +pointer returned by \fBif_nameindex()\fR +.RE + +.SH DESCRIPTION +.sp +.LP +This \fBAPI\fR defines two functions that map between an Internet Protocol +network interface name and index, a third function that returns all the +interface names and indexes, and a fourth function to return the dynamic memory +allocated by the previous function. +.sp +.LP +Network interfaces are normally known by names such as \fBeri0\fR, \fBsl1\fR, +\fBppp2\fR, and the like. The \fIifname\fR argument must point to a buffer of +at least \fBIF_NAMESIZE\fR bytes into which the interface name corresponding to +the specified index is returned. \fBIF_NAMESIZE\fR is defined in +<\fBnet/if.h\fR> and its value includes a terminating null byte at the end of +the interface name. +.sp +.ne 2 +.mk +.na +\fB\fBif_nametoindex()\fR\fR +.ad +.RS 22n +.rt +The \fBif_nametoindex()\fR function returns the interface index corresponding +to the interface name pointed to by the \fIifname\fR pointer. If the specified +interface name does not exist, the return value is \fB0\fR, and \fIerrno\fR is +set to \fBENXIO\fR. If there was a system error, such as running out of memory, +the return value is \fB0\fR and \fIerrno\fR is set to the proper value, for +example, \fBENOMEM\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBif_indextoname()\fR\fR +.ad +.RS 22n +.rt +The \fBif_indextoname()\fR function maps an interface index into its +corresponding name. This pointer is also the return value of the function. If +there is no interface corresponding to the specified index, \fBNULL\fR is +returned, and \fIerrno\fR is set to \fBENXIO\fR, if there was a system error, +such as running out of memory, \fBif_indextoname()\fR returns \fBNULL\fR and +\fIerrno\fR would be set to the proper value, for example, \fBENOMEM\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBif_nameindex()\fR\fR +.ad +.RS 22n +.rt +The \fBif_nameindex()\fR function returns an array of \fBif_nameindex\fR +structures, one structure per interface. The \fBif_nameindex\fR structure holds +the information about a single interface and is defined when the +<\fBnet/if.h\fR> header is included: +.sp +.in +2 +.nf +struct if_nameindex + unsigned int if_index; /* 1, 2, ... */ + char *if_name; /* "net0", ... */ +}; +.fi +.in -2 + +While any IPMP IP interfaces are returned by \fBif_nameindex()\fR, the +underlying IP interfaces that comprise each IPMP group are not returned. +.sp +The end of the array of structures is indicated by a structure with an +\fBif_index\fR of 0 and an \fBif_name\fR of \fBNULL\fR. The function returns a +null pointer upon an error and sets \fIerrno\fR to the appropriate value. The +memory used for this array of structures along with the interface names pointed +to by the \fBif_name\fR members is obtained dynamically. This memory is freed +by the \fBif_freenameindex()\fR function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBif_freenameindex()\fR\fR +.ad +.RS 22n +.rt +The \fBif_freenameindex()\fR function frees the dynamic memory that was +allocated by \fBif_nameindex()\fR. The argument to this function must be a +pointer that was returned by \fBif_nameindex()\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBifconfig\fR(1M), \fBif_nametoindex\fR(3XNET), \fBattributes\fR(5), +\fBif\fR(7P) diff --git a/usr/src/man/man3socket/inet.3socket b/usr/src/man/man3socket/inet.3socket new file mode 100644 index 0000000000..beea488f1f --- /dev/null +++ b/usr/src/man/man3socket/inet.3socket @@ -0,0 +1,331 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" 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 inet 3SOCKET "28 Nov 2007" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +inet, inet6, inet_ntop, inet_pton, inet_aton, inet_addr, inet_network, +inet_makeaddr, inet_lnaof, inet_netof, inet_ntoa \- Internet address +manipulation +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR... ] +#include <sys/types.h> +#include <sys/socket.h> +#include <netinet/in.h> +#include <arpa/inet.h> + +\fBconst char *\fR\fBinet_ntop\fR(\fBint\fR \fIaf\fR, \fBconst void *\fR\fIaddr\fR, \fBchar *\fR\fIcp\fR, + \fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBint\fR \fBinet_pton\fR(\fBint\fR \fIaf\fR, \fBconst char *\fR\fIcp\fR, \fBvoid *\fR\fIaddr\fR); +.fi + +.LP +.nf +\fBint\fR \fBinet_aton\fR(\fBconst char *\fR\fIcp\fR, \fBstruct in_addr *\fR\fIaddr\fR); +.fi + +.LP +.nf +\fBin_addr_t\fR \fBinet_addr\fR(\fBconst char *\fR\fIcp\fR); +.fi + +.LP +.nf +\fBin_addr_t\fR \fBinet_network\fR(\fBconst char *\fR\fIcp\fR); +.fi + +.LP +.nf +\fBstruct in_addr\fR \fBinet_makeaddr\fR(\fBconst int\fR \fInet\fR, \fBconst int\fR \fIlna\fR); +.fi + +.LP +.nf +\fBint\fR \fBinet_lnaof\fR(\fBconst struct in_addr\fR \fIin\fR); +.fi + +.LP +.nf +\fBint\fR \fBinet_netof\fR(\fBconst struct in_addr\fR \fIin\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBinet_ntoa\fR(\fBconst struct in_addr\fR \fIin\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBinet_ntop()\fR and \fBinet_pton()\fR functions can manipulate both IPv4 +and IPv6 addresses. The \fBinet_aton()\fR, \fBinet_addr()\fR, +\fBinet_network()\fR, \fBinet_makeaddr()\fR, \fBinet_lnaof()\fR, +\fBinet_netof()\fR, and \fBinet_ntoa()\fR functions can only manipulate IPv4 +addresses. +.sp +.LP +The \fBinet_ntop()\fR function converts a numeric address into a string +suitable for presentation. The \fIaf\fR argument specifies the family of the +address which can be \fBAF_INET\fR or \fBAF_INET6\fR. The \fIaddr\fR argument +points to a buffer that holds an IPv4 address if the \fIaf\fR argument is +\fBAF_INET\fR. The \fIaddr\fR argument points to a buffer that holds an IPv6 +address if the \fIaf\fR argument is \fBAF_INET6\fR. The address must be in +network byte order. The \fIcp\fR argument points to a buffer where the function +stores the resulting string. The application must specify a non-\fINULL\fR +\fIcp\fR argument. The \fIsize\fR argument specifies the size of this buffer. +For IPv6 addresses, the buffer must be at least 46-octets. For IPv4 addresses, +the buffer must be at least 16-octets. To allow applications to easily declare +buffers of the proper size to store IPv4 and IPv6 addresses in string form, the +following two constants are defined in <\fBnetinet/in.h\fR>: +.sp +.in +2 +.nf +#define INET_ADDRSTRLEN 16 +#define INET6_ADDRSTRLEN 46 +.fi +.in -2 + +.sp +.LP +The \fBinet_pton()\fR function converts the standard text presentation form of +a function to the numeric binary form. The \fIaf\fR argument specifies the +family of the address. Currently, the \fBAF_INET\fR and \fBAF_INET6\fR address +families are supported. The \fIcp\fR argument points to the string being passed +in. The \fIaddr\fR argument points to a buffer where the function stores the +numeric address. The calling application must ensure that the buffer referred +to by \fIaddr\fR is large enough to hold the numeric address, at least 4 bytes +for \fBAF_INET\fR or 16 bytes for \fBAF_INET6\fR. +.sp +.LP +The \fBinet_aton()\fR, \fBinet_addr()\fR, and \fBinet_network()\fR functions +interpret character strings that represent numbers expressed in the IPv4 +standard '\fB\&.\fR' notation, returning numbers suitable for use as IPv4 +addresses and IPv4 network numbers, respectively. The \fBinet_makeaddr()\fR +function uses an IPv4 network number and a local network address to construct +an IPv4 address. The \fBinet_netof()\fR and \fBinet_lnaof()\fR functions break +apart IPv4 host addresses, then return the network number and local network +address, respectively. +.sp +.LP +The \fBinet_ntoa()\fR function returns a pointer to a string in the base 256 +notation \fBd.d.d.d\fR. See the following section on IPv4 addresses. +.sp +.LP +Internet addresses are returned in network order, bytes ordered from left to +right. Network numbers and local address parts are returned as machine format +integer values. +.SS "IPv6 Addresses" +.sp +.LP +There are three conventional forms for representing IPv6 addresses as strings: +.RS +4 +.TP +1. +The preferred form is \fBx:x:x:x:x:x:x:x\fR, where the 'x's are the +hexadecimal values of the eight 16-bit pieces of the address. For example: +.sp +.in +2 +.nf +1080:0:0:0:8:800:200C:417A +.fi +.in -2 + +It is not necessary to write the leading zeros in an individual field. There +must be at least one numeral in every field, except when the special syntax +described in the following is used. +.RE +.RS +4 +.TP +2. +It is common for addresses to contain long strings of zero bits in some +methods used to allocate certain IPv6 address styles. A special syntax is +available to compress the zeros. The use of "\fB::\fR" indicates multiple +groups of 16 bits of zeros. The \fB::\fR may only appear once in an address. +The \fB::\fR can also be used to compress the leading and trailing zeros in an +address. For example: +.sp +.in +2 +.nf +1080::8:800:200C:417A +.fi +.in -2 + +.RE +.RS +4 +.TP +3. +The alternative form \fBx:x:x:x:x:x:d.d.d.d\fR is sometimes more convenient +when dealing with a mixed environment of IPv4 and IPv6 nodes. The \fBx\fR's in +this form represent the hexadecimal values of the six high-order 16-bit pieces +of the address. The \fBd\fR's represent the decimal values of the four +low-order 8-bit pieces of the standard IPv4 address. For example: +.sp +.in +2 +.nf +::FFFF:129.144.52.38 +::129.144.52.38 +.fi +.in -2 + +The \fB::FFFF:d.d.d.d\fR and \fB::d.d.d.d\fR pieces are the general forms of an +IPv4-mapped IPv6 address and an IPv4-compatible IPv6 address. +.sp +The IPv4 portion must be in the \fBd.d.d.d\fR form. The following forms are +invalid: +.sp +.in +2 +.nf +::FFFF:d.d.d +::FFFF:d.d +::d.d.d +::d.d +.fi +.in -2 + +The \fB::FFFF:d\fR form is a valid but unconventional representation of the +IPv4-compatible IPv6 address \fB::255.255.0.d\fR. +.sp +The \fB::d\fR form corresponds to the general IPv6 address +\fB0:0:0:0:0:0:0:d\fR. +.RE +.SS "IPv4 Addresses" +.sp +.LP +Values specified using `\fB\&.\fR' notation take one of the following forms: +.sp +.in +2 +.nf +d.d.d.d +d.d.d +d.d +d +.fi +.in -2 + +.sp +.LP +When four parts are specified, each part is interpreted as a byte of data and +assigned from left to right to the four bytes of an IPv4 address. +.sp +.LP +When a three-part address is specified, the last part is interpreted as a +16-bit quantity and placed in the right most two bytes of the network address. +The three part address format is convenient for specifying Class B network +addresses such as \fB128.net.host\fR. +.sp +.LP +When a two-part address is supplied, the last part is interpreted as a 24-bit +quantity and placed in the right most three bytes of the network address. The +two part address format is convenient for specifying Class A network addresses +such as \fBnet.host\fR. +.sp +.LP +When only one part is given, the value is stored directly in the network +address without any byte rearrangement. +.sp +.LP +With the exception of \fBinet_pton()\fR, numbers supplied as \fIparts\fR +in '\fB\&.\fR' notation may be decimal, octal, or hexadecimal, as specified in C +language. For example, a leading \fB0x\fR or \fB0X\fR implies hexadecimal. A +leading \fB0\fR implies octal. Otherwise, the number is interpreted as decimal. +.sp +.LP +For IPv4 addresses, \fBinet_pton()\fR accepts only a string in standard IPv4 +dot notation: +.sp +.in +2 +.nf +d.d.d.d +.fi +.in -2 + +.sp +.LP +Each number has one to three digits with a decimal value between 0 and 255. +.sp +.LP +The \fBinet_addr()\fR function has been obsoleted by \fBinet_aton()\fR. +.SH RETURN VALUES +.sp +.LP +The \fBinet_aton()\fR function returns nonzero if the address is valid, \fB0\fR +if the address is invalid. +.sp +.LP +The \fBinet_ntop()\fR function returns a pointer to the buffer that contains a +string if the conversion succeeds. Otherwise, \fINULL\fR is returned. Upon +failure, \fIerrno\fR is set to \fBEAFNOSUPPORT\fR if the \fIaf\fR argument is +invalid or \fBENOSPC\fR if the size of the result buffer is inadequate. +.sp +.LP +The \fBinet_pton()\fR function returns \fB1\fR if the conversion succeeds, +\fB0\fR if the input is not a valid IPv4 dotted-decimal string or a valid IPv6 +address string. The function returns \fB-1\fR with \fIerrno\fR set to +\fBEAFNOSUPPORT\fR if the af argument is unknown. +.sp +.LP +The value \fBINADDR_NONE\fR, which is equivalent to \fB(in_addr_t)(-1)\fR, is +returned by \fBinet_addr()\fR and \fBinet_network()\fR for malformed requests. +.sp +.LP +The functions \fBinet_netof()\fR and \fBinet_lnaof()\fR break apart IPv4 host +addresses, returning the network number and local network address part, +respectively. +.sp +.LP +The function \fBinet_ntoa()\fR returns a pointer to a string in the base 256 +notation \fBd.d.d.d\fR, described in the section on IPv4 addresses. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilitySee below. +_ +MT-LevelSafe +.TE + +.sp +.LP +The \fBinet_ntop()\fR, \fBinet_pton()\fR, \fBinet_aton()\fR, \fBinet_addr()\fR, +and \fBinet_network()\fR functions are Committed. The \fBinet_lnaof()\fR, +\fBinet_makeaddr()\fR, \fBinet_netof()\fR, and \fBinet_network()\fR functions +are Committed (Obsolete). +.SH SEE ALSO +.sp +.LP +\fBgethostbyname\fR(3NSL), \fBgetipnodebyname\fR(3SOCKET), +\fBgetnetbyname\fR(3SOCKET), \fBinet.h\fR(3HEAD), \fBhosts\fR(4), +\fBnetworks\fR(4), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The return value from \fBinet_ntoa()\fR points to a buffer which is overwritten +on each call. This buffer is implemented as thread-specific data in +multithreaded applications. +.sp +.LP +IPv4-mapped addresses are not recommended. +.SH BUGS +.sp +.LP +The problem of host byte ordering versus network byte ordering is confusing. A +simple way to specify Class C network addresses in a manner similar to that for +Class B and Class A is needed. diff --git a/usr/src/man/man3socket/inet6_opt.3socket b/usr/src/man/man3socket/inet6_opt.3socket new file mode 100644 index 0000000000..eb210d19d2 --- /dev/null +++ b/usr/src/man/man3socket/inet6_opt.3socket @@ -0,0 +1,186 @@ +'\" te +.\" Copyright 2003 AT&T +.\" 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 inet6_opt 3SOCKET "15 Feb 2007" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +inet6_opt, inet6_opt_init, inet6_opt_append, inet6_opt_finish, +inet6_opt_set_val, inet6_opt_next, inet6_opt_find, inet6_opt_get_val \- Option +manipulation mechanism +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR [\fIlibrary...\fR] +#include <netinet/in.h> + +\fBint\fR \fBinet6_opt_init\fR(\fBvoid *\fR\fIextbuf\fR, \fBsocklen_t\fR \fIextlen\fR); +.fi + +.LP +.nf +\fBint\fR \fBinet6_opt_append\fR(\fBvoid *\fR\fIextbuf\fR, \fBsocklen_t\fR \fIextlen\fR, + \fBint\fR \fIoffset\fR, \fBuint8_t\fR \fItype\fR, \fBsocklen_t\fR \fIlen\fR, \fBuint_t\fR \fIalign\fR, + \fBvoid **\fR\fIdatabufp\fR); +.fi + +.LP +.nf +\fBint\fR \fBinet6_opt_finish\fR(\fBvoid *\fR\fIextbuf\fR, \fBsocklen_t\fR \fIextlen\fR, + \fBint\fR \fIoffset\fR); +.fi + +.LP +.nf +\fBint\fR \fBinet6_opt_set_val\fR(\fBvoid *\fR\fIdatabuf\fR, \fBint\fR \fIoffset\fR, + \fBvoid *\fR\fIval\fR, \fBsocklen_t\fR \fIvallen\fR); +.fi + +.LP +.nf +\fBint\fR \fBinet6_opt_next\fR(\fBvoid *\fR\fIextbuf\fR, \fBsocklen_t\fR \fIextlen\fR, + \fBint\fR \fIoffset\fR, \fBuint8_t *\fR\fItypep\fR, \fBsocklen_t *\fR\fIlenp\fR, + \fBvoid **\fR\fIdatabufp\fR); +.fi + +.LP +.nf +\fBint\fR \fBinet6_opt_find\fR(\fBvoid *\fR\fIextbuf\fR, \fBsocklen_t\fR \fIextlen\fR, \fBint\fR \fIoffset\fR, + \fBuint8_t\fR \fItype\fR, \fBsocklen_t *\fR\fIlenp\fR, \fBvoid **\fR\fIdatabufp\fR); +.fi + +.LP +.nf +\fBint\fR\fBinet6_opt_get_val\fR(\fBvoid *\fR\fIdatabuf\fR, \fBint\fR \fIoffset\fR, + \fBvoid *\fR\fIval\fR, \fBsocklen_t *\fR\fIvallen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBinet6_opt\fR functions enable users to manipulate options without having +to know the structure of the option header. +.sp +.LP +The \fBinet6_opt_init()\fR function returns the number of bytes needed for the +empty extension header, that is, without any options. If \fIextbuf\fR is not +\fBNULL\fR, it also initializes the extension header to the correct length +field. If the \fIextlen\fR value is not a positive non-zero multiple of 8, the +function fails and returns \fB-1\fR\&. +.sp +.LP +The \fBinet6_opt_append()\fR function returns the updated total length while +adding an option with length \fBlen\fR and alignment \fBalign\fR. If +\fIextbuf\fR is not \fBNULL\fR, then, in addition to returning the length, the +function inserts any needed Pad option, initializes the option setting the type +and length fields, and returns a pointer to the location for the option content +in \fIdatabufp\fR. If the option does not fit in the extension header buffer, +the function returns \fB-1\fR\&. The \fItype\fR is the 8-bit option type. The +\fIlen\fR is the length of the option data, excluding the option type and +option length fields. Once \fBinet6_opt_append()\fR is called, the application +can use the \fIdatabuf\fR directly, or \fBinet6_opt_set_val()\fR can be used to +specify the content of the option. The option type must have a value from 2 to +255, inclusive. The values 0 and 1 are reserved for the Pad1 and PadN options, +respectively. The option data length must have a value between 0 and 255, +inclusive, and it is the length of the option data that follows. The align +parameter must have a value of 1, 2, 4, or 8. The align value cannot exceed the +value of \fBlen\fR. +.sp +.LP +The \fBinet6_opt_finish()\fR function returns the updated total length the +takes into account the final padding of the extension header to make it a +multiple of 8 bytes. If \fIextbuf\fR is not \fBNULL\fR, the function also +initializes the option by inserting a Pad1 or PadN option of the proper length. +If the necessary pad does not fit in the extension header buffer, the function +returns \fB-1\fR\&. +.sp +.LP +The \fBinet6_opt_set_val()\fR function inserts data items of various sizes in +the data portion of the option. The \fIval\fR parameter should point to the +data to be inserted. The \fIoffset\fR specifies the data portion of the option +in which the value should be inserted. The first byte after the option type and +length is accessed by specifying an \fIoffset\fR of zero. +.sp +.LP +The \fBinet6_opt_next()\fR function parses the received option extension +headers which return the next option. The \fIextbuf\fR and \fIextlen\fR +parameters specify the extension header. The \fIoffset\fR should be zero for +the first option or the length returned by a previous call to either +\fBinet6_opt_next()\fR or \fBinet6_opt_find()\fR. The \fIoffset\fR specifies +where to continue scanning the extension buffer. The subsequent option is +returned by updating \fItypep\fR, \fIlenp\fR, and \fIdatabufp\fR. The +\fItypep\fR argument stores the option type. The \fIlenp\fR argument stores the +length of the option data, excluding the option type and option length fields. +The \fIdatabufp\fR argument points to the data field of the option. +.sp +.LP +The \fBinet6_opt_find()\fR function is similar to the \fBinet6_opt_next()\fR +function. Unlike \fBinet6_opt_next()\fR, the \fBinet6_opt_find()\fR function +enables the caller to specify the option type to be searched for, rather than +returning the next option in the extension header. +.sp +.LP +The \fBinet6_opt_get_val()\fR function extracts data items of various sizes in +the portion of the option. The \fIval\fR argument should point to the +destination for the extracted data. The \fIoffset\fR specifies at which point +in the option's data portion the value should be extracted. The first byte +following the option type and length is accessed by specifying an \fIoffset\fR +of zero. +.SH RETURN VALUES +.sp +.LP +The \fBinet6_opt_init()\fR function returns the number of bytes needed for the +empty extension header. If the \fIextlen\fR value is not a positive non-zero +multiple of 8, the function fails and returns \fB-1\fR\&. +.sp +.LP +The \fBinet6_opt_append()\fR function returns the updated total length. +.sp +.LP +The \fBinet6_opt_finish()\fR function returns the updated total length. +.sp +.LP +The \fBinet6_opt_set_val()\fR function returns the \fIoffset\fR for the +subsequent field. +.sp +.LP +The \fBinet6_opt_next()\fR function returns the updated "previous" length +computed by advancing past the option that was returned. When there are no +additional options or if the option extension header is malformed, the return +value is \fB-1\fR\&. +.sp +.LP +The \fBinet6_opt_find()\fR function returns the updated "previous" total +length. If an option of the specified type is not located, the return value is +\fB-1\fR\&. If the option extension header is malformed, the return value is +\fB-1\fR\&. +.sp +.LP +The \fBinet6_opt_get_val()\fR function returns the \fIoffset\fR for the next +field (that is, \fIoffset\fR + \fIvallen\fR) which can be used when extracting +option content with multiple fields. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +RFC 3542 - \fIAdvanced Sockets Application Programming Interface (API) for +IPv6\fR, The Internet Society. May 2003 diff --git a/usr/src/man/man3socket/inet6_rth.3socket b/usr/src/man/man3socket/inet6_rth.3socket new file mode 100644 index 0000000000..6d09f4a6f2 --- /dev/null +++ b/usr/src/man/man3socket/inet6_rth.3socket @@ -0,0 +1,190 @@ +'\" te +.\" Copyright 2003 AT&T +.\" 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 inet6_rth 3SOCKET "15 Feb 2007" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +inet6_rth, inet6_rth_space, inet6_rth_init, inet6_rth_add, inet6_rth_reverse, +inet6_rth_segments, inet6_rth_getaddr \- Routing header manipulation +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR [\fIlibrary\fR] +#include <netinet/in.h> + +\fBsocklen_t\fR \fBinet6_rth_space\fR(\fBint\fR \fItype\fR, \fBint\fR \fIsegments\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBinet6_rth_init\fR(\fBvoid *\fR\fIbp\fR, \fBsocklen_t\fR \fIbp_len\fR, \fBint\fR \fItype\fR, \fBint\fR \fIsegments\fR); +.fi + +.LP +.nf +\fBint\fR \fBinet6_rth_add\fR(\fBvoid *\fR\fIbp\fR, \fBconst\fR \fIstruct\fR, \fBin6_addr *\fR\fIaddr\fR); +.fi + +.LP +.nf +\fBint\fR \fBinet6_rth_reverse\fR(\fBconst void *\fR\fIin\fR, \fBvoid *\fR\fIout\fR); +.fi + +.LP +.nf +\fBint\fR \fBinet6_rth_segments\fR(\fBconst void *\fR\fIbp\fR); +.fi + +.LP +.nf +\fBstruct in6_addr *\fR\fBinet6_rth_getaddr\fR(\fBconst void *\fR\fIbp\fR, \fBint\fR \fIindex\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBinet6_rth\fR functions enable users to manipulate routing headers +without having knowledge of their structure. +.sp +.LP +The \fBiet6_rth_init()\fR function initializes the buffer pointed to by +\fIbp\fR to contain a routing header of the specified type and sets +\fBip6r_len\fR based on the segments parameter. The \fIbp_len\fR argument is +used only to verify that the buffer is large enough. The \fBip6r_segleft\fR +field is set to zero and \fBinet6_rth_add()\fR increments it. The caller +allocates the buffer and its size can be determined by calling +\fBinet6_rth_space()\fR. +.sp +.LP +The \fBinet6_rth_add()\fR function adds the IPv6 address pointed to by +\fIaddr\fR to the end of the routing header that is being constructed. +.sp +.LP +The \fBinet6_rth_reverse()\fR function takes a routing header extension header +pointed to by the first argument and writes a new routing header that sends +datagrams along the reverse of the route. The function reverses the order of +the addresses and sets the \fBsegleft\fR member in the new routing header to +the number of segments. Both arguments can point to the same buffer (that is, +the reversal can occur in place). +.sp +.LP +The \fBinet6_rth_segments()\fR function returns the number of segments +(addresses) contained in the routing header described by \fIbp\fR. +.sp +.LP +The \fBinet6_rth_getaddr()\fR function returns a pointer to the IPv6 address +specified by index, which must have a value between 0 and one less than the +value returned by \fBinet6_rth_segments()\fR in the routing header described by +\fIbp\fR. Applications should first call \fBinet6_rth_segments()\fR to obtain +the number of segments in the routing header. +.sp +.LP +The \fBinet6_rth_space()\fR function returns the size, but the function does +not allocate the space required for the ancillary data routing header. +.SH ROUTING HEADERS +.sp +.LP +To receive a routing header, the application must enable the +\fBIPV6_RECVRTHDR\fR socket option: +.sp +.in +2 +.nf +int on = 1; +setsockopt (fd, IPPROTO_IPV6, IPV6_RECVRTHDR, &on, sizeof(on)); +.fi +.in -2 + +.sp +.LP +Each received routing header is returned as one ancillary data object described +by a \fBcmsghdr\fR structure with \fBcmsg_type\fR set to \fBIPV6_RTHDR\fR. +.sp +.LP +To send a routing header, the application specifies it either as ancillary data +in a call to \fBsendmsg()\fR or by using \fBsetsockopt()\fR. For the sending +side, this \fBAPI\fR assumes the number of occurrences of the routing header as +described in \fIRFC-2460\fR. Applications can specify no more than one outgoing +routing header. +.sp +.LP +The application can remove any sticky routing header by calling +\fBsetsockopt()\fR for \fBIPV6_RTHDR\fR with a zero option length. +.sp +.LP +When using ancillary data, a routing header is passed between the application +and the kernel as follows: The \fBcmsg_level\fR member has a value of +\fBIPPROTO_IPV6\fR and the \fBcmsg_type\fR member has a value of +\fBIPV6_RTHDR\fR. The contents of the \fBcmsg_data\fR member is +implementation-dependent and should not be accessed directly by the +application, but should be accessed using the \fBinet6_rth\fR functions. +.sp +.LP +The following constant is defined as a result of including the +<\fBnetinet/in.h\fR>: +.sp +.in +2 +.nf +#define IPV6_RTHDR_TYPE_0 0 /* IPv6 Routing header type 0 */ +.fi +.in -2 + +.SS "ROUTING HEADER OPTION" +.sp +.LP +Source routing in IPv6 is accomplished by specifying a routing header as an +extension header. There are a number of different routing headers, but IPv6 +currently defines only the Type 0 header. See \fIRFC-2460\fR. The Type 0 header +supports up to 127 intermediate nodes, limited by the length field in the +extension header. With this maximum number of intermediate nodes, a source, and +a destination, there are 128 hops. +.SH RETURN VALUES +.sp +.LP +The \fBinet6_rth_init()\fR function returns a pointer to the buffer (\fIbp\fR) +upon success. +.sp +.LP +For the \fBinet6_rth_add()\fR function, the \fBsegleft\fR member of the routing +header is updated to account for the new address in the routing header. The +function returns \fB0\fR upon success and \fB-1\fR upon failure. +.sp +.LP +The \fBinet6_rth_reverse()\fR function returns \fB0\fR upon success or \fB-1\fR +upon an error. +.sp +.LP +The \fBinet6_rth_segments()\fR function returns \fB0\fR or greater upon success +and \fB-1\fR upon an error. +.sp +.LP +The \fBinet6_rth_getaddr()\fR function returns \fBNULL\fR upon an error. +.sp +.LP +The \fBinet6_rth_space()\fR function returns the size of the buffer needed for +the routing header. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityStandard +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +RFC 3542- \fIAdvanced Sockets Application Programming Interface (API) for +IPv6\fR, The Internet Society. May 2003 diff --git a/usr/src/man/man3socket/listen.3socket b/usr/src/man/man3socket/listen.3socket new file mode 100644 index 0000000000..5546f5c138 --- /dev/null +++ b/usr/src/man/man3socket/listen.3socket @@ -0,0 +1,107 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (C) 1999, 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 listen 3SOCKET "8 Nov 1999" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +listen \- listen for connections on a socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ] +#include <sys/types.h> +#include <sys/socket.h> + +\fBint\fR \fBlisten\fR(\fBint\fR \fIs\fR, \fBint\fR \fIbacklog\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +To accept connections, a socket is first created with \fBsocket\fR(3SOCKET), a +backlog for incoming connections is specified with \fBlisten()\fR and then the +connections are accepted with \fBaccept\fR(3SOCKET). The \fBlisten()\fR call +applies only to sockets of type \fBSOCK_STREAM\fR or \fBSOCK_SEQPACKET\fR. +.sp +.LP +The \fIbacklog\fR parameter defines the maximum length the queue of pending +connections may grow to. +.sp +.LP +If a connection request arrives with the queue full, the client will receive an +error with an indication of \fBECONNREFUSED\fR for \fBAF_UNIX\fR sockets. If +the underlying protocol supports retransmission, the connection request may be +ignored so that retries may succeed. For \fBAF_INET\fR and +\fBAF_INET6\fRsockets, the \fBTCP\fR will retry the connection. If the +\fIbacklog\fR is not cleared by the time the tcp times out, the connect will +fail with \fBETIMEDOUT\fR. +.SH RETURN VALUES +.sp +.LP +A \fB0\fR return value indicates success; \fB\(mi1\fR indicates an error. +.SH ERRORS +.sp +.LP +The call fails if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 14n +.rt +The argument \fIs\fR is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 14n +.rt +The argument \fIs\fR is not a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 14n +.rt +The socket is not of a type that supports the operation \fBlisten()\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBaccept\fR(3SOCKET), \fBconnect\fR(3SOCKET), \fBsocket\fR(3SOCKET), +\fBattributes\fR(5), \fBsocket.h\fR(3HEAD) +.SH NOTES +.sp +.LP +There is currently no \fIbacklog\fR limit. diff --git a/usr/src/man/man3socket/rcmd.3socket b/usr/src/man/man3socket/rcmd.3socket new file mode 100644 index 0000000000..266dc6e2b5 --- /dev/null +++ b/usr/src/man/man3socket/rcmd.3socket @@ -0,0 +1,178 @@ +'\" te +.\" Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. +.\" Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved +.TH rcmd 3SOCKET "10 Feb 2004" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +rcmd, rcmd_af, rresvport, rresvport_af, ruserok \- routines for returning a +stream to a remote command +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR... ] +#include <netdb.h> +#include <unistd.h> + +\fBint\fR \fBrcmd\fR(\fBchar **\fR\fIahost\fR, \fBunsigned short\fR \fIinport\fR, \fBconst char *\fR\fIluser\fR, + \fBconst char *\fR\fIruser\fR, \fBconst char *\fR\fIcmd\fR, \fBint *\fR\fIfd2p\fR); +.fi + +.LP +.nf +\fBint\fR \fBrcmd_af\fR(\fBchar **\fR\fIahost\fR, \fBunsigned short\fR \fIinport\fR, \fBconst char *\fR\fIluser\fR, + \fBconst char *\fR\fIruser\fR, \fBconst char *\fR\fIcmd\fR, \fBint *\fR\fIfd2p\fR, \fBint\fR \fIaf\fR); +.fi + +.LP +.nf +\fBint\fR \fBrresvport\fR(\fBint *\fR\fIport\fR); +.fi + +.LP +.nf +\fBint\fR \fBrresvport_af\fR(\fBint *\fR\fIport\fR, \fBint\fR \fIaf\fR); +.fi + +.LP +.nf +\fBint\fR \fBruserok\fR(\fBconst char *\fR\fIrhost\fR, \fBint\fR \fIsuser\fR, \fBconst char *\fR\fIruser\fR, + \fBconst char *\fR\fIluser\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBrcmd()\fR function is used by the superuser to execute a command on a +remote machine with an authentication scheme based on reserved port numbers. An +\fBAF_INET\fR socket is returned with \fBrcmd()\fR. The \fBrcmd_af()\fR +function supports \fBAF_INET\fR, \fBAF_INET6\fR or \fBAF_UNSPEC\fR for the +address family. An application can choose which type of socket is returned by +passing \fBAF_INET\fR or \fBAF_INET6\fR as the address family. The use of +\fBAF_UNSPEC\fR means that the caller will accept any address family. Choosing +\fBAF_UNSPEC\fR provides a socket that best suits the connectivity to the +remote host. +.sp +.LP +The \fBrresvport()\fR function returns a descriptor to a socket with an address +in the privileged port space. The \fBrresvport_af()\fR function is the +equivalent to \fBrresvport()\fR, except that you can choose \fBAF_INET\fR or +\fBAF_INET6\fR as the socket address family to be returned by +\fBrresvport_af()\fR. \fBAF_UNSPEC\fR does not apply to the \fBrresvport()\fR +function. +.sp +.LP +The \fBruserok()\fR function is a routine used by servers to authenticate +clients that request as service with \fBrcmd\fR. +.sp +.LP +All of these functions are present in the same file and are used by the +\fBin.rshd\fR(1M) server among others. +.sp +.LP +The \fBrcmd()\fR and \fBrcmd_af()\fR functions look up the host \fI*ahost\fR +using \fBgetaddrinfo\fR(3SOCKET) and return \fB\(mi1\fR if the host does not +exist. Otherwise, *\fIahost\fR is set to the standard name of the host and a +connection is established to a server residing at the Internet port +\fIinport\fR. +.sp +.LP +If the connection succeeds, a socket in the Internet domain of type +\fBSOCK_STREAM\fR is returned to the caller. The socket is given to the remote +command as standard input (file descriptor 0) and standard output (file +descriptor 1). If \fIfd2p\fR is non-zero, an auxiliary channel to a control +process is set up and a descriptor for it is placed in \fI*fd2p\fR. The control +process returns diagnostic output file (descriptor 2) from the command on the +auxiliary channel. The control process also accepts bytes on this channel as +signal numbers to be forwarded to the process group of the command. If +\fIfd2p\fR is 0, the standard error (file descriptor 2) of the remote command +is made the same as its standard output. No provision is made for sending +arbitrary signals to the remote process, other than possibly sending +out-of-band data. +.sp +.LP +The protocol is described in detail in \fBin.rshd\fR(1M). +.sp +.LP +The \fBrresvport()\fR and \fBrresvport_af()\fR functions are used to obtain a +socket bound to a privileged port number. The socket is suitable for use by +\fBrcmd()\fR and \fBrresvport_af()\fR and several other routines. Privileged +Internet ports are those in the range 1 to 1023. Only the superuser is allowed +to bind a socket to a privileged port number. The application must pass in +\fIport\fR, which must be in the range 512 to 1023. The system first tries to +bind to that port number. If it fails, the system then tries to bind to +another unused privileged port, if one is available. +.sp +.LP +The \fBruserok()\fR function takes a remote host name returned by the +\fBgethostbyaddr()\fR function with two user names and a flag to indicate +whether the local user's name is that of the superuser. See +\fBgethostbyname\fR(3NSL). The \fBruserok()\fR function then checks the files +\fB/etc/hosts.equiv\fR and possibly \fB\&.rhosts\fR in the local user's home +directory to see if the request for service is allowed. A \fB0\fR value is +returned if the machine name is listed in the \fB/etc/hosts.equiv\fR file, or +if the host and remote user name are found in the \fB\&.rhosts\fR file. +Otherwise, the \fBruserok()\fR function returns \fB\(mi1\fR\&. If the superuser +flag is \fB1\fR, the \fB/etc/hosts.equiv\fR is not checked. +.sp +.LP +The error code \fBEAGAIN\fR is overloaded to mean "All network ports in use." +.SH RETURN VALUES +.sp +.LP +The \fBrcmd()\fR and \fBrcmd_af()\fR functions return a valid socket descriptor +upon success. The functions returns \fB\(mi1\fR upon error and print a +diagnostic message to standard error. +.sp +.LP +The \fBrresvport()\fR and \fBrresvport_af()\fR functions return a valid, bound +socket descriptor upon success. The functions return \fB\(mi1\fR upon error +with the global value \fIerrno\fR set according to the reason for failure. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/etc/hosts.equiv\fR\fR +.ad +.RS 20n +.rt +system trusted hosts and users +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB~/.rhosts\fR\fR +.ad +.RS 20n +.rt +user's trusted hosts and users +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +.TE + +.sp +.LP +This interface is Unsafe in multithreaded applications. Unsafe interfaces +should be called only from the main thread. +.SH SEE ALSO +.sp +.LP +\fBrlogin\fR(1), \fBrsh\fR(1), \fBin.rexecd\fR(1M), \fBin.rshd\fR(1M), +\fBIntro\fR(2), \fBgetaddrinfo\fR(3SOCKET), \fBgethostbyname\fR(3NSL), +\fBrexec\fR(3SOCKET), \fBattributes\fR(5) diff --git a/usr/src/man/man3socket/recv.3socket b/usr/src/man/man3socket/recv.3socket new file mode 100644 index 0000000000..5ca6d02529 --- /dev/null +++ b/usr/src/man/man3socket/recv.3socket @@ -0,0 +1,320 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (C) 2006, 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 recv 3SOCKET "20 Aug 2007" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +recv, recvfrom, recvmsg \- receive a message from a socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR... ] +#include <sys/types.h> +#include <sys/socket.h> +#include <sys/uio.h> + +\fBssize_t\fR \fBrecv\fR(\fBint\fR \fIs\fR, \fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBssize_t\fR \fBrecvfrom\fR(\fBint\fR \fIs\fR, \fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIflags\fR, + \fBstruct sockaddr *\fR\fIfrom\fR, \fBsocklen_t *\fR\fIfromlen\fR); +.fi + +.LP +.nf +\fBssize_t\fR \fBrecvmsg\fR(\fBint\fR \fIs\fR, \fBstruct msghdr *\fR\fImsg\fR, \fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBrecv()\fR, \fBrecvfrom()\fR, and \fBrecvmsg()\fR functions are used to +receive messages from another socket. The \fIs\fR socket is created with +\fBsocket\fR(3SOCKET). +.sp +.LP +If \fIfrom\fR is a non-\fBNULL\fR pointer, the source address of the message is +filled in. The value-result parameter \fIfromlen\fR is initialized to the size +of the buffer associated with \fIfrom\fR and modified on return to indicate the +actual size of the address stored in the buffer. The length of the message is +returned. If a message is too long to fit in the supplied buffer, excess bytes +may be discarded depending on the type of socket from which the message is +received. See \fBsocket\fR(3SOCKET). +.sp +.LP +If no messages are available at the socket, the receive call waits for a +message to arrive. If the socket is non-blocking, \fB-1\fR is returned with the +external variable \fBerrno\fR set to \fBEWOULDBLOCK\fR. See \fBfcntl\fR(2). +.sp +.LP +For processes on the same host, \fBrecvmsg()\fR can be used to receive a file +descriptor from another process, but it cannot receive ancillary data. See +\fBlibxnet\fR(3LIB). +.sp +.LP +If a zero-length buffer is specified for a message, an EOF condition results +that is indistinguishable from the successful transfer of a file descriptor. +For that reason, one or more bytes of data should be provided when +\fBrecvmsg()\fR passes a file descriptor. +.sp +.LP +The \fBselect\fR(3C) call can be used to determine when more data arrives. +.sp +.LP +The \fIflags\fR parameter is formed by an \fBOR\fR operation on one or more of +the following: +.sp +.ne 2 +.mk +.na +\fB\fBMSG_OOB\fR\fR +.ad +.RS 16n +.rt +Read any \fBout-of-band\fR data present on the socket rather than the regular +\fBin-band\fR data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMSG_PEEK\fR\fR +.ad +.RS 16n +.rt +Peek at the data present on the socket. The data is returned, but not consumed +to allow a subsequent receive operation to see the same data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMSG_WAITALL\fR\fR +.ad +.RS 16n +.rt +Messages are blocked until the full amount of data requested is returned. The +\fBrecv()\fR function can return a smaller amount of data if a signal is +caught, the connection is terminated, \fBMSG_PEEK\fR is specified, or if an +error is pending for the socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMSG_DONTWAIT\fR\fR +.ad +.RS 16n +.rt +Pending messages received on the connection are returned. If data is +unavailable, the function does not block. This behavior is the equivalent to +specifying \fBO_NONBLOCK\fR on the file descriptor of a socket, except that +write requests are unaffected. +.RE + +.sp +.LP +The \fBrecvmsg()\fR function call uses a \fBmsghdr\fR structure defined in +<\fBsys/socket.h\fR> to minimize the number of directly supplied parameters. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions return the number of bytes +received. Otherwise, they return \fB-1\fR and set \fBerrno\fR to indicate the +error. +.SH ERRORS +.sp +.LP +The \fBrecv()\fR, \fBrecvfrom()\fR, and \fBrecvmsg()\fR functions return errors +under the following conditions: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 16n +.rt +The \fIs\fR file descriptor is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The \fBMSG_OOB\fR flag is set and no out-of-band data is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 16n +.rt +The operation is interrupted by the delivery of a signal before any data is +available to be received. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 16n +.rt +An I/O error occurs while reading from or writing to the file system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 16n +.rt +Insufficient user memory is available to complete operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 16n +.rt +Insufficient \fBSTREAMS\fR resources are available for the operation to +complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 16n +.rt +\fIs\fR is not a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESTALE\fR\fR +.ad +.RS 16n +.rt +A stale NFS file handle exists. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEWOULDBLOCK\fR\fR +.ad +.RS 16n +.rt +The socket is marked non-blocking and the requested operation would block. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECONNREFUSED\fR\fR +.ad +.RS 16n +.rt +The requested connection was refused by the peer. For connected IPv4 and IPv6 +datagram sockets, this indicates that the system received an \fBICMP +Destination Port Unreachable\fR message from the peer. +.RE + +.sp +.LP +The \fBrecv()\fR and \fBrecvfrom()\fR functions fail under the following +conditions: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIlen\fR argument overflows a \fBssize_t\fR. +.RE + +.sp +.LP +The \fBrecvmsg()\fR function returns errors under the following conditions: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fBmsg_iovlen\fR member of the \fBmsghdr\fR structure pointed to by +\fImsg\fR is less than or equal to \fB0\fR, or greater than \fB[IOV_MAX}\fR. +See \fBIntro\fR(2) for a definition of \fB[IOV_MAX}\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +One of the \fIiov_len\fR values in the \fBmsg_iov\fR array member of the +\fBmsghdr\fR structure pointed to by \fImsg\fR is negative, or the sum of the +\fIiov_len\fR values in the \fBmsg_iov\fR array overflows a \fBssize_t\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfcntl\fR(2), \fBioctl\fR(2), \fBread\fR(2), \fBconnect\fR(3SOCKET), +\fBgetsockopt\fR(3SOCKET), \fBlibxnet\fR(3LIB), \fBselect\fR(3C), +\fBsend\fR(3SOCKET), \fBsocket\fR(3SOCKET), \fBsocket.h\fR(3HEAD), +\fBattributes\fR(5) diff --git a/usr/src/man/man3socket/rexec.3socket b/usr/src/man/man3socket/rexec.3socket new file mode 100644 index 0000000000..1c34c3fe6d --- /dev/null +++ b/usr/src/man/man3socket/rexec.3socket @@ -0,0 +1,111 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (C) 2004, 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 rexec 3SOCKET "10 Feb 2004" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +rexec, rexec_af \- return stream to a remote command +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR... ] +#include <netdb.h> +#include <unistd.h> + +\fBint\fR \fBrexec\fR(\fBchar **\fR\fIahost\fR, \fBunsigned short\fR \fIinport\fR, \fBconst char *\fR\fIuser\fR, + \fBconst char *\fR\fIpasswd\fR, \fBconst char *\fR\fIcmd\fR, \fBint *\fR\fIfd2p\fR); +.fi + +.LP +.nf +\fBint\fR \fBrexec_af\fR(\fBchar **\fR\fIahost\fR, \fBunsigned short\fR \fIinport\fR, \fBconst char *\fR\fIuser\fR, + \fBconst char *\fR\fIpasswd\fR, \fBconst char *\fR\fIcmd\fR, \fBint *\fR\fIfd2p\fR, \fBint\fR \fIaf\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBrexec()\fR and \fBrexec_af()\fR functions look up the host \fIahost\fR +using \fBgetaddrinfo\fR(3SOCKET) and return \fB\(mi1\fR if the host does not +exist. Otherwise \fIahost\fR is set to the standard name of the host. The +username and password are used in remote host authentication. When a username +and password are not specified, the \fB\&.netrc\fR file in the user's home +directory is searched for the appropriate information. If the search fails, the +user is prompted for the information. +.sp +.LP +The \fBrexec()\fR function always returns a socket of the \fBAF_INET\fR address +family. The \fBrexec_af()\fR function supports \fBAF_INET\fR, \fBAF_INET6\fR, +or \fBAF_UNSPEC\fR for the address family. An application can choose which type +of socket is returned by passing \fBAF_INET\fR or \fBAF_INET6\fR as the address +family. The use of \fBAF_UNSPEC\fR means that the caller will accept any +address family. Choosing \fBAF_UNSPEC\fR provides a socket that best suits the +connectivity to the remote host. +.sp +.LP +The port \fIinport\fR specifies which \fBDARPA\fR Internet port to use for the +connection. The port number used must be in network byte order, as supplied by +a call to \fBhtons\fR(3XNET). The protocol for connection is described in +detail in \fBin.rexecd\fR(1M). +.sp +.LP +If the call succeeds, a socket of type \fBSOCK_STREAM\fR is returned to the +caller, and given to the remote command as its standard input and standard +output. If \fIfd2p\fR is non-zero, an auxiliary channel to a control process is +set up and a file descriptor for it is placed in *\fIfd2p\fR. The control +process returns diagnostic output (file descriptor 2), from the command on the +auxiliary channel. The control process also accepts bytes on this channel as +signal numbers to be forwarded to the process group of the command. If +\fIfd2p\fR is 0, the standard error (file descriptor 2) of the remote command +is made the same as its standard output. No provision is made for sending +arbitrary signals to the remote process, other than possibly sending +out-of-band data. +.sp +.LP +There is no way to specify options to the \fBsocket()\fR call made by the +\fBrexec()\fR or \fBrexec_af()\fRfunctions. +.SH RETURN VALUES +.sp +.LP +If \fBrexec()\fR succeeds, a file descriptor number is returned of the socket +type \fBSOCK_STREAM\fR and the address family \fBAF_INET\fR. The parameter +*\fIahost\fR is set to the standard name of the host. If the value of +\fIfd2p\fR is other than \fBNULL\fR, a file descriptor number is placed in +*\fIfd2p\fR which represents the standard error stream of the command. +.sp +.LP +If \fBrexec_af()\fR succeeds, the routine returns a file descriptor number of +the socket type \fBSOCK_STREAM\fR in the address family \fBAF_INET\fR or +\fBAF_INET6\fR, as determined by the value of the \fIaf\fR parameter. +.sp +.LP +If either \fBrexec()\fR or \fBrexec_af()\fR fails, \fB\(mi1\fR is returned. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +.TE + +.sp +.LP +This interface is Unsafe in multithreaded applications. Unsafe interfaces +should be called only from the main thread. +.SH SEE ALSO +.sp +.LP +\fBin.rexecd\fR(1M), \fBgetaddrinfo\fR(3SOCKET), \fBgethostbyname\fR(3NSL), +\fBgetservbyname\fR(3SOCKET), \fBhtonl\fR(3XNET), \fBsocket\fR(3SOCKET), +\fBattributes\fR(5) diff --git a/usr/src/man/man3socket/sctp_bindx.3socket b/usr/src/man/man3socket/sctp_bindx.3socket new file mode 100644 index 0000000000..b2a0c39743 --- /dev/null +++ b/usr/src/man/man3socket/sctp_bindx.3socket @@ -0,0 +1,169 @@ +'\" te +.\" 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 sctp_bindx 3SOCKET "22 Aug 2007" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +sctp_bindx \- add or remove IP addresses to or from an SCTP socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR \fB -lsctp \fR [ \fIlibrary\fR... ] +#include <sys/types.h> +#include <sys/socket.h> +#include <netinet/sctp.h> + +\fBint\fR \fBsctp_bindx\fR(\fBint\fR \fIsock\fR, \fBvoid *\fR\fIaddrs\fR, \fBint\fR \fIaddrcnt\fR, \fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsctp_bindx()\fR function adds or removes addresses to or from an SCTP +socket. If \fIsock\fR is an Internet Protocol Version 4 (IPv4) socket, +\fIaddrs\fR should be an array of \fBsockaddr_in\fR structures containing IPv4 +addresses. If \fIsock\fR is an Internet Protocol Version 6 (IPv6) socket, +\fIaddrs\fR should be an array of \fBsockaddr_in6\fR structures containing IPv6 +or IPv4-mapped IPv6 addresses. The \fIaddrcnt\fR is the number of array +elements in \fIaddrs\fR. The family of the address type is used with +\fIaddrcnt\fR to determine the size of the array. +.sp +.LP +The \fIflags\fR parameter is a bitmask that indicates whether addresses are to +be added or removed from a socket. The \fIflags\fR parameter is formed by +bitwise OR of zero or more of the following flags: +.sp +.ne 2 +.mk +.na +\fB\fBSCTP_BINDX_ADD_ADDR\fR\fR +.ad +.RS 23n +.rt +Indicates that addresses from \fIaddrs\fR should be added to the SCTP socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCTP_BINDX_REM_ADDR\fR\fR +.ad +.RS 23n +.rt +Indicates that addresses from \fIaddrs\fR should be removed from the SCTP +socket. +.RE + +.sp +.LP +These two flags are mutually exclusive. If \fIflags\fR is formed by a bitwise +OR of both \fBSCTP_BINDX_ADD_ADDR\fR and \fBSCTP_BINDX_REM_ADDR\fR, the +\fBsctp_bindx()\fR function will fail. +.sp +.LP +Prior to calling \fBsctp_bindx()\fR on an SCTP endpoint, the endpoint should be +bound using \fBbind\fR(3SOCKET). On a listening socket, a special +\fBINADDR_ANY\fR value for IP or an unspecified address of all zeros for IPv6 +can be used in \fIaddrs\fR to add all IPv4 or IPv6 addresses on the system to +the socket. The \fBsctp_bindx()\fR function can also be used to add or remove +addresses to or from an established association. In such a case, messages are +exchanged between the SCTP endpoints to update the address lists for that +association if both endpoints support dynamic address reconfiguration. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBsctp_bindx()\fR function returns \fB0\fR. +Otherwise, the function returns \fB-1\fR and sets \fBerrno\fR to indicate the +error. +.SH ERRORS +.sp +.LP +The \fBsctp_bindx()\fR call fails under the following conditions. +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 12n +.rt +The \fIsock\fR argument is an invalid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 12n +.rt +The \fIsock\fR argument is not a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 12n +.rt +One or more of the IPv4 or IPv6 addresses is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 12n +.rt +The endpoint is not bound. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 12n +.rt +The last address is requested to be removed from an established association. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBbind\fR(3SOCKET), \fBin.h\fR(3HEAD), \fBlibsctp\fR(3LIB), +\fBlisten\fR(3SOCKET), \fBsctp_freeladdrs\fR(3SOCKET), +\fBsctp_freepaddrs\fR(3SOCKET), \fBsctp_getladdrs\fR(3SOCKET), +\fBsctp_getpaddrs\fR(3SOCKET), \fBsocket\fR(3SOCKET), \fBinet\fR(7P), +\fBinet6\fR(7P), \fBip\fR(7P), \fBip6\fR(7P), \fBsctp\fR(7P) +.SH NOTES +.sp +.LP +IPv4-mapped addresses are not recommended. diff --git a/usr/src/man/man3socket/sctp_getladdrs.3socket b/usr/src/man/man3socket/sctp_getladdrs.3socket new file mode 100644 index 0000000000..a5c5234023 --- /dev/null +++ b/usr/src/man/man3socket/sctp_getladdrs.3socket @@ -0,0 +1,133 @@ +'\" te +.\" Copyright (c) 2008, 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 sctp_getladdrs 3SOCKET "23 Jan 2008" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +sctp_getladdrs, sctp_freeladdrs \- returns all locally bound addresses on an +SCTP socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR \fB -lsctp \fR [ \fIlibrary\fR... ] +#include <sys/types.h> +#include <sys/socket.h> +#include <netinet/sctp.h> + +\fBint\fR \fBsctp_getladdrs\fR(\fBint\fR \fIsock\fR, \fBsctp_assoc_t\fR \fIid\fR, \fBvoid **\fR\fIaddrs\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsctp_freeladdrs\fR(\fBvoid *\fR\fIaddrs\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsctp_getladdrs()\fR function queries addresses to which an SCTP socket +is bound. The \fBsctp_freeladdrs()\fR function releases resources that are +allocated to hold the addresses. +.sp +.LP +The \fBsctp_getladdrs()\fR function returns all the locally bound addresses on +the SCTP socket \fIsock\fR. On completion \fIaddrs\fR points to a dynamically +allocated array of \fBsockaddr_in\fR structures for an Internet Protocol (IPv4) +socket or an array of \fBsockaddr_in6\fR structures for an Internet Protocol +Version 6 (IPv6) socket. The \fIaddrs\fR parameter must not be \fINULL\fR. For +an IPv4 SCTP socket, the addresses returned in the \fBsockaddr_in\fR structures +are IPv4 addresses. For an IPv6 SCTP socket, the addresses in the +\fBsockaddr_in6\fR structures can be IPv6 addresses or IPv4-mapped IPv6 +addresses. +.sp +.LP +If \fIsock\fR is a one-to-many style SCTP socket, \fIid\fR specifies the +association of interest. A value of \fB0\fR to \fIid\fR returns locally-bound +addresses regardless of a particular association. If \fIsock\fR is a one-to-one +style SCTP socket, \fIid\fR is ignored. +.sp +.LP +The \fBsctp_freeladdrs()\fR function frees the resources allocated by +\fBsctp_getladdrs()\fR. The \fIaddrs\fR parameter is the array of addresses +allocated by \fBsctp_getladdrs()\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBsctp_getladdrs()\fR function returns the +number of addresses in the \fIaddrs\fR array. Otherwise, the function returns +\fB-1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsctp_getladdrs()\fR call fails under the following conditions. +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 12n +.rt +The \fIsock\fR argument is an invalid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 12n +.rt +The \fIsock\fR argument is not a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 12n +.rt +The \fIaddrs\fR argument is \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 12n +.rt +The \fIid\fR argument is an invalid socket. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBbind\fR(3SOCKET), \fBin.h\fR(3HEAD), \fBlibsctp\fR(3LIB), +\fBsctp_freepaddrs\fR(3SOCKET), \fBsctp_getpaddrs\fR(3SOCKET), +\fBsocket\fR(3SOCKET), \fBattributes\fR(5), \fBinet\fR(7P), \fBinet6\fR(7P), +\fBip\fR(7P), \fBip6\fR(7P), \fBsctp\fR(7P) diff --git a/usr/src/man/man3socket/sctp_getpaddrs.3socket b/usr/src/man/man3socket/sctp_getpaddrs.3socket new file mode 100644 index 0000000000..f3deaa5ef6 --- /dev/null +++ b/usr/src/man/man3socket/sctp_getpaddrs.3socket @@ -0,0 +1,145 @@ +'\" te +.\" Copyright (c) 2008, 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 sctp_getpaddrs 3SOCKET "23 Jan 2008" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +sctp_getpaddrs, sctp_freepaddrs \- returns all peer addresses on an SCTP +association +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR \fB -lsctp \fR [ \fIlibrary\fR... ] +#include <sys/types.h> +#include <sys/socket.h> +#include <netinet/sctp.h> + +\fBint\fR \fBsctp_getpaddrs\fR(\fBint\fR \fIsock\fR, \fBsctp_assoc_t\fR \fIid\fR, \fBvoid **\fR\fIaddrs\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsctp_freepaddrs\fR(\fBvoid *\fR\fIaddrs\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsctp_getpaddrs()\fR queries the peer addresses in an SCTP association. +The \fBsctp_freepaddrs()\fR function releases resources that are allocated to +hold the addresses. +.sp +.LP +The \fBsctp_getpaddrs()\fR function returns all the peer addresses in the SCTP +association identified by \fIsock\fR. On completion \fIaddrs\fR points to a +dynamically allocated array of \fBsockaddr_in\fR structures for an Internet +Protocol (IPv4) socket or an array of \fBsockaddr_in6\fR structures for an +Internet Protocol Version 6 (IPv6) socket. The \fIaddrs\fR parameter must not +be \fINULL\fR. For an IPv4 SCTP socket, the addresses returned in the +\fBsockaddr_in\fR structures are IPv4 addresses. For an IPv6 SCTP socket, the +addresses in the \fBsockaddr_in6\fR structures can be IPv6 addresses or +IPv4-mapped IPv6 addresses. +.sp +.LP +If \fIsock\fR is a one-to-many style SCTP socket, \fIid\fR specifies the +association of interest. If \fIsock\fR is a one-to-one style SCTP socket, +\fIid\fR is ignored. +.sp +.LP +The \fBsctp_freepaddrs()\fR function frees the resources allocated by +\fBsctp_getpaddrs()\fR. The \fIaddrs\fR parameter is the array of addresses +allocated by \fBsctp_getpaddrs()\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBsctp_getpaddrs()\fR function returns the +number of addresses in the \fIaddrs\fR array. Otherwise, the function returns +\fB-1\fR and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsctp_getpaddrs()\fR succeeds unless one of the following conditions +exist. +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 12n +.rt +The \fIsock\fR argument is an invalid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 12n +.rt +The \fIsock\fR argument is not a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 12n +.rt +The \fIaddrs\fR argument is \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 12n +.rt +The \fIid\fR argument is an invalid association identifier for a one-to-many +style STP socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTCONN\fR\fR +.ad +.RS 12n +.rt +The specified socket is not connected. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBbind\fR(3SOCKET), \fBin.h\fR(3HEAD), \fBlibsctp\fR(3LIB), +\fBsctp_freeladdrs\fR(3SOCKET), \fBsctp_getladdrs\fR(3SOCKET), +\fBsocket\fR(3SOCKET), \fBattributes\fR(5), \fBinet\fR(7P), \fBinet6\fR(7P), +\fBip\fR(7P), \fBip6\fR(7P), \fBsctp\fR(7P) diff --git a/usr/src/man/man3socket/sctp_opt_info.3socket b/usr/src/man/man3socket/sctp_opt_info.3socket new file mode 100644 index 0000000000..8ef16b6e2a --- /dev/null +++ b/usr/src/man/man3socket/sctp_opt_info.3socket @@ -0,0 +1,387 @@ +'\" te +.\" Copyright (c) 2005, 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 sctp_opt_info 3SOCKET "25 Feb 2005" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +sctp_opt_info \- examine SCTP level options for an SCTP endpoint +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR \fB -lsctp \fR [ \fIlibrary\fR... ] +#include <sys/types.h> +#include <sys/socket.h> +#include <netinet/sctp.h> + +\fBint\fR \fBsctp_opt_info\fR(\fBint\fR \fIsock\fR, \fBsctp_assoc_t\fR \fIid\fR, \fBint\fR \fIopt\fR, \fBvoid *\fR\fIarg\fR, + \fBsocklen_t *\fR\fIlen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsctp_opt_info()\fR returns SCTP level options associated with the SCTP +socket \fIsock\fR. If \fIsock\fR is a one-to-many style socket, \fIid\fR refers +to the association of interest. If \fIsock\fR is a one-to-one socket or if +\fIsock\fR is a branched-off one-to-many style socket, \fIid\fR is ignored. The +\fIopt\fR parameter specifies the SCTP option to get. The \fIarg\fR structure +is an option-specific structure buffer allocated by the caller. The \fIlen\fR +parameter is the length of the option specified. +.sp +.LP +Following are the currently supported values for the \fIopt\fR parameter. When +one of the options below specifies an association \fIid\fR, the \fIid\fR is +relevant for only one-to-many style SCTP sockets. The associatation \fIid\fR +can be ignored for one-to-one style or branched-off one-to-many style SCTP +sockets. +.sp +.ne 2 +.mk +.na +\fB\fBSCTP_RTOINFO\fR\fR +.ad +.RS 27n +.rt +Returns the protocol parameters used to initialize and bind retransmission +timeout (RTO) tunable. The following structure is used to access these +parameters: +.sp +.in +2 +.nf +struct sctp_rtoinfo { + sctp_assoc_t srto_assoc_id; + uint32_t srto_initial; + uint32_t srto_max; + uint32_t srto_min; +}; +where: + srto_assoc_id Association ID specified by the caller + srto_initial Initial RTO value + srto_max Maximum value for the RTO + srto_min Minimum value for the RTO +.fi +.in -2 + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSSCTP_ASSOCINFO\fR\fR +.ad +.RS 27n +.rt +Returns association-specific parameters. The following structure is used to +access the parameters: +.sp +.in +2 +.nf +struct sctp_assocparams { + sctp_assoc_t sasoc_assoc_id; + uint16_t sasoc_asocmaxrxt; + uint16_t sasoc_number_peer_destinations; + uint32_t sasoc_peer_rwnd; + uint32_t sasoc_local_rwnd; + uint32_t sasoc_cookie_life; +}; +where: + srto_assoc_id Association ID specified by the caller + sasoc_asocmaxrxt Maximum retransmission count for + the association + sasoc_number_peer_destinations + Number of addresses the peer has + sasoc_peer_rwnd Current value of the peer's + receive window + sasoc_local_rwnd Last reported receive window sent + to the peer + sasoc_cookie_life Association cookie lifetime used + when issuing cookies +.fi +.in -2 + +All parameters with time values are in milliseconds. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCTP_DEFAULT_SEND_PARAM\fR\fR +.ad +.RS 27n +.rt +Returns the default set of parameters used by the \fBsendto()\fR function on +this association. The following structure is used to access the parameters: +.sp +.in +2 +.nf +struct sctp_sndrcvinfo { + uint16_t sinfo_stream; + uint16_t sinfo_ssn; + uint16_t sinfo_flags; + uint32_t sinfo_ppid; + uint32_t sinfo_context; + uint32_t sinfo_timetolive; + uint32_t sinfo_tsn; + uint32_t sinfo_cumtsn; + sctp_assoc_t sinfo_assoc_id; +}; +where: + sinfo_stream Default stream for \fBsendmsg()\fR + sinfo_ssn Always returned as 0 + sinfo_flags Default flags for \fBsendmsg()\fR + that include the following: + MSG_UNORDERED + MSG_ADDR_OVER + MSG_ABORT + MSG_EOF + MSG_PR_SCTP + sinfo_ppid Default payload protocol identifier + for \fBsendmsg()\fR + sinfo_context Default context for \fBsendmsg()\fR + sinfo_timetolive Time to live in milliseconds for a + message on the sending side. + The message expires if the sending + side does not start the first + transmission for the message within + the specified time period. If the + sending side starts the first + transmission before the time period + expires, the message is sent as a + normal reliable message. A value of + 0 indicates that the message does not + expire. When MSG_PR_SCTP is set in + sinfo_flags, the message expires if + it is not acknowledged within the + time period. + sinfo_tsn Always returned as 0 + sinfo_cumtsn Always returned as 0 + sinfo_assoc_id Association ID specified by the caller +.fi +.in -2 + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCTP_PEER_ADDR_PARAMS\fR\fR +.ad +.RS 27n +.rt +Returns the parameters for a specified peer address of the association. The +following structure is used to access the parameters: +.sp +.in +2 +.nf +struct sctp_paddrparams { + sctp_assoc_t spp_assoc_id; + struct sockaddr_storage spp_address; + uint32_t spp_hbinterval; + uint16_t spp_pathmaxrxt; +}; +where: + spp_assoc_id Association ID specified by the caller + spp_address Peer's address + spp_hbinterval Heartbeat interval in milliseconds + spp_pathmaxrxt Maximum number of retransmissions + to an address before it is + considered unreachable +.fi +.in -2 + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCTP_STATUS\fR\fR +.ad +.RS 27n +.rt +Returns the current status information about the association. The following +structure is used to access the parameters: +.sp +.in +2 +.nf +struct sctp_status { + sctp_assoc_t sstat_assoc_id; + int32_t sstat_state; + uint32_t sstat_rwnd; + uint16_t sstat_unackdata; + uint16_t sstat_penddata; + uint16_t sstat_instrms; + uint16_t sstat_outstrms; + uint16_t sstat_fragmentation_point; + struct sctp_paddrinfo sstat_primary; +}; +where: + + sstat_assoc_id Association ID specifed by the caller + sstat_state Current state of the association + which might be one of the following: + + SCTP_CLOSED + SCTP_BOUND + SCTP_LISTEN + SCTP_COOKIE_WAIT + SCTP_COOKIE_ECHOED + SCTP_ESTABLISHED + SCTP_SHUTDOWN_PENDING + SCTP_SHUTDOWN_SENT + SCTP_SHUTDOWN_RECEIVED + SCTP_SHUTDOWN_ACK_SENT + sstat_rwnd Current receive window of the + association peer + sstat_unackdata Number of unacked DATA chunks + sstat_penddata Number of DATA chunks pending + receipt + sstat_instrms Number of inbound streams + sstat_outstrms Number of outbound streams + sstat_fragmentation_point + Size at which SCTP fragmentation occurs + sstat_primary Information about the primary + peer address + + sstat_primary has the following structure + struct sctp_paddrinfo { + sctp_assoc_t spinfo_assoc_id; + struct sockaddr_storage spinfo_address; + int32_t spinfo_state; + uint32_t spinfo cwnd; + uint32_t spinfo_srtt; + uint32_t spinfo_rto; + uint32_t spinfo_mtu; + }; + where: + spinfo_assoc_id Association ID + specified by + the caller + spinfo_address Primary peer + address + spinfo_state State of the peer + address: + SCTP_ACTIVE or + SCTP_INACTIVE + spinfo_cwnd Congestion window + of the peer + address + spinfo_srtt Smoothed round-trip + time calculation of + the peer address + spinfo_rto Current retransmission + timeout value of the + peer address in + milliseconds + spinfo_mtu P-MTU of the address +.fi +.in -2 + +.RE + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBsctp_opt_info()\fR function returns \fB0\fR. +Otherwise, the function returns \fB-1\fR and sets \fBerrno\fR to indicate the +error. +.SH ERRORS +.sp +.LP +The \fBsctp_opt_info()\fR call fails under the following conditions. +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 16n +.rt +The \fIsock\fR argument is an invalid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 16n +.rt +The \fIsock\fR argument is not a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The association \fIid\fR is invalid for a one-to-many style SCTP socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The input buffer length is insufficient for the option specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The peer address is invalid or does not belong to the association. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAFNOSUPPORT\fR\fR +.ad +.RS 16n +.rt +The address family for the peer's address is other than \fBAF_INET\fR or +\fBAF_INET6\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBin.h\fR(3HEAD), \fBlibsctp\fR(3LIB), \fBgetsockopt\fR(3SOCKET), +\fBsetsockopt\fR(3SOCKET), \fBsocket\fR(3SOCKET), \fBinet\fR(7P), +\fBinet6\fR(7P), \fBip\fR(7P), \fBip6\fR(7P), \fBsctp\fR(7P) diff --git a/usr/src/man/man3socket/sctp_peeloff.3socket b/usr/src/man/man3socket/sctp_peeloff.3socket new file mode 100644 index 0000000000..c143b55dad --- /dev/null +++ b/usr/src/man/man3socket/sctp_peeloff.3socket @@ -0,0 +1,99 @@ +'\" te +.\" Copyright (c) 2004, 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 sctp_peeloff 3SOCKET "05 Mar 2004" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +sctp_peeloff \- branch off existing association from a one-to-many SCTP socket +to create a one-to-one STP socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR \fB -lsctp \fR [ \fIlibrary\fR... ] +#include <sys/types.h> +#include <sys/socket.h> +#include <netinet/sctp.h> + +\fBint\fR \fBsctp_peeloff\fR(\fBint\fR \fIsock\fR, \fBsctp_assoc_t\fR \fIid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsctp_peeloff()\fR function branches off an existing association from a +one-to-many style SCTP socket into a separate socket file descriptor. The +resulting branched-off socket is a one-to-one style SCTP socket and is confined +to operations allowed on a one-to-one style SCTP socket. +.sp +.LP +The \fIsock\fR argument is a one-to-many socket. The association specified by +the \fIid\fR argument is branched off \fIsock\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBsctp_peeloff()\fR function returns the file +descriptor that references the branched-off socket. The function returns +\fB-1\fR if an error occurs. +.SH ERRORS +.sp +.LP +The \fBsctp_peeloff()\fR function fails under the following conditions. +.sp +.ne 2 +.mk +.na +\fB\fBEOPTNOTSUPP\fR\fR +.ad +.RS 15n +.rt +The \fIsock\fR argument is not a one-to-many style SCTP socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 15n +.rt +The \fIid\fR is \fB0\fR or greater than the maximum number of associations for +\fIsock\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 15n +.rt +Failure to create a new user file descriptor or file structure. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBin.h\fR(3HEAD), \fBlibsctp\fR(3LIB), \fBsocket\fR(3SOCKET), \fBsctp\fR(7P) diff --git a/usr/src/man/man3socket/sctp_recvmsg.3socket b/usr/src/man/man3socket/sctp_recvmsg.3socket new file mode 100644 index 0000000000..d8746c7597 --- /dev/null +++ b/usr/src/man/man3socket/sctp_recvmsg.3socket @@ -0,0 +1,160 @@ +'\" te +.\" Copyright (c) 2004, 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 sctp_recvmsg 3SOCKET "14 Jul 2004" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +sctp_recvmsg \- receive message from an SCTP socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR \fB -lsctp \fR [ \fIlibrary\fR... ] +#include <sys/types.h> +#include <sys/socket.h> +#include <netinet/sctp.h> + +\fBssize_t\fR \fBsctp_recvmsg\fR(\fBint\fR \fIs\fR, \fBvoid *\fR\fImsg\fR, \fBsize_t\fR \fIlen\fR, \fBstruct sockaddr *\fR\fIfrom\fR, + \fBsocklen_t *\fR\fIfromlen\fR, \fBstruct sctp_sndrcvinfo *\fR\fIsinfo\fR, \fBint *\fR\fImsg_flags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsctp_recvmsg()\fR function receives a message from the SCTP endpoint +\fIs\fR. +.sp +.LP +In addition to specifying the message buffer \fImsg\fR and the length \fIlen\fR +of the buffer, the following parameters can be set: +.sp +.ne 2 +.mk +.na +\fB\fIfrom\fR\fR +.ad +.RS 13n +.rt +Pointer to an address, filled in with the sender's address +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfromlen\fR\fR +.ad +.RS 13n +.rt +Size of the buffer associated with the \fIfrom\fR parameter +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsinfo\fR\fR +.ad +.RS 13n +.rt +Pointer to an \fBsctp_sndrcvinfo\fR structure, filled in upon the receipt of +the message +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImsg_flags\fR\fR +.ad +.RS 13n +.rt +Message flags such as \fBMSG_CTRUNC\fR, \fBMSG_NOTIFICATION\fR, \fBMSG_EOR\fR +.RE + +.sp +.LP +The \fIsinfo\fR parameter is filled in only when the caller has enabled +\fBsctp_data_io_events\fR by calling \fBsetsockopt()\fR with the socket option +\fBSCTP_EVENTS\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBsctp_recvmsg()\fR function returns the +number of bytes received. The function returns \fB-1\fR if an error occurs. +.SH ERRORS +.sp +.LP +The \fBsctp_recvmsg()\fR function fails under the following conditions. +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 14n +.rt +The \fIs\fR argument is an invalid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 14n +.rt +The \fIs\fR argument is not a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 14n +.rt +\fBMSG_OOB\fR is set as a flag. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTCONN\fR\fR +.ad +.RS 14n +.rt +There is no established association. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBaccept\fR(3SOCKET), \fBbind\fR(3SOCKET), \fBconnect\fR(3SOCKET), +\fBin.h\fR(3HEAD), \fBlibsctp\fR(3LIB), \fBlisten\fR(3SOCKET), +\fBrecvmsg\fR(3SOCKET), \fBsctp_opt_info\fR(3SOCKET), +\fBsetsockopt\fR(3SOCKET), \fBsocket\fR(3SOCKET), \fBsocket.h\fR(3HEAD), +\fBsctp\fR(7P) diff --git a/usr/src/man/man3socket/sctp_send.3socket b/usr/src/man/man3socket/sctp_send.3socket new file mode 100644 index 0000000000..4f31389942 --- /dev/null +++ b/usr/src/man/man3socket/sctp_send.3socket @@ -0,0 +1,216 @@ +'\" te +.\" Copyright (c) 2004, 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 sctp_send 3SOCKET "19 Mar 2004" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +sctp_send \- send message from an SCTP socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR \fB -lsctp \fR [ \fIlibrary\fR... ] +#include <sys/types.h> +#include <sys/socket.h> +#include <netinet/sctp.h> + +\fBssize_t\fR \fBsctp_send\fR(\fBint\fR \fIs\fR, \fBconst void *\fR\fImsg\fR, \fBsize_t *\fR\fIlen\fR, + \fBconst struct sctp_sndrcvinfo *\fR\fIsinfo\fR, \fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsctp_send()\fR function sends messages from one-to-one and one-to-many +style SCTP endpoints. The following parameters can be set: +.sp +.ne 2 +.mk +.na +\fB\fIs\fR\fR +.ad +.RS 7n +.rt +Socket created by \fBsocket\fR(3SOCKET) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImsg\fR\fR +.ad +.RS 7n +.rt +Message to be sent +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 7n +.rt +Size of the message to be sent in bytes +.RE + +.sp +.LP +The caller completes the \fIsinfo\fR parameter with values used to send a +message. Such values might include the stream number, payload protocol +identifier, time to live, and the SCTP message flag and context. For a +one-to-many socket, the association ID can be specified in the \fIsinfo\fR +parameter to send a message to the association represented in the ID. +.sp +.LP +Flags supported for \fBsctp_send()\fR are reserved for future use. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBsctp_send()\fR function returns the number +of bytes sent. The function returns \fB-1\fR if an error occurs. +.SH ERRORS +.sp +.LP +The \fBsctp_send()\fR function fails under the following conditions. +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 16n +.rt +The \fIs\fR argument is an invalid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 16n +.rt +The \fIs\fR argument is not a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 16n +.rt +\fBMSG_ABORT\fR or \fBMSG_EOF\fR is set in the \fBsinfo_flags\fR field of +\fBsinfo\fR for a one-to-one style SCTP socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPIPE\fR\fR +.ad +.RS 16n +.rt +The socket is shutting down and no more writes are allowed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 16n +.rt +The socket is non-blocking and the transmit queue is full. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTCONN\fR\fR +.ad +.RS 16n +.rt +There is no established association. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +Control message length is incorrect. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +Specified destination address does not belong to the association. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The \fBstream_no\fR is outside the number of outbound streams supported by the +association. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAFNOSUPPORT\fR\fR +.ad +.RS 16n +.rt +Address family of the specified destination address is other than \fBAF_INET\fR +or \fBAF_INET6\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBaccept\fR(3SOCKET), \fBbind\fR(3SOCKET), \fBconnect\fR(3SOCKET), +\fBin.h\fR(3HEAD), \fBlibsctp\fR(3LIB), \fBlisten\fR(3SOCKET), +\fBsctp_sendmsg\fR(3SOCKET), \fBsendmsg\fR(3SOCKET), \fBsocket\fR(3SOCKET), +\fBsocket.h\fR(3HEAD), \fBsctp\fR(7P) diff --git a/usr/src/man/man3socket/sctp_sendmsg.3socket b/usr/src/man/man3socket/sctp_sendmsg.3socket new file mode 100644 index 0000000000..835495080f --- /dev/null +++ b/usr/src/man/man3socket/sctp_sendmsg.3socket @@ -0,0 +1,311 @@ +'\" te +.\" 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 sctp_sendmsg 3SOCKET "22 Aug 2007" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +sctp_sendmsg \- send message from an SCTP socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR \fB -lsctp \fR [ \fIlibrary\fR... ] +#include <sys/types.h> +#include <sys/socket.h> +#include <netinet/sctp.h> + +\fBssize_t\fR \fBsctp_sendmsg\fR(\fBint\fR \fIs\fR, \fBconst void *\fR\fImsg\fR, \fBsize_t\fR \fIlen\fR, + \fBconst struct sockaddr *\fR\fIto\fR, \fBsocklen_t\fR \fItolen\fR, \fBuint32_t\fR \fIppid\fR, + \fBuint32_t\fR \fIflags\fR, \fBuint16_t\fR \fIstream_no\fR, \fBuint32_t\fR \fItimetolive\fR, + \fBuint32_t\fR \fIcontext\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsctp_sendmsg()\fR function sends a message from the SCTP endpoint +\fIs\fR. +.sp +.LP +In addition to specifying \fImsg\fR as the message buffer and \fIlen\fR as the +length of the buffer, the following parameters can be set: +.sp +.ne 2 +.mk +.na +\fB\fIto\fR\fR +.ad +.RS 14n +.rt +Destination address +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItolen\fR\fR +.ad +.RS 14n +.rt +Length of the destination address +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIppid\fR\fR +.ad +.RS 14n +.rt +Application-specified payload protocol identifier +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstream_no\fR\fR +.ad +.RS 14n +.rt +Target stream for the message +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItimetolive\fR\fR +.ad +.RS 14n +.rt +Time period in milliseconds after which the message expires if transmission for +the message has not been started. A value of \fB0\fR indicates that the message +does not expire. When the \fBMSG_PR_SCTP\fR flag is set the message expires, +even if transmission has started, unless the entire message is transmitted +within the \fItimetolive\fR period. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcontext\fR\fR +.ad +.RS 14n +.rt +Value returned when an error occurs in sending a message +.RE + +.sp +.LP +The \fIflags\fR parameter is formed from the bitwise OR of zero or more of the +following flags: +.sp +.ne 2 +.mk +.na +\fBMSG_UNORDERED\fR +.ad +.RS 17n +.rt +This flag requests un-ordered delivery of the message. If this flag is clear +the message is considered an ordered send. +.RE + +.sp +.ne 2 +.mk +.na +\fBMSG_ABORT\fR +.ad +.RS 17n +.rt +When set, this flag causes the specified association to abort by sending an +ABORT to the peer. The flag is used only for one-to-many style SCTP socket +associations. +.RE + +.sp +.ne 2 +.mk +.na +\fBMSG_EOF\fR +.ad +.RS 17n +.rt +When set, this flag invokes a graceful shutdown on a specified association. The +flag is used only for one-to-many style SCTP socket associations. +.RE + +.sp +.ne 2 +.mk +.na +\fBMSG_PR_SCTP\fR +.ad +.RS 17n +.rt +This flag indicates that the message is treated as partially reliable. The +message expires unless the entire message is successfully transmitted within +the time period specified in the \fItimetolive\fR parameter. +.sp +\fBMSG_PR_SCTP\fR implements \fItimed reliability\fR service for SCTP messages. +As yet, no common standard has been defined for the service and the interface +is considered unstable. +.RE + +.sp +.LP +The initial call to \fBsctp_sendmsg()\fR can be used to create an association, +but it cannot be used subsequently on an existing association. Since +\fBsctp_sendmsg()\fR always uses 0 internally as the association ID, it is not +suitable for use on one-to-many sockets. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBsctp_sendmsg()\fR function returns the +number of bytes sent. The function returns \fB-1\fR if an error occurs. +.SH ERRORS +.sp +.LP +The \fBsctp_sendmsg()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 16n +.rt +The \fIs\fR argument is an invalid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 16n +.rt +The \fIs\fR argument is not a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 16n +.rt +\fBMSG_OOB\fR is set as a \fIflag\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 16n +.rt +\fBMSG_ABORT\fR or \fBMSG_EOF\fR is set on a one-to-one style SCTP socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPIPE\fR\fR +.ad +.RS 16n +.rt +The socket is shutting down and no more writes are allowed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 16n +.rt +The socket is non-blocking and the transmit queue is full. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTCONN\fR\fR +.ad +.RS 16n +.rt +There is no established association. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +Control message length is incorrect. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +Specified destination address does not belong to the association. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAFNOSUPPORT\fR\fR +.ad +.RS 16n +.rt +Address family of the specified destination address is other than \fBAF_INET\fR +or \fBAF_INET6\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBaccept\fR(3SOCKET), \fBbind\fR(3SOCKET), \fBconnect\fR(3SOCKET), +\fBin.h\fR(3HEAD), \fBlibsctp\fR(3LIB), \fBlisten\fR(3SOCKET), +\fBsendmsg\fR(3SOCKET), \fBsocket\fR(3SOCKET), \fBsocket.h\fR(3HEAD), +\fBattributes\fR(5), \fBsctp\fR(7P) diff --git a/usr/src/man/man3socket/send.3socket b/usr/src/man/man3socket/send.3socket new file mode 100644 index 0000000000..f9e1ad6b15 --- /dev/null +++ b/usr/src/man/man3socket/send.3socket @@ -0,0 +1,304 @@ +'\" te +.\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 1989 AT&T +.\" 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 send 3SOCKET "31 Aug 2009" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +send, sendto, sendmsg \- send a message from a socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR... ] +#include <sys/types.h> +#include <sys/socket.h> + +\fBssize_t\fR \fBsend\fR(\fBint\fR \fIs\fR, \fBconst void *\fR\fImsg\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBssize_t\fR \fBsendto\fR(\fBint\fR \fIs\fR, \fBconst void *\fR\fImsg\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIflags\fR, + \fBconst struct sockaddr *\fR\fIto\fR, \fBint\fR \fItolen\fR); +.fi + +.LP +.nf +\fBssize_t\fR \fBsendmsg\fR(\fBint\fR \fIs\fR, \fBconst struct msghdr *\fR\fImsg\fR, \fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsend()\fR, \fBsendto()\fR, and \fBsendmsg()\fR functions are used to +transmit a message to another transport end-point. The \fBsend()\fR function +can be used only when the socket is in a connected state. See +\fBconnect\fR(3SOCKET). The \fBsendto()\fR and \fBsendmsg()\fR functions can be +used at any time. The \fIs\fR socket is created with \fBsocket\fR(3SOCKET). +.sp +.LP +The address of the target is supplied by \fIto\fR with a \fItolen\fR parameter +used to specify the size. The length of the message is supplied by the +\fIlen\fR parameter. For socket types such as \fBSOCK_DGRAM\fR and +\fBSOCK_RAW\fR that require atomic messages, the error \fBEMSGSIZE\fR is +returned and the message is not transmitted when it is too long to pass +atomically through the underlying protocol. The same restrictions do not apply +to \fBSOCK_STREAM\fR sockets. +.sp +.LP +A return value \fB\(mi1\fR indicates locally detected errors. It does not imply +a delivery failure. +.sp +.LP +If the socket does not have enough buffer space available to hold a message, +the \fBsend()\fR function blocks the message, unless the socket has been placed +in non-blocking I/O mode (see \fBfcntl\fR(2)). The \fBselect\fR(3C) or +\fBpoll\fR(2) call can be used to determine when it is possible to send more +data. +.sp +.LP +The \fIflags\fR parameter is formed from the bitwise OR of zero or more of the +following: +.sp +.ne 2 +.mk +.na +\fB\fBMSG_OOB\fR\fR +.ad +.RS 17n +.rt +Send \fBout-of-band\fR data on sockets that support this notion. The underlying +protocol must also support \fBout-of-band\fR data. Only \fBSOCK_STREAM\fR +sockets created in the \fBAF_INET\fR or the \fBAF_INET6\fR address family +support out-of-band data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMSG_DONTROUTE\fR\fR +.ad +.RS 17n +.rt +The \fBSO_DONTROUTE\fR option is turned on for the duration of the operation. +It is used only by diagnostic or routing programs. +.RE + +.sp +.LP +See \fBrecv\fR(3SOCKET) for a description of the \fBmsghdr\fR structure. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions return the number of bytes sent. +Otherwise, they return \fB-1\fR and set \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsend()\fR, \fBsendto()\fR, and \fBsendmsg()\fR functions return errors +under the following conditions: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 16n +.rt +\fIs\fR is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 16n +.rt +The operation was interrupted by delivery of a signal before any data could be +buffered to be sent. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMSGSIZE\fR\fR +.ad +.RS 16n +.rt +The message is too large to be sent all at once (as the socket requires), or +the \fImsg_iovlen\fR member of the \fBmsghdr\fR structure pointed to by message +is less than or equal to 0 or is greater than {\fBIOV_MAX\fR}. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 16n +.rt +Insufficient memory is available to complete the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 16n +.rt +Insufficient STREAMS resources are available for the operation to complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 16n +.rt +\fIs\fR is not a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEWOULDBLOCK\fR\fR +.ad +.RS 16n +.rt +The socket is marked non-blocking and the requested operation would block. +\fBEWOULDBLOCK\fR is also returned when sufficient memory is not immediately +available to allocate a suitable buffer. In such a case, the operation can be +retried later. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECONNREFUSED\fR\fR +.ad +.RS 16n +.rt +The requested connection was refused by the peer. For conected IPv4 and IPv6 +datagram sockets, this indicates that the system received an \fBICMP +Destination Port Unreachable\fR message from the peer in response to some prior +transmission. +.RE + +.sp +.LP +The \fBsend()\fR and \fBsendto()\fR functions return errors under the following +conditions: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIlen\fR argument overflows a \fBssize_t\fR. +.sp +Inconsistent port attributes for system call. +.RE + +.sp +.LP +The \fBsendto()\fR function returns errors under the following conditions: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The value specified for the \fItolen\fR parameter is not the size of a valid +address for the specified address family. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEISCON\fR\fR +.ad +.RS 10n +.rt +A destination address was specified and the socket is already connected. +.RE + +.sp +.LP +The \fBsendmsg()\fR function returns errors under the following conditions: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fBmsg_iovlen\fR member of the \fBmsghdr\fR structure pointed to by +\fImsg\fR is less than or equal to \fB0\fR, or the sum of the \fIiov_len\fR +values in the \fBmsg_iov\fR array overflows a \fBssize_t\fR. +.sp +One of the \fIiov_len\fR values in the \fBmsg_iov\fR array member of the +\fBmsghdr\fR structure pointed to by \fImsg\fR is negative, or the sum of the +\fIiov_len\fR values in the \fBmsg_iov\fR array overflows a \fBssize_t\fR. +.sp +\fBmsg_iov\fR contents are inconsistent with port attributes. +.RE + +.sp +.LP +The \fBsend()\fR function returns errors under the following conditions: +.sp +.ne 2 +.mk +.na +\fB\fBEPIPE\fR\fR +.ad +.RS 9n +.rt +The socket is shut down for writing, or the socket is connection-mode and is no +longer connected. In the latter case, if the socket is of type +\fBSOCK_STREAM\fR, the \fBSIGPIPE\fR signal is generated to the calling thread. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfcntl\fR(2), \fBpoll\fR(2), \fBwrite\fR(2), \fBconnect\fR(3SOCKET), +\fBgetsockopt\fR(3SOCKET), \fBrecv\fR(3SOCKET), \fBselect\fR(3C), +\fBsocket\fR(3SOCKET), \fBsocket.h\fR(3HEAD), \fBattributes\fR(5) diff --git a/usr/src/man/man3socket/shutdown.3socket b/usr/src/man/man3socket/shutdown.3socket new file mode 100644 index 0000000000..912797fec8 --- /dev/null +++ b/usr/src/man/man3socket/shutdown.3socket @@ -0,0 +1,118 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2005, +.\" 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 shutdown 3SOCKET "31 Jan 2005" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +shutdown \- shut down part of a full-duplex connection +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR... ] +#include <sys/socket.h> + +\fBint\fR \fBshutdown\fR(\fBint\fR \fIs\fR, \fBint\fR \fIhow\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBshutdown()\fR call shuts down all or part of a full-duplex connection on +the socket associated with \fIs\fR. If \fIhow\fR is \fBSHUT_RD\fR, further +receives are disallowed. If \fIhow\fR is \fBSHUT_WR\fR, further sends are +disallowed. If \fIhow\fR is \fBSHUT_RDWR\fR, further sends and receives are +disallowed. +.sp +.LP +The \fIhow\fR values should be defined constants. +.SH RETURN VALUES +.sp +.LP +\fB0\fR is returned if the call succeeds. +.sp +.LP +\fB\(mi1\fR is returned if the call fails. +.SH ERRORS +.sp +.LP +The call succeeds unless one of the following conditions exists: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 12n +.rt +The \fIs\fR value is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 12n +.rt +Insufficient user memory is available for the operation to complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 12n +.rt +Insufficient \fBSTREAMS\fR resources are available for the operation to +complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTCONN\fR\fR +.ad +.RS 12n +.rt +The specified socket is not connected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 12n +.rt +The \fIs\fR value is not a socket. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBconnect\fR(3SOCKET), \fBsocket\fR(3SOCKET), \fBsocket.h\fR(3HEAD), +\fBattributes\fR(5) diff --git a/usr/src/man/man3socket/socket.3socket b/usr/src/man/man3socket/socket.3socket new file mode 100644 index 0000000000..c474af2c5b --- /dev/null +++ b/usr/src/man/man3socket/socket.3socket @@ -0,0 +1,306 @@ +'\" te +.\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" 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 socket 3SOCKET "28 Jan 2009" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +socket \- create an endpoint for communication +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ] +#include <sys/types.h> +#include <sys/socket.h> + +\fBint\fR \fBsocket\fR(\fBint\fR \fIdomain\fR, \fBint\fR \fItype\fR, \fBint\fR \fIprotocol\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsocket()\fR function creates an endpoint for communication and returns a +descriptor. +.sp +.LP +The \fIdomain\fR argument specifies the protocol family within which +communication takes place. The protocol family is generally the same as the +address family for the addresses supplied in later operations on the socket. +These families are defined in \fB<sys/socket.h>\fR. +.sp +.LP +The currently supported protocol families are: +.sp +.ne 2 +.mk +.na +\fB\fBPF_UNIX\fR\fR +.ad +.RS 12n +.rt +\fBUNIX\fR system internal protocols +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPF_INET\fR\fR +.ad +.RS 12n +.rt +Internet Protocol Version 4 (IPv4) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPF_INET6\fR\fR +.ad +.RS 12n +.rt +Internet Protocol Version 6 (IPv6) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPF_NCA\fR\fR +.ad +.RS 12n +.rt +Network Cache and Accelerator (NCA) protocols +.RE + +.sp +.LP +The socket has the indicated \fItype\fR, which specifies the communication +semantics. Currently defined types are: +.sp +.in +2 +.nf +SOCK_STREAM +SOCK_DGRAM +SOCK_RAW +SOCK_SEQPACKET +SOCK_RDM +.fi +.in -2 + +.sp +.LP +There must be an entry in the \fBnetconfig\fR(4) file for at least each +protocol family and type required. If a non-zero protocol has been specified +but no exact match for the protocol family, type, and protocol is found, then +the first entry containing the specified family and type with a \fIprotocol\fR +value of zero will be used. +.sp +.LP +A \fBSOCK_STREAM\fR type provides sequenced, reliable, two-way connection-based +byte streams. An out-of-band data transmission mechanism may be supported. A +\fBSOCK_DGRAM\fR socket supports datagrams (connectionless, unreliable messages +of a fixed (typically small) maximum length). A \fBSOCK_SEQPACKET\fR socket may +provide a sequenced, reliable, two-way connection-based data transmission path +for datagrams of fixed maximum length; a consumer may be required to read an +entire packet with each read system call. This facility is protocol specific, +and presently not implemented for any protocol family. \fBSOCK_RAW\fR sockets +provide access to internal network interfaces. The types \fBSOCK_RAW\fR, which +is available only to a user with the \fBnet_rawaccess\fR privilege, and +\fBSOCK_RDM\fR, for which no implementation currently exists, are not described +here. +.sp +.LP +The \fIprotocol\fR parameter is a protocol-family-specific value which +specifies a particular protocol to be used with the socket. Normally this +value is zero, as commonly only a single protocol exists to support a +particular socket type within a given protocol family. However, multiple +protocols may exist, in which case a particular protocol may be specified in +this manner. +.sp +.LP +Sockets of type \fBSOCK_STREAM\fR are full-duplex byte streams, similar to +pipes. A stream socket must be in a \fIconnected\fR state before any data may +be sent or received on it. A connection to another socket is created with a +\fBconnect\fR(3SOCKET) call. Once connected, data may be transferred using +\fBread\fR(2) and \fBwrite\fR(2) calls or some variant of the +\fBsend\fR(3SOCKET) and \fBrecv\fR(3SOCKET) calls. When a session has been +completed, a \fBclose\fR(2) may be performed. Out-of-band data may also be +transmitted as described on the \fBsend\fR(3SOCKET) manual page and received as +described on the \fBrecv\fR(3SOCKET) manual page. +.sp +.LP +The communications protocols used to implement a \fBSOCK_STREAM\fR insure that +data is not lost or duplicated. If a piece of data for which the peer protocol +has buffer space cannot be successfully transmitted within a reasonable length +of time, then the connection is considered broken and calls will indicate an +error with \(mi1 returns and with \fBETIMEDOUT\fR as the specific code in the +global variable \fBerrno\fR. The protocols optionally keep sockets "warm" by +forcing transmissions roughly every minute in the absence of other activity. An +error is then indicated if no response can be elicited on an otherwise idle +connection for a extended period (for instance 5 minutes). A \fBSIGPIPE\fR +signal is raised if a thread sends on a broken stream; this causes naive +processes, which do not handle the signal, to exit. +.sp +.LP +\fBSOCK_SEQPACKET\fR sockets employ the same system calls as \fBSOCK_STREAM\fR +sockets. The only difference is that \fBread\fR(2) calls will return only the +amount of data requested, and any remaining in the arriving packet will be +discarded. +.sp +.LP +\fBSOCK_DGRAM\fR and \fBSOCK_RAW\fR sockets allow datagrams to be sent to +correspondents named in \fBsendto\fR(3SOCKET) calls. Datagrams are generally +received with \fBrecvfrom\fR(3SOCKET), which returns the next datagram with its +return address. +.sp +.LP +An \fBfcntl\fR(2) call can be used to specify a process group to receive a +\fBSIGURG\fR signal when the out-of-band data arrives. It can also enable +non-blocking I/O. +.sp +.LP +The operation of sockets is controlled by socket level \fIoptions\fR. These +options are defined in the file <\fBsys/socket.h\fR>. \fBsetsockopt\fR(3SOCKET) +and \fBgetsockopt\fR(3SOCKET) are used to set and get options, respectively. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, a descriptor referencing the socket is returned. +Otherwise, -1 is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsocket()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 19n +.rt +Permission to create a socket of the specified type or protocol is denied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 19n +.rt +There were insufficient resources available to complete the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAFNOSUPPORT\fR\fR +.ad +.RS 19n +.rt +The specified address family is not supported by the protocol family. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 19n +.rt +The per-process descriptor table is full. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 19n +.rt +Insufficient user memory is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 19n +.rt +There were insufficient STREAMS resources available to complete the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPFNOSUPPORT\fR\fR +.ad +.RS 19n +.rt +The specified protocol family is not supported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPROTONOSUPPORT\fR\fR +.ad +.RS 19n +.rt +The protocol type is not supported by the address family. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPROTOTYPE\fR\fR +.ad +.RS 19n +.rt +The socket type is not supported by the protocol. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBnca\fR(1), \fBclose\fR(2), \fBfcntl\fR(2), \fBioctl\fR(2), \fBread\fR(2), +\fBwrite\fR(2), \fBaccept\fR(3SOCKET), \fBbind\fR(3SOCKET), +\fBconnect\fR(3SOCKET), \fBgetsockname\fR(3SOCKET), \fBgetsockopt\fR(3SOCKET), +\fBin.h\fR(3HEAD),\fBlisten\fR(3SOCKET), \fBrecv\fR(3SOCKET), +\fBsetsockopt\fR(3SOCKET), \fBsend\fR(3SOCKET), \fBshutdown\fR(3SOCKET), +\fBsocket.h\fR(3HEAD), \fBsocketpair\fR(3SOCKET), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +Historically, \fBAF_\fR* was commonly used in places where \fBPF_\fR* was +meant. New code should be careful to use \fBPF_\fR* as necessary. diff --git a/usr/src/man/man3socket/socketpair.3socket b/usr/src/man/man3socket/socketpair.3socket new file mode 100644 index 0000000000..a455bef899 --- /dev/null +++ b/usr/src/man/man3socket/socketpair.3socket @@ -0,0 +1,138 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (C) 2002, 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 socketpair 3SOCKET "10 Jan 2001" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +socketpair \- create a pair of connected sockets +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ] +#include <sys/types.h> +#include <sys/socket.h> + +\fBint\fR \fBsocketpair\fR(\fBint\fR \fIdomain\fR, \fBint\fR \fItype\fR, \fBint\fR \fIprotocol\fR, \fBint\fR \fIsv\fR[2]); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsocketpair()\fR library call creates an unnamed pair of connected +sockets in the specified address family \fIdomain\fR, of the specified +\fItype\fR, that uses the optionally specified \fIprotocol\fR. The descriptors +that are used in referencing the new sockets are returned in \fIsv\fR[0] and +\fIsv\fR[1]. The two sockets are indistinguishable. +.SH RETURN VALUES +.sp +.LP +\fBsocketpair()\fR returns \fB\(mi1\fR on failure and \fB0\fR on success. +.SH ERRORS +.sp +.LP +The call succeeds unless: +.sp +.ne 2 +.mk +.na +\fB\fBEAFNOSUPPORT\fR\fR +.ad +.RS 19n +.rt +The specified address family is not supported on this machine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 19n +.rt +Too many descriptors are in use by this process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 19n +.rt +There was insufficient user memory for the operation to complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 19n +.rt +There were insufficient \fBSTREAMS\fR resources for the operation to complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 19n +.rt +The specified protocol does not support creation of socket pairs. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPROTONOSUPPORT\fR\fR +.ad +.RS 19n +.rt +The specified protocol is not supported on this machine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 19n +.rt +The process does not have appropriate privileges. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpipe\fR(2), \fBread\fR(2), \fBwrite\fR(2), \fBsocket.h\fR(3HEAD), +\fBattributes\fR(5) +.SH NOTES +.sp +.LP +This call is currently implemented only for the \fBAF_UNIX\fR address family. diff --git a/usr/src/man/man3socket/spray.3socket b/usr/src/man/man3socket/spray.3socket new file mode 100644 index 0000000000..612a5ece32 --- /dev/null +++ b/usr/src/man/man3socket/spray.3socket @@ -0,0 +1,152 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1997, 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 spray 3SOCKET "30 Dec 1996" "SunOS 5.11" "Sockets Library Functions" +.SH NAME +spray \- scatter data in order to test the network +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ] +#include <rpcsvc/spray.h> + +\fBbool_t\fR \fBxdr_sprayarr\fR(\fBXDR *\fR\fIxdrs\fR, \fBsprayarr *\fR\fIobjp\fR); +.fi + +.LP +.nf +\fBbool_t\fR \fBxdr_spraycumul\fR(\fBXDR *\fR\fIxdrs\fR, \fBspraycumul *\fR\fIobjp\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The spray program sends packets to a given machine to test communications with +that machine. +.sp +.LP +The spray program is not a C function interface, per se, but it can be accessed +using the generic remote procedure calling interface \fBclnt_call()\fR. See +\fBrpc_clnt_calls\fR(3NSL). The program sends a packet to the called host. The +host acknowledges receipt of the packet. The program counts the number of +acknowledgments and can return that count. +.sp +.LP +The spray program currently supports the following procedures, which should be +called in the order given: +.sp +.ne 2 +.mk +.na +\fB\fBSPRAYPROC_CLEAR\fR\fR +.ad +.RS 19n +.rt +This procedure clears the counter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSPRAYPROC_SPRAY\fR\fR +.ad +.RS 19n +.rt +This procedure sends the packet. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSPRAYPROC_GET\fR\fR +.ad +.RS 19n +.rt +This procedure returns the count and the amount of time since the last +\fBSPRAYPROC_CLEAR\fR. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBspray()\fR +.sp +.LP +The following code fragment demonstrates how the spray program is used: + +.sp +.in +2 +.nf +#include <rpc/rpc.h> +#include <rpcsvc/spray.h> + . . . + spraycumul spray_result; + sprayarr spray_data; + char buf[100]; /* arbitrary data */ + int loop = 1000; + CLIENT *clnt; + struct timeval timeout0 = {0, 0}; + struct timeval timeout25 = {25, 0}; + spray_data.sprayarr_len = (uint_t)100; + spray_data.sprayarr_val = buf; + clnt = clnt_create("somehost", SPRAYPROG, SPRAYVERS, "netpath"); + if (clnt == (CLIENT *)NULL) { + /* handle this error */ + } + if (clnt_call(clnt, SPRAYPROC_CLEAR, + xdr_void, NULL, xdr_void, NULL, timeout25)) { + /* handle this error */ + } + while (loop\(mi > 0) { + if (clnt_call(clnt, SPRAYPROC_SPRAY, + xdr_sprayarr, &spray_data, xdr_void, NULL, timeout0)) { + /* handle this error */ + } + } + if (clnt_call(clnt, SPRAYPROC_GET, + xdr_void, NULL, xdr_spraycumul, &spray_result, timeout25)) { + /* handle this error */ + } + printf("Acknowledged %ld of 1000 packets in %d secs %d usecs\en", + spray_result.counter, + spray_result.clock.sec, + spray_result.clock.usec); +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBspray\fR(1M), \fBrpc_clnt_calls\fR(3NSL), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +This interface is unsafe in multithreaded applications. Unsafe interfaces +should be called only from the main thread. +.sp +.LP +A spray program is not useful as a networking benchmark as it uses unreliable +connectionless transports, for example, udp. It can report a large number of +packets dropped, when the drops were caused by the program sending packets +faster than they can be buffered locally, that is, before the packets get to +the network medium. |