diff options
Diffstat (limited to 'usr/src/man/man3xnet')
31 files changed, 8055 insertions, 0 deletions
diff --git a/usr/src/man/man3xnet/Makefile b/usr/src/man/man3xnet/Makefile new file mode 100644 index 0000000000..4996a85a9f --- /dev/null +++ b/usr/src/man/man3xnet/Makefile @@ -0,0 +1,130 @@ +# +# 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 = 3xnet + +MANFILES = accept.3xnet \ + bind.3xnet \ + connect.3xnet \ + endhostent.3xnet \ + endnetent.3xnet \ + endprotoent.3xnet \ + endservent.3xnet \ + freeaddrinfo.3xnet \ + gai_strerror.3xnet \ + gethostname.3xnet \ + getnameinfo.3xnet \ + getpeername.3xnet \ + getsockname.3xnet \ + getsockopt.3xnet \ + htonl.3xnet \ + if_nametoindex.3xnet \ + inet_addr.3xnet \ + inet_ntop.3xnet \ + listen.3xnet \ + recv.3xnet \ + recvfrom.3xnet \ + recvmsg.3xnet \ + send.3xnet \ + sendmsg.3xnet \ + sendto.3xnet \ + setsockopt.3xnet \ + shutdown.3xnet \ + sockatmark.3xnet \ + socket.3xnet \ + socketpair.3xnet + +MANSOFILES = getaddrinfo.3xnet \ + gethostbyaddr.3xnet \ + gethostbyname.3xnet \ + gethostent.3xnet \ + getnetbyaddr.3xnet \ + getnetbyname.3xnet \ + getnetent.3xnet \ + getprotobyname.3xnet \ + getprotobynumber.3xnet \ + getprotoent.3xnet \ + getservbyname.3xnet \ + getservbyport.3xnet \ + getservent.3xnet \ + htons.3xnet \ + if_freenameindex.3xnet \ + if_indextoname.3xnet \ + if_nameindex.3xnet \ + inet_lnaof.3xnet \ + inet_makeaddr.3xnet \ + inet_netof.3xnet \ + inet_network.3xnet \ + inet_ntoa.3xnet \ + inet_pton.3xnet \ + ntohl.3xnet \ + ntohs.3xnet \ + sethostent.3xnet \ + setnetent.3xnet \ + setprotoent.3xnet \ + setservent.3xnet + +MANFILES += $(MANSOFILES) + +getaddrinfo.3xnet := SOSRC = man3xnet/freeaddrinfo.3xnet + +gethostbyaddr.3xnet := SOSRC = man3xnet/endhostent.3xnet +gethostbyname.3xnet := SOSRC = man3xnet/endhostent.3xnet +gethostent.3xnet := SOSRC = man3xnet/endhostent.3xnet + +getnetbyaddr.3xnet := SOSRC = man3xnet/endnetent.3xnet +getnetbyname.3xnet := SOSRC = man3xnet/endnetent.3xnet +getnetent.3xnet := SOSRC = man3xnet/endnetent.3xnet + +getprotobyname.3xnet := SOSRC = man3xnet/endprotoent.3xnet +getprotobynumber.3xnet := SOSRC = man3xnet/endprotoent.3xnet +getprotoent.3xnet := SOSRC = man3xnet/endprotoent.3xnet + +getservbyname.3xnet := SOSRC = man3xnet/endservent.3xnet +getservbyport.3xnet := SOSRC = man3xnet/endservent.3xnet +getservent.3xnet := SOSRC = man3xnet/endservent.3xnet + +htons.3xnet := SOSRC = man3xnet/htonl.3xnet + +if_freenameindex.3xnet := SOSRC = man3xnet/if_nametoindex.3xnet +if_indextoname.3xnet := SOSRC = man3xnet/if_nametoindex.3xnet +if_nameindex.3xnet := SOSRC = man3xnet/if_nametoindex.3xnet + +inet_lnaof.3xnet := SOSRC = man3xnet/inet_addr.3xnet +inet_makeaddr.3xnet := SOSRC = man3xnet/inet_addr.3xnet +inet_netof.3xnet := SOSRC = man3xnet/inet_addr.3xnet +inet_network.3xnet := SOSRC = man3xnet/inet_addr.3xnet +inet_ntoa.3xnet := SOSRC = man3xnet/inet_addr.3xnet + +inet_pton.3xnet := SOSRC = man3xnet/inet_ntop.3xnet + +ntohl.3xnet := SOSRC = man3xnet/htonl.3xnet +ntohs.3xnet := SOSRC = man3xnet/htonl.3xnet + +sethostent.3xnet := SOSRC = man3xnet/endhostent.3xnet + +setnetent.3xnet := SOSRC = man3xnet/endnetent.3xnet + +setprotoent.3xnet := SOSRC = man3xnet/endprotoent.3xnet + +setservent.3xnet := SOSRC = man3xnet/endservent.3xnet + +.KEEP_STATE: + +include ../Makefile.man + +install: $(ROOTMANFILES) + + diff --git a/usr/src/man/man3xnet/accept.3xnet b/usr/src/man/man3xnet/accept.3xnet new file mode 100644 index 0000000000..d249666b50 --- /dev/null +++ b/usr/src/man/man3xnet/accept.3xnet @@ -0,0 +1,302 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 3XNET "1 Nov 2003" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +accept \- accept a new connection on a socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> + + +\fBint\fR \fBaccept\fR(\fBint\fR \fIsocket\fR, \fBstruct sockaddr *restrict\fR \fIaddress\fR, + \fBsocklen_t *restrict\fR \fIaddress_len\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBaccept()\fR function extracts the first connection on the queue of +pending connections, creates a new socket with the same socket type protocol +and address family as the specified socket, and allocates a new file descriptor +for that socket. +.sp +.LP +The function takes the following arguments: +.sp +.ne 2 +.mk +.na +\fB\fIsocket\fR\fR +.ad +.RS 15n +.rt +Specifies a socket that was created with \fBsocket\fR(3XNET), has been bound to +an address with \fBbind\fR(3XNET), and has issued a successful call to +\fBlisten\fR(3XNET). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddress\fR\fR +.ad +.RS 15n +.rt +Either a null pointer, or a pointer to a \fBsockaddr\fR structure where the +address of the connecting socket will be returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddress_len\fR\fR +.ad +.RS 15n +.rt +Points to a \fBsocklen_t\fR which on input specifies the length of the supplied +\fBsockaddr\fR structure, and on output specifies the length of the stored +address. +.RE + +.sp +.LP +If \fIaddress\fR is not a null pointer, the address of the peer for the +accepted connection is stored in the \fBsockaddr\fR structure pointed to by +\fIaddress\fR, and the length of this address is stored in the object pointed +to by \fIaddress_len\fR. +.sp +.LP +If the actual length of the address is greater than the length of the supplied +\fBsockaddr\fR structure, the stored address will be truncated. +.sp +.LP +If the protocol permits connections by unbound clients, and the peer is not +bound, then the value stored in the object pointed to by \fIaddress\fR is +unspecified. +.sp +.LP +If the listen queue is empty of connection requests and O_NONBLOCK is not set +on the file descriptor for the socket, \fBaccept()\fR will block until a +connection is present. If the \fBlisten\fR(3XNET) queue is empty of connection +requests and O_NONBLOCK is set on the file descriptor for the socket, +\fBaccept()\fR will fail and set \fBerrno\fR to \fBEAGAIN\fR or +\fBEWOULDBLOCK\fR. +.sp +.LP +The accepted socket cannot itself accept more connections. The original socket +remains open and can accept more connections. +.SH USAGE +.sp +.LP +When a connection is available, \fBselect\fR(3C) will indicate that the file +descriptor for the socket is ready for reading. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBaccept()\fR returns the nonnegative file +descriptor of the accepted socket. Otherwise, \(mi1 is returned and +\fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBaccept()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.br +.na +\fB\fBEWOULDBLOCK\fR\fR +.ad +.RS 16n +.rt +O_NONBLOCK is set for the socket file descriptor and no connections are present +to be accepted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 16n +.rt +The \fIsocket\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECONNABORTED\fR\fR +.ad +.RS 16n +.rt +A connection has been aborted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 16n +.rt +The \fIaddress\fR or \fIaddress_len\fR parameter can not be accessed or +written. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 16n +.rt +The \fBaccept()\fR function was interrupted by a signal that was caught before +a valid connection arrived. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The \fIsocket\fR is not accepting connections. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 16n +.rt +\fBOPEN_MAX\fR file descriptors are currently open in the calling process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 16n +.rt +The maximum number of file descriptors in the system are already open. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 16n +.rt +The \fIsocket\fR argument does not refer to a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 16n +.rt +The socket type of the specified socket does not support accepting connections. +.RE + +.sp +.LP +The \fBaccept()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 11n +.rt +No buffer space is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 11n +.rt +There was insufficient memory available to complete the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 11n +.rt +There was insufficient STREAMS resources available to complete the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPROTO\fR\fR +.ad +.RS 11n +.rt +A protocol error has occurred; for example, the STREAMS protocol stack has not +been initialized. +.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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBbind\fR(3XNET), \fBconnect\fR(3XNET), \fBlisten\fR(3XNET), +\fBsocket\fR(3XNET), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/bind.3xnet b/usr/src/man/man3xnet/bind.3xnet new file mode 100644 index 0000000000..fef4029f2d --- /dev/null +++ b/usr/src/man/man3xnet/bind.3xnet @@ -0,0 +1,372 @@ +'\" te +.\" Copyright (c) 1997, The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 3XNET "20 Feb 2003" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +bind \- bind a name to a socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> + +\fBint\fR \fBbind\fR(\fBint\fR \fIsocket\fR, \fBconst struct sockaddr *\fR\fIaddress\fR, + \fBsocklen_t\fR \fIaddress_len\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBbind()\fR function assigns an \fIaddress\fR to an unnamed socket. +Sockets created with \fBsocket\fR(3XNET) function are initially unnamed. They +are identified only by their address family. +.sp +.LP +The function takes the following arguments: +.sp +.ne 2 +.mk +.na +\fB\fIsocket\fR\fR +.ad +.RS 15n +.rt +Specifies the file descriptor of the socket to be bound. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddress\fR\fR +.ad +.RS 15n +.rt +Points to a \fBsockaddr\fR structure containing the address to be bound to the +socket. The length and format of the address depend on the address family of +the socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddress_len\fR\fR +.ad +.RS 15n +.rt +Specifies the length of the \fBsockaddr\fR structure pointed to by the +\fIaddress\fR argument. +.RE + +.sp +.LP +The socket in use may require the process to have appropriate privileges to use +the \fBbind()\fR function. +.SH USAGE +.sp +.LP +An application program can retrieve the assigned socket name with the +\fBgetsockname\fR(3XNET) function. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBbind()\fR returns 0. Otherwise, \(mi1 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\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 from the local machine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAFNOSUPPORT\fR\fR +.ad +.RS 17n +.rt +The specified address is not a valid address for the address family of the +specified socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 17n +.rt +The \fIsocket\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 17n +.rt +The \fIaddress\fR argument can not be accessed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 17n +.rt +The socket is already bound to an address, and the protocol does not support +binding to a new address; or the socket has been shut down. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 17n +.rt +The \fIsocket\fR argument does not refer to a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 17n +.rt +The socket type of the specified socket does not support binding to an address. +.RE + +.sp +.LP +If the address family of the socket is AF_UNIX, then \fBbind()\fR will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +A component of the path prefix denies search permission, or the requested name +requires writing in a directory with a mode that denies write permission. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEDESTADDRREQ\fR\fR +.ad +.br +.na +\fB\fBEISDIR\fR\fR +.ad +.RS 16n +.rt +The \fIaddress\fR argument is a null pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 16n +.rt +An I/O error occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +Too many symbolic links were encountered in translating the pathname in +\fIaddress.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +A component of a pathname exceeded \fINAME_MAX\fR characters, or an entire +pathname exceeded \fIPATH_MAX\fR characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 16n +.rt +A component of the pathname does not name an existing file or the pathname is +an empty string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 16n +.rt +A component of the path prefix of the pathname in \fIaddress\fR is not a +directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEROFS\fR\fR +.ad +.RS 16n +.rt +The name would reside on a read-only filesystem. +.RE + +.sp +.LP +The \fBbind()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +The specified address is protected, and \fB{PRIV_NET_PRIVADOR}\fR is not +asserted in the effective set of the current process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The \fIaddress_len\fR argument is not a valid length for the address family. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEISCONN\fR\fR +.ad +.RS 16n +.rt +The socket is already connected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +Pathname resolution of a symbolic link produced an intermediate result whose +length exceeds \fIPATH_MAX\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 16n +.rt +Insufficient resources were available to complete the call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 16n +.rt +There were insufficient STREAMS resources for the operation to complete. +.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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBconnect\fR(3XNET), \fBgetsockname\fR(3XNET), \fBlisten\fR(3XNET), +\fBsocket\fR(3XNET), \fBattributes\fR(5), \fBprivileges\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/connect.3xnet b/usr/src/man/man3xnet/connect.3xnet new file mode 100644 index 0000000000..f56eff4bcd --- /dev/null +++ b/usr/src/man/man3xnet/connect.3xnet @@ -0,0 +1,477 @@ +'\" te +.\" Copyright 1994, The X/Open Company Ltd. All Rights Reserved Portions Copyright 1989 AT&T Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 3XNET "10 Jun 2002" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +connect \- connect a socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> + +\fBint\fR \fBconnect\fR(\fBint\fR \fIsocket\fR, \fBconst struct sockaddr *\fR\fIaddress\fR, + \fBsocklen_t\fR \fIaddress_len\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBconnect()\fR function requests a connection to be made on a socket. The +function takes the following arguments: +.sp +.ne 2 +.mk +.na +\fB\fIsocket\fR\fR +.ad +.RS 15n +.rt +Specifies the file descriptor associated with the socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddress\fR\fR +.ad +.RS 15n +.rt +Points to a \fBsockaddr\fR structure containing the peer address. The length +and format of the address depend on the address family of the socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddress_len\fR\fR +.ad +.RS 15n +.rt +Specifies the length of the \fBsockaddr\fR structure pointed to by the +\fIaddress\fR argument. +.RE + +.sp +.LP +If the socket has not already been bound to a local address, \fBconnect()\fR +will bind it to an address which, unless the socket's address family is +AF_UNIX, is an unused local address. +.sp +.LP +If the initiating socket is not connection-mode, then \fBconnect()\fR sets the +socket's peer address, but no connection is made. For SOCK_DGRAM sockets, the +peer address identifies where all datagrams are sent on subsequent +\fBsend\fR(3XNET) calls, and limits the remote sender for subsequent +\fBrecv\fR(3XNET) calls. If \fIaddress\fR is a null address for the protocol, +the socket's peer address will be reset. +.sp +.LP +If the initiating socket is connection-mode, then \fBconnect()\fR attempts to +establish a connection to the address specified by the \fIaddress\fR argument. +.sp +.LP +If the connection cannot be established immediately and O_NONBLOCK is not set +for the file descriptor for the socket, \fBconnect()\fR will block for up to an +unspecified timeout interval until the connection is established. If the +timeout interval expires before the connection is established, \fBconnect()\fR +will fail and the connection attempt will be aborted. If \fBconnect()\fR is +interrupted by a signal that is caught while blocked waiting to establish a +connection, \fBconnect()\fR will fail and set \fBerrno\fR to \fBEINTR\fR, but +the connection request will not be aborted, and the connection will be +established asynchronously. +.sp +.LP +If the connection cannot be established immediately and O_NONBLOCK is set for +the file descriptor for the socket, \fBconnect()\fR will fail and set +\fBerrno\fR to \fBEINPROGRESS\fR, but the connection request will not be +aborted, and the connection will be established asynchronously. Subsequent +calls to \fBconnect()\fR for the same socket, before the connection is +established, will fail and set \fBerrno\fR to \fBEALREADY\fR. +.sp +.LP +When the connection has been established asynchronously, \fBselect\fR(3C) and +\fBpoll\fR(2) will indicate that the file descriptor for the socket is ready +for writing. +.sp +.LP +The socket in use may require the process to have appropriate privileges to use +the \fBconnect()\fR function. +.SH USAGE +.sp +.LP +If \fBconnect()\fR fails, the state of the socket is unspecified. Portable +applications should close the file descriptor and create a new socket before +attempting to reconnect. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBconnect()\fR returns 0. Otherwise, \(mi1 is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBconnect()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEADDRNOTAVAIL\fR\fR +.ad +.RS 17n +.rt +The specified address is not available from the local machine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAFNOSUPPORT\fR\fR +.ad +.RS 17n +.rt +The specified address is not a valid address for the address family of the +specified socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEALREADY\fR\fR +.ad +.RS 17n +.rt +A connection request is already in progress for the specified socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 17n +.rt +The \fIsocket\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECONNREFUSED\fR\fR +.ad +.RS 17n +.rt +The target address was not listening for connections or refused the connection +request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 17n +.rt +The address parameter can not be accessed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINPROGRESS\fR\fR +.ad +.RS 17n +.rt +O_NONBLOCK is set for the file descriptor for the socket and the connection +cannot be immediately established; the connection will be established +asynchronously. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 17n +.rt +The attempt to establish a connection was interrupted by delivery of a signal +that was caught; the connection will be established asynchronously. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEISCONN\fR\fR +.ad +.RS 17n +.rt +The specified socket is connection-mode and is already connected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENETUNREACH\fR\fR +.ad +.RS 17n +.rt +No route to the network is present. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 17n +.rt +The \fIsocket\fR argument does not refer to a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPROTOTYPE\fR\fR +.ad +.RS 17n +.rt +The specified address has a different type than the socket bound to the +specified peer address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBETIMEDOUT\fR\fR +.ad +.RS 17n +.rt +The attempt to connect timed out before a connection was made. +.RE + +.sp +.LP +If the address family of the socket is AF_UNIX, then \fBconnect()\fR will fail +if: +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 16n +.rt +An I/O error occurred while reading from or writing to the file system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +Too many symbolic links were encountered in translating the pathname in +\fIaddress\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +A component of a pathname exceeded \fINAME_MAX\fR characters, or an entire +pathname exceeded \fIPATH_MAX\fR characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 16n +.rt +A component of the pathname does not name an existing file or the pathname is +an empty string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 16n +.rt +A component of the path prefix of the pathname in \fIaddress\fR is not a +directory. +.RE + +.sp +.LP +The \fBconnect()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +Search permission is denied for a component of the path prefix; or write access +to the named socket is denied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEADDRINUSE\fR\fR +.ad +.RS 16n +.rt +Attempt to establish a connection that uses addresses that are already in use. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECONNRESET\fR\fR +.ad +.RS 16n +.rt +Remote host reset the connection request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEHOSTUNREACH\fR\fR +.ad +.RS 16n +.rt +The destination host cannot be reached (probably because the host is down or a +remote router cannot reach it). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The \fIaddress_len\fR argument is not a valid length for the address family; or +invalid address family in sockaddr structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +Pathname resolution of a symbolic link produced an intermediate result whose +length exceeds \fIPATH_MAX\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENETDOWN\fR\fR +.ad +.RS 16n +.rt +The local interface used to reach the destination is down. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 16n +.rt +No buffer space is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 16n +.rt +There were insufficient STREAMS resources available to complete the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 16n +.rt +The socket is listening and can not be 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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBpoll\fR(2), \fBaccept\fR(3XNET), \fBbind\fR(3XNET), +\fBgetsockname\fR(3XNET), \fBselect\fR(3C), \fBsend\fR(3XNET), +\fBshutdown\fR(3XNET), \fBsocket\fR(3XNET), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/endhostent.3xnet b/usr/src/man/man3xnet/endhostent.3xnet new file mode 100644 index 0000000000..aa0163845d --- /dev/null +++ b/usr/src/man/man3xnet/endhostent.3xnet @@ -0,0 +1,185 @@ +'\" te +.\" Copyright (c) 1997, The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 endhostent 3XNET "1 Nov 2003" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +endhostent, gethostbyaddr, gethostbyname, gethostent, sethostent \- network +host database functions +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <netdb.h> +extern int h_errno; + +\fBvoid\fR \fBendhostent\fR(void) +.fi + +.LP +.nf +\fBstruct hostent *\fR\fBgethostbyaddr\fR(\fBconst void *\fR\fIaddr\fR, \fBsocklen_t\fR \fIlen\fR, \fBint\fR \fItype\fR); +.fi + +.LP +.nf +\fBstruct hostent *\fR\fBgethostbyname\fR(\fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBstruct hostent *\fR\fBgethostent\fR(void) +.fi + +.LP +.nf +\fBvoid\fR \fBsethostent\fR(\fBint\fR \fIstayopen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgethostent()\fR, \fBgethostbyaddr()\fR, and \fBgethostbyname()\fR +functions each return a pointer to a \fBhostent\fR structure, the members of +which contain the fields of an entry in the network host database. +.sp +.LP +The \fBgethostent()\fR function reads the next entry of the database, opening a +connection to the database if necessary. +.sp +.LP +The \fBgethostbyaddr()\fR function searches the database and finds an entry +which matches the address family specified by the \fBtype\fR argument and which +matches the address pointed to by the \fIaddr\fR argument, opening a +connection to the database if necessary. The \fIaddr\fR argument is a pointer +to the binary-format (that is, not null-terminated) address in network byte +order, whose length is specified by the \fIlen\fR argument. The datatype of +the address depends on the address family. For an address of type +\fBAF_INET\fR, this is an \fBin_addr\fR structure, defined in +<\fBnetinet/in.h\fR>. For an address of type \fBAF_INET6\fR, there is an +\fBin6_addr\fR structure defined in <\fBnetinet/in.h\fR>. +.sp +.LP +The \fBgethostbyname()\fR function searches the database and finds an entry +which matches the host name specified by the \fIname\fR argument, opening a +connection to the database if necessary. If \fIname\fR is an alias for a valid +host name, the function returns information about the host name to which the +alias refers, and \fIname\fR is included in the list of aliases returned. +.sp +.LP +The \fBsethostent()\fR function opens a connection to the network host +database, and sets the position of the next entry to the first entry. If the +\fIstayopen\fR argument is non-zero, the connection to the host database will +not be closed after each call to \fBgethostent()\fR (either directly, or +indirectly through one of the other \fBgethost*(\|)\fR functions). +.sp +.LP +The \fBendhostent()\fR function closes the connection to the database. +.SH USAGE +.sp +.LP +The \fBgethostent()\fR, \fBgethostbyaddr()\fR, and \fBgethostbyname()\fR +functions may return pointers to static data, which may be overwritten by +subsequent calls to any of these functions. +.sp +.LP +These functions are generally used with the Internet address family. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBgethostbyaddr()\fR, \fBgethostbyname()\fR and +\fBgethostent()\fR return a pointer to a \fBhostent\fR structure if the +requested entry was found, and a null pointer if the end of the database was +reached or the requested entry was not found. Otherwise, a null pointer is +returned. +.sp +.LP +On unsuccessful completion, \fBgethostbyaddr()\fR and \fBgethostbyname()\fR +functions set \fIh_errno\fR to indicate the error. +.SH ERRORS +.sp +.LP +No errors are defined for \fBendhostent()\fR, \fBgethostent()\fR and +\fBsethostent()\fR. +.sp +.LP +The \fBgethostbyaddr()\fR and \fBgethostbyname()\fR functions will fail in the +following cases, setting \fIh_errno\fR to the value shown in the list below. +Any changes to \fBerrno\fR are unspecified. +.sp +.ne 2 +.mk +.na +\fB\fBHOST_NOT_FOUND\fR\fR +.ad +.RS 18n +.rt +No such host is known. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNO_DATA\fR\fR +.ad +.RS 18n +.rt +The server recognised the request and the name but no address is available. +Another type of request to the name server for the domain might return an +answer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNO_RECOVERY\fR\fR +.ad +.RS 18n +.rt +An unexpected server failure occurred which can not be recovered. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTRY_AGAIN\fR\fR +.ad +.RS 18n +.rt +A temporary and possibly transient error occurred, such as a failure of a +server to respond. +.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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBendservent\fR(3XNET), \fBhtonl\fR(3XNET), \fBinet_addr\fR(3XNET), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/endnetent.3xnet b/usr/src/man/man3xnet/endnetent.3xnet new file mode 100644 index 0000000000..a725e5323e --- /dev/null +++ b/usr/src/man/man3xnet/endnetent.3xnet @@ -0,0 +1,113 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 endnetent 3XNET "10 Jun 2002" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +endnetent, getnetbyaddr, getnetbyname, getnetent, setnetent \- network database +functions +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <netdb.h> + +\fBvoid\fR \fBendnetent\fR(\fBvoid);struct netent *getnetbyaddr(in_addr_t\fR \fInet\fR, \fBint\fR \fItype\fR); +.fi + +.LP +.nf +\fBstruct netent *\fR\fBgetnetbyname\fR(\fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBstruct netent *\fR\fBgetnetent\fR(void) +.fi + +.LP +.nf +\fBvoid\fR \fBsetnetent\fR(\fBint\fR \fIstayopen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetnetbyaddr()\fR, \fBgetnetbyname()\fR and \fBgetnetent()\fR, functions +each return a pointer to a \fBnetent\fR structure, the members of which contain +the fields of an entry in the network database. +.sp +.LP +The \fBgetnetent()\fR function reads the next entry of the database, opening a +connection to the database if necessary. +.sp +.LP +The \fBgetnetbyaddr()\fR function searches the database from the beginning, and +finds the first entry for which the address family specified by \fBtype\fR +matches the \fBn_addrtype\fR member and the network number \fInet\fR matches +the \fBn_net\fR member, opening a connection to the database if necessary. The +\fInet\fR argument is the network number in host byte order. +.sp +.LP +The \fBgetnetbyname()\fR function searches the database from the beginning and +finds the first entry for which the network name specified by \fIname\fR +matches the \fBn_name\fR member, opening a connection to the database if +necessary. +.sp +.LP +The \fBsetnetent()\fR function opens and rewinds the database. If the +\fIstayopen\fR argument is non-zero, the connection to the net database will +not be closed after each call to \fBgetnetent()\fR (either directly, or +indirectly through one of the other \fBgetnet*(\|)\fR functions). +.sp +.LP +The \fBendnetent()\fR function closes the database. +.SH USAGE +.sp +.LP +The \fBgetnetbyaddr()\fR, \fBgetnetbyname()\fR and \fBgetnetent()\fR, functions +may return pointers to static data, which may be overwritten by subsequent +calls to any of these functions. +.sp +.LP +These functions are generally used with the Internet address family. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBgetnetbyaddr()\fR, \fBgetnetbyname()\fR and +\fBgetnetent()\fR, return a pointer to a \fBnetent\fR structure if the +requested entry was found, and a null pointer if the end of the database was +reached or the requested entry was not found. Otherwise, a null pointer is +returned. +.SH ERRORS +.sp +.LP +No errors are defined. +.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-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/endprotoent.3xnet b/usr/src/man/man3xnet/endprotoent.3xnet new file mode 100644 index 0000000000..7b0db69f0b --- /dev/null +++ b/usr/src/man/man3xnet/endprotoent.3xnet @@ -0,0 +1,118 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 endprotoent 3XNET "10 Jun 2002" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +endprotoent, getprotobynumber, getprotobyname, getprotoent, setprotoent \- +network protocol database functions +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <netdb.h> + +\fBvoid\fR \fBendprotoent\fR(void) +.fi + +.LP +.nf +\fBstruct protoent *\fR\fBgetprotobyname\fR(\fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBstruct protoent *\fR\fBgetprotobynumber\fR(\fBint\fR \fIproto\fR); +.fi + +.LP +.nf +\fBstruct protoent *\fR\fBgetprotoent\fR(void) +.fi + +.LP +.nf +\fBvoid\fR \fBsetprotoent\fR(\fBint\fR \fIstayopen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetprotobyname()\fR, \fBgetprotobynumber()\fR and \fBgetprotoent()\fR, +functions each return a pointer to a \fBprotoent\fR structure, the members of +which contain the fields of an entry in the network protocol database. +.sp +.LP +The \fBgetprotoent()\fR function reads the next entry of the database, opening +a connection to the database if necessary. +.sp +.LP +The \fBgetprotobyname()\fR function searches the database from the beginning +and finds the first entry for which the protocol name specified by \fIname\fR +matches the \fBp_name\fR member, opening a connection to the database if +necessary. +.sp +.LP +The \fBgetprotobynumber()\fR function searches the database from the beginning +and finds the first entry for which the protocol number specified by +\fInumber\fR matches the \fBp_proto\fR member, opening a connection to the +database if necessary. +.sp +.LP +The \fBsetprotoent()\fR function opens a connection to the database, and sets +the next entry to the first entry. If the \fIstayopen\fR argument is non-zero, +the connection to the network protocol database will not be closed after each +call to \fBgetprotoent()\fR (either directly, or indirectly through one of the +other \fBgetproto*(\|)\fR functions). +.sp +.LP +The \fBendprotoent()\fR function closes the connection to the database. +.SH USAGE +.sp +.LP +The \fBgetprotobyname()\fR, \fBgetprotobynumber()\fR and \fBgetprotoent()\fR +functions may return pointers to static data, which may be overwritten by +subsequent calls to any of these functions. +.sp +.LP +These functions are generally used with the Internet address family. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBgetprotobyname()\fR, \fBgetprotobynumber()\fR and +\fBgetprotoent()\fR functions return a pointer to a \fBprotoent\fR structure if +the requested entry was found, and a null pointer if the end of the database +was reached or the requested entry was not found. Otherwise, a null pointer is +returned. +.SH ERRORS +.sp +.LP +No errors are defined. +.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-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/endservent.3xnet b/usr/src/man/man3xnet/endservent.3xnet new file mode 100644 index 0000000000..a93b8a57a6 --- /dev/null +++ b/usr/src/man/man3xnet/endservent.3xnet @@ -0,0 +1,128 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 endservent 3XNET "14 Jun 2002" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +endservent, getservbyport, getservbyname, getservent, setservent \- network +services database functions +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <netdb.h> + +\fBvoid\fR \fBendservent\fR(void) +.fi + +.LP +.nf +\fBstruct servent *\fR\fBgetservbyname\fR(\fBconst char *\fR\fIname\fR, \fBconst char *\fR\fIproto\fR); +.fi + +.LP +.nf +\fBstruct servent *\fR\fBgetservbyport\fR(\fBint\fR \fIport\fR, \fBconst char *\fR\fIproto\fR); +.fi + +.LP +.nf +\fBstruct servent *\fR\fBgetservent\fR(void) +.fi + +.LP +.nf +\fBvoid\fR \fBsetservent\fR(\fBint\fR \fIstayopen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetservbyname()\fR, \fBgetservbyport()\fR and \fBgetservent()\fR +functions each return a pointer to a \fBservent\fR structure, the members of +which contain the fields of an entry in the network services database. +.sp +.LP +The \fBgetservent()\fR function reads the next entry of the database, opening a +connection to the database if necessary. +.sp +.LP +The \fBgetservbyname()\fR function searches the database from the beginning and +finds the first entry for which the service name specified by \fIname\fR +matches the \fBs_name\fR member and the protocol name specified by \fIproto\fR +matches the \fBs_proto\fR member, opening a connection to the database if +necessary. If \fIproto\fR is a null pointer, any value of the \fBs_proto\fR +member will be matched. +.sp +.LP +The \fBgetservbyport()\fR function searches the database from the beginning and +finds the first entry for which the port specified by \fIport\fR matches the +\fBs_port\fR member and the protocol name specified by \fIproto\fR matches the +\fBs_proto\fR member, opening a connection to the database if necessary. If +\fIproto\fR is a null pointer, any value of the \fBs_proto\fR member will be +matched. The \fIport\fR argument must be in network byte order. +.sp +.LP +The \fBsetservent()\fR function opens a connection to the database, and sets +the next entry to the first entry. If the \fIstayopen\fR argument is non-zero, +the net database will not be closed after each call to the \fBgetservent()\fR +function, either directly, or indirectly through one of the other +\fBgetserv*()\fR functions. +.sp +.LP +The \fBendservent()\fR function closes the database. +.SH USAGE +.sp +.LP +The \fIport\fR argument of \fBgetservbyport()\fR need not be compatible with +the port values of all address families. +.sp +.LP +The \fBgetservent()\fR, \fBgetservbyname()\fR and \fBgetservbyport()\fR +functions may return pointers to static data, which may be overwritten by +subsequent calls to any of these functions. +.sp +.LP +These functions are generally used with the Internet address family. +.SH RETURN VALUES +.sp +.LP +On successful completion, \fBgetservbyname()\fR, \fBgetservbyport()\fR and +\fBgetservent()\fR return a pointer to a \fBservent\fR structure if the +requested entry was found, and a null pointer if the end of the database was +reached or the requested entry was not found. Otherwise, a null pointer is +returned. +.SH ERRORS +.sp +.LP +No errors are defined. +.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-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBendhostent\fR(3XNET), \fBendprotoent\fR(3XNET), \fBhtonl\fR(3XNET), +\fBinet_addr\fR(3XNET), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/freeaddrinfo.3xnet b/usr/src/man/man3xnet/freeaddrinfo.3xnet new file mode 100644 index 0000000000..36079f87fa --- /dev/null +++ b/usr/src/man/man3xnet/freeaddrinfo.3xnet @@ -0,0 +1,354 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 freeaddrinfo 3XNET "1 Nov 2003" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +freeaddrinfo, getaddrinfo \- get address information +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> +#include <netdb.h> + +\fBvoid\fR \fBfreeaddrinfo\fR(\fBstruct addrinfo *\fR\fIai\fR); +.fi + +.LP +.nf +\fBint\fR \fBgetaddrinfo\fR(\fBconst char *restrict\fR \fInodename\fR, + \fBconst char *restrict\fR \fIservname\fR, \fBconst struct addrinfo *restrict\fR \fIhints\fR, + \fBstruct addrinfo **restrict\fR \fIres\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBfreeaddrinfo()\fR function frees one or more \fBaddrinfo\fR structures +returned by \fBgetaddrinfo()\fR, along with any additional storage associated +with those structures. If the \fBai_next\fR member of the structure is not +null, the entire list of structures is freed. The \fBfreeaddrinfo()\fR function +supports the freeing of arbitrary sublists of an \fBaddrinfo\fR list originally +returned by \fBgetaddrinfo()\fR. +.sp +.LP +The \fBgetaddrinfo()\fR function translates the name of a service location (for +example, a host name) and/or a service name and returns a set of socket +addresses and associated information to be used in creating a socket with which +to address the specified service. +.sp +.LP +The \fInodename\fR and \fIservname\fR arguments are either null pointers or +pointers to null-terminated strings. One or both of these two arguments are +supplied by the application as a non-null pointer. +.sp +.LP +The format of a valid name depends on the address family or families. If a +specific family is not given and the name could be interpreted as valid within +multiple supported families, the implementation attempts to resolve the name in +all supported families and, in absence of errors, one or more results are +returned. +.sp +.LP +If the \fInodename\fR argument is not null, it can be a descriptive name or can +be an address string. If the specified address family is \fBAF_INET\fR, +\fBAF_INET6\fR, or \fBAF_UNSPEC\fR, valid descriptive names include host names. +If the specified address family is \fBAF_INET\fR or \fBAF_UNSPEC\fR, address +strings using Internet standard dot notation as specified in +\fBinet_addr\fR(3XNET) are valid. +.sp +.LP +If the specified address family is \fBAF_INET6\fR or \fBAF_UNSPEC\fR, standard +IPv6 text forms described in \fBinet_ntop\fR(3XNET) are valid. +.sp +.LP +If \fInodename\fR is not null, the requested service location is named by +\fInodename\fR; otherwise, the requested service location is local to the +caller. +.sp +.LP +If \fIservname\fR is null, the call returns network-level addresses for the +specified \fInodename\fR. If \fIservname\fR is not null, it is a +null-terminated character string identifying the requested service. This string +can be either a descriptive name or a numeric representation suitable for use +with the address family or families. If the specified address family is +\fBAF_INET\fR, \fBAF_INET6\fR, or \fBAF_UNSPEC\fR, the service can be specified +as a string specifying a decimal port number. +.sp +.LP +If the \fIhints\fR argument is not null, it refers to a structure containing +input values that can direct the operation by providing options and by limiting +the returned information to a specific socket type, address family and/or +protocol. In this \fIhints\fR structure every member other than \fBai_flags\fR, +\fBai_family\fR , \fBai_socktype\fR, and \fBai_protocol\fR is set to 0 or a +null pointer. A value of \fBAF_UNSPEC\fR for \fBai_family\fR means that the +caller accepts any address family. A value of 0 for \fBai_socktype\fR means +that the caller accepts any socket type. A value of 0 for \fBai_protocol\fR +means that the caller accepts any protocol. If \fIhints\fR is a null pointer, +the behavior is as if it referred to a structure containing the value 0 for the +\fBai_flags\fR, \fBai_socktype\fR, and \fBai_protocol\fR members, and +\fBAF_UNSPEC\fR for the \fBai_family\fR member. +.sp +.LP +The \fBai_flags\fR member to which the \fIhints\fR parameter points is set to 0 +or be the bitwise-inclusive OR of one or more of the values \fBAI_PASSIVE\fR, +\fBAI_CANONNAME\fR, \fBAI_NUMERICHOST\fR, and \fBAI_NUMERICSERV\fR. +.sp +.LP +If the \fBAI_PASSIVE\fR flag is specified, the returned address information is +suitable for use in binding a socket for accepting incoming connections for the +specified service. In this case, if the \fInodename\fR argument is null, then +the IP address portion of the socket address structure is set to +\fBINADDR_ANY\fR for an IPv4 address or \fBIN6ADDR_ANY_INIT\fR for an IPv6 +address. If the \fBAI_PASSIVE\fR flag is not specified, the returned address +information is suitable for a call to \fBconnect\fR(3XNET) (for a +connection-mode protocol) or for a call to \fBconnect()\fR, +\fBsendto\fR(3XNET), or \fBsendmsg\fR(3XNET) (for a connectionless protocol). +In this case, if the \fInodename\fR argument is null, then the IP address +portion of the socket address structure is set to the loopback address. +.sp +.LP +If the \fBAI_CANONNAME\fR flag is specified and the \fInodename\fR argument is +not null, the function attempts to determine the canonical name corresponding +to \fInodename\fR (for example, if \fInodename\fR is an alias or shorthand +notation for a complete name). +.sp +.LP +If the \fBAI_NUMERICHOST\fR flag is specified, then a non-null \fInodename\fR +string supplied is a numeric host address string. Otherwise, an +\fBEAI_NONAME\fR error is returned. This flag prevents any type of name +resolution service (for example, the DNS) from being invoked. +.sp +.LP +If the \fBAI_NUMERICSERV\fR flag is specified, then a non-null \fIservname\fR +string supplied is 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 is 16). The +\fBAI_V4MAPPED\fR flag is ignored unless \fBai_family\fR equals \fBAF_INET6\fR. +If the \fBAI_ALL\fR flag is used with the \fBAI_V4MAPPED\fR flag, then +\fBgetaddrinfo()\fR returns all matching IPv6 and IPv4 addresses. The +\fBAI_ALL\fR flag without the \fBAI_V4MAPPED\fR flag is ignored. +.sp +.LP +The \fBai_socktype\fR member to which argument hints points specifies the +socket type for the service, as defined in \fBsocket\fR(3XNET). If a specific +socket type is not given (for example, a value of 0) and the service name could +be interpreted as valid with multiple supported socket types, the +implementation attempts to resolve the service name for all supported socket +types and, in the absence of errors, all possible results are returned. A +non-zero socket type value limits the returned information to values with the +specified socket type. +.sp +.LP +If the \fBai_family\fR member to which hints points has the value +\fBAF_UNSPEC\fR, addresses are returned for use with any address family that +can be used with the specified \fInodename\fR and/or \fIservname\fR. Otherwise, +addresses are returned for use only with the specified address family. If +\fBai_family\fR is not \fBAF_UNSPEC\fR and \fBai_protocol\fR is not 0, then +addresses are returned for use only with the specified address family and +protocol; the value of \fBai_protocol\fR is interpreted as in a call to the +\fBsocket()\fR function with the corresponding values of \fBai_family\fR and +\fBai_protocol\fR. +.SH RETURN VALUES +.sp +.LP +A 0 return value for \fBgetaddrinfo()\fR indicates successful completion; a +non-zero return value indicates failure. The possible values for the failures +are listed in the ERRORS section. +.sp +.LP +Upon successful return of \fBgetaddrinfo()\fR, the location to which res points +refers to a linked list of \fBaddrinfo\fR structures, each of which specifies a +socket address and information for use in creating a socket with which to use +that socket address. The list includes at least one \fBaddrinfo\fR structure. +The \fBai_next\fR member of each structure contains a pointer to the next +structure on the list, or a null pointer if it is the last structure on the +list. Each structure on the list includes values for use with a call to the +socket function, and a socket address for use with the connect function or, if +the \fBAI_PASSIVE\fR flag was specified, for use with the \fBbind\fR(3XNET) +function. The \fBai_family\fR , \fBai_socktype\fR, and \fBai_protocol\fR +members are usable as the arguments to the \fBsocket()\fR function to create a +socket suitable for use with the returned address. The \fBai_addr\fR and +\fBai_addrlen\fR members are usable as the arguments to the \fBconnect()\fR or +\fBbind()\fR functions with such a socket, according to the \fBAI_PASSIVE\fR +flag. +.sp +.LP +If \fInodename\fR is not null, and if requested by the \fBAI_CANONNAME\fR flag, +the \fBai_canonname\fR member of the first returned \fBaddrinfo\fR structure +points to a null-terminated string containing the canonical name corresponding +to the input \fInodename\fR. If the canonical name is not available, then +\fBai_canonname\fR refers to the \fInodename\fR argument or a string with the +same contents. The contents of the \fBai_flags\fR member of the returned +structures are undefined. +.sp +.LP +All members in socket address structures returned by \fBgetaddrinfo()\fR that +are not filled in through an explicit argument (for example, +\fBsin6_flowinfo\fR) are set to 0, making it easier to compare socket address +structures. +.SH ERRORS +.sp +.LP +The \fBgetaddrinfo()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAI_AGAIN\fR\fR +.ad +.RS 16n +.rt +The name could not be resolved at this time. Future attempts might succeed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_BADFLAGS\fR\fR +.ad +.RS 16n +.rt +The \fBai_flags\fR member of the \fBaddrinfo\fR structure had an invalid value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_FAIL\fR\fR +.ad +.RS 16n +.rt +A non-recoverable error occurred when attempting to resolve the name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_FAMILY\fR\fR +.ad +.RS 16n +.rt +The address family was not recognized. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_MEMORY\fR\fR +.ad +.RS 16n +.rt +There was a memory allocation failure when trying to allocate storage for the +return value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_NONAME\fR\fR +.ad +.RS 16n +.rt +he name does not resolve for the supplied parameters. Neither \fInodename\fR +nor \fIservname\fR were supplied. At least one of these must be supplied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_SERVICE\fR\fR +.ad +.RS 16n +.rt +The service passed was not recognized for the specified socket type. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_SOCKTYPE\fR\fR +.ad +.RS 16n +.rt +The intended socket type was not recognized. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_SYSTEM\fR\fR +.ad +.RS 16n +.rt +A system error occurred. The error code can be found in \fBerrno\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_OVERFLOW\fR\fR +.ad +.RS 16n +.rt +An argument buffer overflowed. +.RE + +.SH USAGE +.sp +.LP +If the caller handles only TCP and not UDP, for example, then the +\fBai_protocol\fR member of the \fIhints\fR structure should be set to +\fBIPPROTO_TCP\fR when \fBgetaddrinfo()\fR is called. +.sp +.LP +If the caller handles only IPv4 and not IPv6, then the \fBai_family\fR member +of the \fIhints\fR structure should be set to \fBAF_INET\fR when +\fBgetaddrinfo()\fR is called. +.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-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBconnect\fR(3XNET), \fBgai_strerror\fR(3XNET), \fBgethostbyname\fR(3XNET), +\fBgetnameinfo\fR(3XNET), \fBgetservbyname\fR(3XNET), \fBinet_addr\fR(3XNET), +\fBinet_ntop\fR(3XNET), \fBsocket\fR(3XNET), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/gai_strerror.3xnet b/usr/src/man/man3xnet/gai_strerror.3xnet new file mode 100644 index 0000000000..948afb09dd --- /dev/null +++ b/usr/src/man/man3xnet/gai_strerror.3xnet @@ -0,0 +1,169 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 gai_strerror 3XNET "1 Dec 2003" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +gai_strerror \- address and name information error description +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <netdb.h> + +\fBconst char *\fR\fBgai_strerror\fR(\fBint\fR \fIecode\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgai_strerror()\fR function returns a text string describing an error +value for the \fBgetaddrinfo\fR(3XNET) and \fBgetnameinfo\fR(3XNET) functions +listed in the <\fBnetdb.h\fR> header. +.sp +.LP +When the \fIecode\fR argument is one of the following values listed in the +<\fBnetdb.h\fR> header: +.sp +.ne 2 +.mk +.na +\fB\fBEAI_AGAIN\fR\fR +.ad +.RS 16n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_BADFLAGS\fR\fR +.ad +.RS 16n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_FAIL\fR\fR +.ad +.RS 16n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_FAMILY\fR\fR +.ad +.RS 16n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_MEMORY\fR\fR +.ad +.RS 16n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_NONAME\fR\fR +.ad +.RS 16n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_SERVICE\fR\fR +.ad +.RS 16n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_SOCKTYPE\fR\fR +.ad +.RS 16n +.rt + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_SYSTEM\fR\fR +.ad +.RS 16n +.rt + +.RE + +.sp +.LP +the function return value points to a string describing the error. If the +argument is not one of those values, the function returns a pointer to a string +whose contents indicate an unknown error. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBgai_strerror()\fR returns a pointer to a string +describing the error value. +.SH ERRORS +.sp +.LP +No errors are defined. +.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-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetaddrinfo\fR(3XNET), \fBgetnameinfo\fR(3XNET), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/gethostname.3xnet b/usr/src/man/man3xnet/gethostname.3xnet new file mode 100644 index 0000000000..f2d192fd29 --- /dev/null +++ b/usr/src/man/man3xnet/gethostname.3xnet @@ -0,0 +1,64 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 gethostname 3XNET "10 Jun 2002" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +gethostname \- get name of current host +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <unistd.h> + +\fBint\fR \fBgethostname\fR(\fBchar *\fR\fIname\fR, \fBsize_t\fR \fInamelen\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgethostname()\fR function returns the standard host name for the current +machine. The \fInamelen\fR argument specifies the size of the array pointed to +by the \fIname\fR argument. The returned name is null-terminated, except that +if \fInamelen\fR is an insufficient length to hold the host name, then the +returned name is truncated and it is unspecified whether the returned name is +null-terminated. +.sp +.LP +Host names are limited to 255 bytes. +.SH RETURN VALUES +.sp +.LP +On successful completion, 0 is returned. Otherwise, -1 is returned. +.SH ERRORS +.sp +.LP +No errors are defined. +.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-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBuname\fR(1), \fBgethostid\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/getnameinfo.3xnet b/usr/src/man/man3xnet/getnameinfo.3xnet new file mode 100644 index 0000000000..99b3ec6466 --- /dev/null +++ b/usr/src/man/man3xnet/getnameinfo.3xnet @@ -0,0 +1,241 @@ +'\" te +.\" Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 getnameinfo 3XNET "1 Nov 2003" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +getnameinfo \- get name information +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> +#include <netdb.h> + +\fBint\fR \fBgetnameinfo\fR(\fBconst struct sockaddr *restrict\fR \fIsa\fR, \fBsocklen_t\fR \fIsalen\fR, + \fBchar *restrict\fR \fInode\fR, \fBsocklen_t\fR \fInodelen\fR, \fBchar *restrict\fR \fIservice\fR, + \fBsocklen_t\fR \fIservicelen\fR, \fBunsigned\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetnameinfo()\fR function translates a socket address to a node name and +service location, all of which are defined as in \fBgetaddrinfo\fR(3XNET). +.sp +.LP +The \fIsa\fR argument points to a socket address structure to be translated. If +the socket address structure contains an IPv4-mapped IPv6 address or an +IPv4-compatible IPv6 address, the implementation extracts the embedded IPv4 +address and lookup the node name for that IPv4 address. +.sp +.LP +If the \fInode\fR argument is non-\fINULL\fR and the nodelen argument is +non-zero, then the \fInode\fR argument points to a buffer able to contain up to +\fInodelen\fR characters that receives the node name as a null-terminated +string. If the \fInode\fR argument is \fINULL\fR or the \fInodelen\fR argument +is zero, the node name is not returned. If the node's name cannot be located, +the numeric form of the node's address is returned instead of its name. +.sp +.LP +If the \fIservice\fR argument is non-\fINULL\fR and the \fIservicelen\fR +argument is non-zero, then the \fIservice\fR argument points to a buffer able +to contain up to \fIservicelen\fR bytes that receives the service name as a +null-terminated string. If the \fIservice\fR argument is \fINULL\fR or the +\fIservicelen\fR argument is zero, the service name is not returned. If the +service's name cannot be located, the numeric form of the service address (for +example, its port number) is returned instead of its name. +.sp +.LP +The \fIflags\fR argument is a flag that changes the default actions of the +function. By default the fully-qualified domain name (FQDN) for the host is +returned, but: +.RS +4 +.TP +.ie t \(bu +.el o +If the flag bit \fBNI_NOFQDN\fR is set, only the node name portion of the FQDN +is returned for local hosts. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the flag bit \fBNI_NUMERICHOST\fR is set, the numeric form of the host's +address is returned instead of its name, under all circumstances. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the flag bit \fBNI_NAMEREQD\fR is set, an error is returned if the host's +name cannot be located. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +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, under +all circumstances. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the flag bit \fBNI_DGRAM\fR is set, this indicates that the service is a +datagram service (\fBSOCK_DGRAM\fR). The default behavior assumes that the +service is a stream service (\fBSOCK_STREAM\fR). +.RE +.SH RETURN VALUES +.sp +.LP +A 0 return value for \fBgetnameinfo()\fR indicates successful completion; a +non-zero return value indicates failure. The possible values for the failures +are listed in the ERRORS section. +.sp +.LP +Upon successful completion, \fBgetnameinfo()\fR returns the node and service +names, if requested, in the buffers provided. The returned names are always +null-terminated strings. +.SH ERRORS +.sp +.LP +The \fBgetnameinfo()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAI_AGAIN\fR\fR +.ad +.RS 16n +.rt +The name could not be resolved at this time. Future attempts might succeed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_BADFLAGS\fR\fR +.ad +.RS 16n +.rt +The \fIflags\fR argument had an invalid value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_FAIL\fR\fR +.ad +.RS 16n +.rt +A non-recoverable error occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_FAMILY\fR\fR +.ad +.RS 16n +.rt +The address family was not recognized or the address length was invalid for the +specified family. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_MEMORY\fR\fR +.ad +.RS 16n +.rt +There was a memory allocation failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_NONAME\fR\fR +.ad +.RS 16n +.rt +The name does not resolve for the supplied parameters. \fBNI_NAMEREQD\fR +is set and the host's name cannot be located, or both \fInodename\fR and +\fIservname\fR were \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAI_SYSTEM\fR\fR +.ad +.RS 16n +.rt +A system error occurred. The error code can be found in \fBerrno\fR. +.RE + +.SH USAGE +.sp +.LP +If the returned values are to be used as part of any further name resolution +(for example, passed to \fBgetaddrinfo()\fR), applications should provide +buffers large enough to store any result possible on the system. +.sp +.LP +Given the IPv4-mapped IPv6 address "::ffff:1.2.3.4", the implementation +performs a lookup as if the socket address structure contains the IPv4 address +"1.2.3.4". +.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-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgai_strerror\fR(3XNET), \fBgetaddrinfo\fR(3XNET), +\fBgetservbyname\fR(3XNET), \fBsocket\fR(3XNET), \fBattributes\fR(5), +\fBstandards\fR(5) +.SH NOTES +.sp +.LP +The IPv6 unspecified address ("::") and the IPv6 loopback address ("::1") are +not IPv4-compatible addresses. If the address is the IPv6 unspecified address +("::"), a lookup is not performed, and the \fBEAI_NONAME\fR error is returned. +.sp +.LP +The two \fBNI_NUMERIC\fR\fIxxx\fR flags are required to support the \fB-n\fR +flag that many commands provide. +.sp +.LP +The \fBNI_DGRAM\fR flag is required for the few \fBAF_INET\fR and +\fBAF_INET6\fR port numbers (for example, [512,514]) that represent different +services for UDP and TCP. diff --git a/usr/src/man/man3xnet/getpeername.3xnet b/usr/src/man/man3xnet/getpeername.3xnet new file mode 100644 index 0000000000..f11deeec9a --- /dev/null +++ b/usr/src/man/man3xnet/getpeername.3xnet @@ -0,0 +1,164 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 3XNET "10 Jun 2002" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +getpeername \- get the name of the peer socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> + +\fBint\fR \fBgetpeername\fR(\fBint\fR \fIsocket\fR, \fBstruct sockaddr *restrict\fR \fIaddress\fR, + \fBsocklen_t *restrict\fR \fIaddress_len\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetpeername()\fR function retrieves the peer address of the specified +socket, stores this address in the \fBsockaddr\fR structure pointed to by the +\fIaddress\fR argument, and stores the length of this address in the object +pointed to by the \fIaddress_len\fR argument. +.sp +.LP +If the actual length of the address is greater than the length of the supplied +\fBsockaddr\fR structure, the stored address will be truncated. +.sp +.LP +If the protocol permits connections by unbound clients, and the peer is not +bound, then the value stored in the object pointed to by \fIaddress\fR is +unspecified. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, 0 is returned. Otherwise, \(mi1 is returned and +\fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBgetpeername()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 14n +.rt +The \fIsocket\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 14n +.rt +The \fIaddress\fR or \fIaddress_len\fR parameter can not be accessed or +written. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 14n +.rt +The socket has been shut down. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTCONN\fR\fR +.ad +.RS 14n +.rt +The socket is not connected or otherwise has not had the peer prespecified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 14n +.rt +The \fIsocket\fR argument does not refer to a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 14n +.rt +The operation is not supported for the socket protocol. +.RE + +.sp +.LP +The \fBgetpeername()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 11n +.rt +Insufficient resources were available in the system to complete the call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 11n +.rt +There were insufficient STREAMS resources available for the operation to +complete. +.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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBaccept\fR(3XNET), \fBbind\fR(3XNET), \fBgetsockname\fR(3XNET), +\fBsocket\fR(3XNET), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/getsockname.3xnet b/usr/src/man/man3xnet/getsockname.3xnet new file mode 100644 index 0000000000..5cafb17832 --- /dev/null +++ b/usr/src/man/man3xnet/getsockname.3xnet @@ -0,0 +1,154 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 3XNET "10 Jun 2002" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +getsockname \- get the socket name +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> + +\fBint\fR \fBgetsockname\fR(\fBint\fR \fIsocket\fR, \fBstruct sockaddr *restrict\fR \fIaddress\fR, + \fBsocklen_t *restrict\fR \fIaddress_len\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetsockname()\fR function retrieves the locally-bound name of the +specified socket, stores this address in the \fBsockaddr\fR structure pointed +to by the \fIaddress\fR argument, and stores the length of this address in the +object pointed to by the \fIaddress_len\fR argument. +.sp +.LP +If the actual length of the address is greater than the length of the supplied +\fBsockaddr\fR structure, the stored address will be truncated. +.sp +.LP +If the socket has not been bound to a local name, the value stored in the +object pointed to by \fIaddress\fR is unspecified. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, 0 is returned, the \fIaddress\fR argument points to +the address of the socket, and the \fIaddress_len\fR argument points to the +length of the address. Otherwise, \(mi1 is returned and \fBerrno\fR is set to +indicate the error. +.SH ERRORS +.sp +.LP +The \fBgetsockname()\fR function will fail: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 14n +.rt +The \fIsocket\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 14n +.rt +The \fIaddress\fR or \fIaddress_len\fR parameter can not be accessed or +written. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 14n +.rt +The \fIsocket\fR argument does not refer to a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 14n +.rt +The operation is not supported for this socket's protocol. +.RE + +.sp +.LP +The \fBgetsockname()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The socket has been shut down. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 11n +.rt +Insufficient resources were available in the system to complete the call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 11n +.rt +There were insufficient STREAMS resources available for the operation to +complete. +.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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBaccept\fR(3XNET), \fBbind\fR(3XNET), \fBgetpeername\fR(3XNET), +\fBsocket\fR(3XNET) \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/getsockopt.3xnet b/usr/src/man/man3xnet/getsockopt.3xnet new file mode 100644 index 0000000000..dd3528b654 --- /dev/null +++ b/usr/src/man/man3xnet/getsockopt.3xnet @@ -0,0 +1,426 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 3XNET "21 Jan 2007" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +getsockopt \- get the socket options +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lxnet\fR [ \fIlibrary\fR... ] +#include <sys/socket.h> + +\fBint\fR \fBgetsockopt\fR(\fBint\fR \fIsocket\fR, \fBint\fR \fIlevel\fR, \fBint\fR \fIoption_name\fR, + \fBvoid *restrict\fR \fIoption_value\fR, \fBsocklen_t *restrict\fR \fIoption_len\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgetsockopt()\fR function retrieves the value for the option specified by +the \fIoption_name\fR argument for the socket specified by the \fIsocket\fR +argument. If the size of the option value is greater than \fIoption_len\fR, the +value stored in the object pointed to by the \fIoption_value\fR argument will +be silently truncated. Otherwise, the object pointed to by the \fIoption_len\fR +argument will be modified to indicate the actual length of the value. +.sp +.LP +The \fIlevel\fR argument specifies the protocol level at which the option +resides. To retrieve options at the socket level, specify the \fIlevel\fR +argument as \fBSOL_SOCKET\fR. To retrieve options at other levels, 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 +(Transport Control Protocol), set \fIlevel\fR to the protocol number of +\fBTCP\fR, as defined in the <\fBnetinet/in.h\fR> header, or as determined by +using \fBgetprotobyname\fR(3XNET) function. +.sp +.LP +The socket in use might require the process to have appropriate privileges to +use the \fBgetsockopt()\fR function. +.sp +.LP +The \fIoption_name\fR argument specifies a single option to be retrieved. It +can be one of the following values defined in \fB<sys/socket.h>\fR: +.sp +.ne 2 +.mk +.na +\fB\fBSO_DEBUG\fR\fR +.ad +.RS 17n +.rt +Reports whether debugging information is being recorded. This option stores an +\fBint\fR value. This is a boolean option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_ACCEPTCONN\fR\fR +.ad +.RS 17n +.rt +Reports whether socket listening is enabled. This option stores an \fBint\fR +value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_BROADCAST\fR\fR +.ad +.RS 17n +.rt +Reports whether transmission of broadcast messages is supported, if this is +supported by the protocol. This option stores an \fBint\fR value. This is a +boolean option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_REUSEADDR\fR\fR +.ad +.RS 17n +.rt +Reports whether the rules used in validating addresses supplied to +\fBbind\fR(3XNET) should allow reuse of local addresses, if this is supported +by the protocol. This option stores an \fBint\fR value. This is a boolean +option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_KEEPALIVE\fR\fR +.ad +.RS 17n +.rt +Reports whether connections are kept active with periodic transmission of +messages, if this is supported by the protocol. +.sp +If the connected socket fails to respond to these messages, the connection is +broken and threads writing to that socket are notified with a \fBSIGPIPE\fR +signal. This option stores an \fBint\fR value. +.sp +This is a boolean option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_LINGER\fR\fR +.ad +.RS 17n +.rt +Reports whether the socket lingers on \fBclose\fR(2) if data is present. If +\fBSO_LINGER\fR is set, the system blocks the process during \fBclose\fR(2) +until it can transmit the data or until the end of the interval indicated by +the \fBl_linger\fR member, whichever comes first. If \fBSO_LINGER\fR is not +specified, and \fBclose\fR(2) is issued, the system handles the call in a way +that allows the process to continue as quickly as possible. This option stores +a \fBlinger\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_OOBINLINE\fR\fR +.ad +.RS 17n +.rt +Reports whether the socket leaves received out-of-band data (data marked +urgent) in line. This option stores an \fBint\fR value. This is a boolean +option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_SNDBUF\fR\fR +.ad +.RS 17n +.rt +Reports send buffer size information. This option stores an \fBint\fR value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_RCVBUF\fR\fR +.ad +.RS 17n +.rt +Reports receive buffer size information. This option stores an \fBint\fR value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_ERROR\fR\fR +.ad +.RS 17n +.rt +Reports information about error status and clears it. This option stores an +\fBint\fR value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_TYPE\fR\fR +.ad +.RS 17n +.rt +Reports the socket type. This option stores an \fBint\fR value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_DONTROUTE\fR\fR +.ad +.RS 17n +.rt +Reports whether outgoing messages bypass the standard routing facilities. The +destination must be on a directly-connected network, and messages are directed +to the appropriate network interface according to the destination address. The +effect, if any, of this option depends on what protocol is in use. This option +stores an \fBint\fR value. This is a boolean option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_MAC_EXEMPT\fR\fR +.ad +.RS 17n +.rt +Gets the mandatory access control status of the socket. A socket that has this +option enabled can communicate with an unlabeled peer if the socket 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. \fB\fR\fBSO_MAC_EXEMPT\fR is a boolean option that is +available only when the system is configured with Trusted Extensions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_ALLZONES\fR\fR +.ad +.RS 17n +.rt +Bypasses zone boundaries (privileged). This option stores an \fBint\fR value. +This is a boolean option. +.sp +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). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_DOMAIN\fR\fR +.ad +.RS 17n +.rt +get the domain used in the socket (get only) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_PROTOTYPE\fR\fR +.ad +.RS 17n +.rt +for socket in domains \fBAF_INET\fR and \fBAF_INET6\fR, get the underlying +protocol number used in the socket. For socket in domain \fBAF_ROUTE\fR, get +the address family used in the socket. +.RE + +.sp +.LP +For boolean options, a zero value indicates that the option is disabled and a +non-zero value indicates that the option is enabled. +.sp +.LP +Options at other protocol levels vary in format and name. +.sp +.LP +The socket in use may require the process to have appropriate privileges to use +the \fBgetsockopt()\fR function. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBgetsockopt()\fR returns \fB0\fR. Otherwise, +\fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBgetsockopt()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 15n +.rt +The \fIsocket\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 15n +.rt +The \fIoption_value\fR or \fIoption_len\fR parameter can not be accessed or +written. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 15n +.rt +The specified option is invalid at the specified socket level. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOPROTOOPT\fR\fR +.ad +.RS 15n +.rt +The option is not supported by the protocol. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 15n +.rt +The \fIsocket\fR argument does not refer to a socket. +.RE + +.sp +.LP +The \fBgetsockopt()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 11n +.rt +The calling process does not have the appropriate privileges. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The socket has been shut down. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 11n +.rt +Insufficient resources are available in the system to complete the call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 11n +.rt +There were insufficient STREAMS resources available for the operation to +complete. +.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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBbind\fR(3XNET), \fBendprotoent\fR(3XNET), +\fBsetsockopt\fR(3XNET), \fBsocket\fR(3XNET), \fBattributes\fR, +\fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/htonl.3xnet b/usr/src/man/man3xnet/htonl.3xnet new file mode 100644 index 0000000000..da3eec9086 --- /dev/null +++ b/usr/src/man/man3xnet/htonl.3xnet @@ -0,0 +1,92 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 htonl 3XNET "10 Jun 2002" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +htonl, htons, ntohl, ntohs \- convert values between host and network byte +order +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <arpa/inet.h> + +\fBuint32_t\fR \fBhtonl\fR(\fBuint32_t\fR \fIhostlong\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 +\fBuint16_t\fR \fBntohs\fR(\fBuint16_t\fR \fI netshort\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions convert 16-bit and 32-bit quantities between network byte order +and host byte order. +.sp +.LP +The \fBuint32_t\fR and \fBuint16_t\fR types are made available by inclusion +of \fB<inttypes.h>\fR\&. +.SH USAGE +.sp +.LP +These functions are most often used in conjunction with Internet addresses and +ports as returned by \fBgethostent\fR(3XNET) and \fBgetservent\fR(3XNET). +.sp +.LP +On some architectures these functions are defined as macros that expand to the +value of their argument. +.SH RETURN VALUES +.sp +.LP +The \fBhtonl()\fR and \fBhtons()\fR functions return the argument value +converted from host to network byte order. +.sp +.LP +The \fBntohl()\fR and \fBntohs()\fR functions return the argument value +converted from network to host byte order. +.SH ERRORS +.sp +.LP +No errors are defined. +.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-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBendhostent\fR(3XNET), \fBendservent\fR(3XNET), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/if_nametoindex.3xnet b/usr/src/man/man3xnet/if_nametoindex.3xnet new file mode 100644 index 0000000000..ea7c233c5f --- /dev/null +++ b/usr/src/man/man3xnet/if_nametoindex.3xnet @@ -0,0 +1,185 @@ +'\" te +.\" Copyright (C) 2003, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH if_nametoindex 3XNET "14 Dec 2003" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +if_nametoindex, if_indextoname, if_nameindex, if_freenameindex \- functions to +map Internet Protocol network interface names and interface indexes +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lxnet\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 +.LP +These functions support the following 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\fB*if_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; /* null terminated name: "eri0", ... */ +}; +.fi +.in -2 + +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 +_ +Interface StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBifconfig\fR(1M), \fBif_nametoindex\fR(3SOCKET), \fBattributes\fR(5), +\fBstandards\fR(5), \fBif\fR(7P) diff --git a/usr/src/man/man3xnet/inet_addr.3xnet b/usr/src/man/man3xnet/inet_addr.3xnet new file mode 100644 index 0000000000..6a271627c1 --- /dev/null +++ b/usr/src/man/man3xnet/inet_addr.3xnet @@ -0,0 +1,196 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Portions Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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_addr 3XNET "10 Jun 2002" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +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-lxnet\fR [ \fIlibrary\fR ... ] +#include <arpa/inet.h> + +\fBin_addr_t\fR \fBinet_addr\fR(\fBconst char *\fR\fIcp\fR); +.fi + +.LP +.nf +\fBin_addr_t\fR \fBinet_lnaof\fR(\fBstruct in_addr\fR \fIin\fR); +.fi + +.LP +.nf +\fBstruct in_addr\fR \fBinet_makeaddr\fR(\fBin_addr_t\fR \fInet\fR, \fBin_addr_t\fR \fIlna\fR); +.fi + +.LP +.nf +\fBin_addr_t\fR \fBinet_netof\fR(\fBstruct in_addr\fR \fIin\fR); +.fi + +.LP +.nf +\fBin_addr_t\fR \fBinet_network\fR(\fBconst char *\fR\fIcp\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBinet_ntoa\fR(\fBstruct in_addr\fR \fIin\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBinet_addr()\fR function converts the string pointed to by \fIcp\fR, in +the Internet standard dot notation, to an integer value suitable for use as an +Internet address. +.sp +.LP +The \fBinet_lnaof()\fR function takes an Internet host address specified by +\fIin\fR and extracts the local network address part, in host byte order. +.sp +.LP +The \fBinet_makeaddr()\fR function takes the Internet network number specified +by \fInet\fR and the local network address specified by \fIlna\fR, both in host +byte order, and constructs an Internet address from them. +.sp +.LP +The \fBinet_netof()\fR function takes an Internet host address specified by +\fIin\fR and extracts the network number part, in host byte order. +.sp +.LP +The \fBinet_network()\fR function converts the string pointed to by \fIcp\fR, +in the Internet standard dot notation, to an integer value suitable for use as +an Internet network number. +.sp +.LP +The \fBinet_ntoa()\fR function converts the Internet host address specified by +\fIin\fR to a string in the Internet standard dot notation. +.sp +.LP +All Internet addresses are returned in network order (bytes ordered from left +to right). +.sp +.LP +Values specified using dot notation take one of the following forms: +.sp +.ne 2 +.mk +.na +\fB\fBa.b.c.d\fR\fR +.ad +.RS 11n +.rt +When four parts are specified, each is interpreted as a byte of data and +assigned, from left to right, to the four bytes of an Internet address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBa.b.c\fR\fR +.ad +.RS 11n +.rt +When a three-part address is specified, the last part is interpreted as a +16-bit quantity and placed in the rightmost two bytes of the network address. +This makes the three-part address format convenient for specifying Class B +network addresses as \fB128.\fR\fInet\fR.\fIhost\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBa.b\fR\fR +.ad +.RS 11n +.rt +When a two-part address is supplied, the last part is interpreted as a 24-bit +quantity and placed in the rightmost three bytes of the network address. This +makes the two-part address format convenient for specifying Class A network +addresses as \fInet\fR\fB\&.\fR\fIhost\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBa\fR\fR +.ad +.RS 11n +.rt +When only one part is given, the value is stored directly in the network +address without any byte rearrangement. +.RE + +.sp +.LP +All numbers supplied as parts in dot notation may be decimal, octal, or +hexadecimal, that is, a leading 0x or 0X implies hexadecimal, as specified in +the \fIISO C\fR standard; otherwise, a leading 0 implies octal; otherwise, the +number is interpreted as decimal. +.SH USAGE +.sp +.LP +The return value of \fBinet_ntoa()\fR may point to static data that may be +overwritten by subsequent calls to \fBinet_ntoa()\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBinet_addr()\fR returns the Internet address. +Otherwise, it returns (\fBin_addr_t\fR)(\(mi1). +.sp +.LP +Upon successful completion, \fBinet_network()\fR returns the converted Internet +network number. Otherwise, it returns (\fBin_addr_t\fR)(\(mi1). +.sp +.LP +The \fBinet_makeaddr()\fR function returns the constructed Internet address. +.sp +.LP +The \fBinet_lnaof()\fR function returns the local network address part. +.sp +.LP +The \fBinet_netof()\fR function returns the network number. +.sp +.LP +The \fBinet_ntoa()\fR function returns a pointer to the network address in +Internet-standard dot notation. +.SH ERRORS +.sp +.LP +No errors are defined. +.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-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBendhostent\fR(3XNET), \fBendnetent\fR(3XNET), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/inet_ntop.3xnet b/usr/src/man/man3xnet/inet_ntop.3xnet new file mode 100644 index 0000000000..f44995dd32 --- /dev/null +++ b/usr/src/man/man3xnet/inet_ntop.3xnet @@ -0,0 +1,161 @@ +'\" te +.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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_ntop 3XNET "1 Nov 2003" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +inet_ntop, inet_pton \- convert IPv4 and IPv6 addresses between binary and text +form +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <arpa/inet.h> + +\fBconst char *\fR\fBinet_ntop\fR(\fBint\fR \fIaf\fR, \fBconst void *restrict\fR \fIsrc\fR, + \fBchar *restrict\fR \fIdst\fR, \fBsocklen_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBint\fR \fBinet_pton\fR(\fBint\fR \fIaf\fR, \fBconst char *restrict\fR \fIsrc\fR, \fIdst\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBinet_ntop()\fR function converts a numeric address into a text string +suitable for presentation. The \fIaf\fR argument specifies the family of the +address. This can be \fBAF_INET\fR or \fBAF_INET6\fR. The \fIsrc\fR argument +points to a buffer holding an IPv4 address if the \fIaf\fR argument is +\fBAF_INET\fR, or an IPv6 address if the \fIaf\fR argument is \fBAF_INET6\fR. +The \fIdst\fR argument points to a buffer where the function stores the +resulting text string; it cannot be \fINULL\fR. The \fIsize\fR argument +specifies the size of this buffer, which must be large enough to hold the text +string (\fBINET_ADDRSTRLEN\fR characters for IPv4, \fBINET6_ADDRSTRLEN\fR +characters for IPv6). +.sp +.LP +The \fBinet_pton()\fR function converts an address in its standard text +presentation form into its numeric binary form. The \fIaf\fR argument specifies +the family of the address. The \fBAF_INET\fR and \fBAF_INET6\fR address +families are supported. The \fIsrc\fR argument points to the string being +passed in. The \fIdst\fR argument points to a buffer into which the function +stores the numeric address; this must be large enough to hold the numeric +address (32 bits for \fBAF_INET\fR, 128 bits for \fBAF_INET6\fR). +.sp +.LP +If the \fIaf\fR argument of \fBinet_pton()\fR is \fBAF_INET\fR, the \fIsrc\fR +string is in the standard IPv4 dotted-decimal form: +.sp +.in +2 +.nf +ddd.ddd.ddd.ddd +.fi +.in -2 + +.sp +.LP +where "\fBddd\fR"is a one to three digit decimal number between 0 and 255 (see +\fBinet_addr\fR(3XNET)). The \fBinet_pton()\fR function does not accept other +formats (such as the octal numbers, hexadecimal numbers, and fewer than four +numbers that \fBinet_addr()\fR accepts). +.sp +.LP +If the \fIaf\fR argument of \fBinet_pton()\fR is \fBAF_INET6\fR, the \fIsrc\fR +string is in one of the following standard IPv6 text forms: +.RS +4 +.TP +1. +The preferred form is "\fBx:x:x:x:x:x:x:x\fR", where the '\fBx\fR's are the +hexadecimal values of the eight 16-bit pieces of the address. Leading zeros in +individual fields can be omitted, but there must be at least one numeral in +every field. +.RE +.RS +4 +.TP +2. +A string of contiguous zero fields in the preferred form can be shown as +"\fB::\fR". The "\fB::\fR" can only appear once in an address. Unspecified +addresses ("\fB0:0:0:0:0:0:0:0\fR") can be represented simply as "\fB::\fR". +.RE +.RS +4 +.TP +3. +A third form that is sometimes more convenient when dealing with a mixed +environment of IPv4 and IPv6 nodes is "\fBx:x:x:x:x:x:d.d.d.d\fR", where +the '\fBx\fR's are the hexadecimal values of the six high-order 16-bit pieces of +the address, and the '\fBd\fR's are the decimal values of the four low-order +8-bit pieces of the address (standard IPv4 representation). +.RE +.sp +.LP +A more extensive description of the standard representations of IPv6 addresses +can be found in RFC 2373. +.SH RETURN VALUES +.sp +.LP +The \fBinet_ntop()\fR function returns a pointer to the buffer containing the +text string if the conversion succeeds. Otherwise it returns \fINULL\fR and +sets \fBerrno\fR to indicate the error. +.sp +.LP +The \fBinet_pton()\fR function returns 1 if the conversion succeeds, with the +address pointed to by \fIdst\fR in network byte order. It returns 0 if the +input is not a valid IPv4 dotted-decimal string or a valid IPv6 address string. +It returns \(mi1 and sets \fBerrno\fR to \fBEAFNOSUPPORT\fR if the \fIaf\fR +argument is unknown. +.SH ERRORS +.sp +.LP +The \fBinet_ntop()\fR and \fBinet_pton()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAFNOSUPPORT\fR\fR +.ad +.RS 16n +.rt +The \fIaf\fR argument is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSPC\fR\fR +.ad +.RS 16n +.rt +The size of the \fBinet_ntop()\fR result buffer is inadequate. +.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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBinet_addr\fR(3XNET), \fBattributes\fR(5) diff --git a/usr/src/man/man3xnet/listen.3xnet b/usr/src/man/man3xnet/listen.3xnet new file mode 100644 index 0000000000..ca7bad4058 --- /dev/null +++ b/usr/src/man/man3xnet/listen.3xnet @@ -0,0 +1,173 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 3XNET "10 Jun 2002" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +listen \- listen for socket connections and limit the queue of incoming +connections +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> + +\fBint\fR \fBlisten\fR(\fBint\fR \fIsocket\fR, \fBint\fR \fIbacklog\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBlisten()\fR function marks a connection-mode socket, specified by the +\fIsocket\fR argument, as accepting connections, and limits the number of +outstanding connections in the socket's listen queue to the value specified by +the \fIbacklog\fR argument. +.sp +.LP +If \fBlisten()\fR is called with a \fIbacklog\fR argument value that is less +than 0, the function sets the length of the socket's listen queue to 0. +.sp +.LP +The implementation may include incomplete connections in the queue subject to +the queue limit. The implementation may also increase the specified queue limit +internally if it includes such incomplete connections in the queue subject to +this limit. +.sp +.LP +Implementations may limit the length of the socket's listen queue. If +\fIbacklog\fR exceeds the implementation-dependent maximum queue length, the +length of the socket's listen queue will be set to the maximum supported value. +.sp +.LP +The socket in use may require the process to have appropriate privileges to use +the \fBlisten()\fR function. +.SH RETURN VALUES +.sp +.LP +Upon successful completions, \fBlisten()\fR returns 0. Otherwise, \(mi1 is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBlisten()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 16n +.rt +The \fIsocket\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEDESTADDRREQ\fR\fR +.ad +.RS 16n +.rt +The socket is not bound to a local address, and the protocol does not support +listening on an unbound socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The \fIsocket\fR is already connected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 16n +.rt +The \fIsocket\fR argument does not refer to a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 16n +.rt +The socket protocol does not support \fBlisten()\fR. +.RE + +.sp +.LP +The \fBlisten()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 11n +.rt +The calling process does not have the appropriate privileges. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The \fIsocket\fR has been shut down. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 11n +.rt +Insufficient resources are available in the system to complete the call. +.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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBaccept\fR(3XNET), \fBconnect\fR(3XNET), \fBsocket\fR(3XNET), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/recv.3xnet b/usr/src/man/man3xnet/recv.3xnet new file mode 100644 index 0000000000..271c7a8cc7 --- /dev/null +++ b/usr/src/man/man3xnet/recv.3xnet @@ -0,0 +1,346 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 3XNET "10 Jun 2002" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +recv \- receive a message from a connected socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> + +\fBssize_t\fR \fBrecv\fR(\fBint\fR \fIsocket\fR, \fBvoid *\fR\fIbuffer\fR, \fBsize_t\fR \fIlength\fR, \fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBrecv()\fR function receives a message from a connection-mode or +connectionless-mode socket. It is normally used with connected sockets because +it does not permit the application to retrieve the source address of received +data. The function takes the following arguments: +.sp +.ne 2 +.mk +.na +\fB\fIsocket\fR\fR +.ad +.RS 10n +.rt +Specifies the socket file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuffer\fR\fR +.ad +.RS 10n +.rt +Points to a buffer where the message should be stored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlength\fR\fR +.ad +.RS 10n +.rt +Specifies the length in bytes of the buffer pointed to by the \fIbuffer\fR +argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 10n +.rt +Specifies the type of message reception. Values of this argument are formed by +logically OR'ing zero or more of the following values: +.sp +.ne 2 +.mk +.na +\fBMSG_PEEK\fR +.ad +.RS 15n +.rt +Peeks at an incoming message. The data is treated as unread and the next +\fBrecv()\fR or similar function will still return this data. +.RE + +.sp +.ne 2 +.mk +.na +\fBMSG_OOB\fR +.ad +.RS 15n +.rt +Requests out-of-band data. The significance and semantics of out-of-band data +are protocol-specific. +.RE + +.sp +.ne 2 +.mk +.na +\fBMSG_WAITALL\fR +.ad +.RS 15n +.rt +Requests that the function block until the full amount of data requested can be +returned. The function may return a smaller amount of data if a signal is +caught, if the connection is terminated, if \fBMSG_PEEK\fR was specified, or +if an error is pending for the socket. +.RE + +.RE + +.sp +.LP +The \fBrecv()\fR function returns the length of the message written to the +buffer pointed to by the \fIbuffer\fR argument. For message-based sockets such +as \fBSOCK_DGRAM\fR and \fBSOCK_SEQPACKET\fR, the entire message must be read +in a single operation. If a message is too long to fit in the supplied buffer, +and \fBMSG_PEEK\fR is not set in the \fIflags\fR argument, the excess bytes are +discarded. For stream-based sockets such as \fBSOCK_STREAM\fR, message +boundaries are ignored. In this case, data is returned to the user as soon as +it becomes available, and no data is discarded. +.sp +.LP +If the \fBMSG_WAITALL\fR flag is not set, data will be returned only up to the +end of the first message. +.sp +.LP +If no messages are available at the socket and \fBO_NONBLOCK\fR is not set on +the socket's file descriptor, \fBrecv()\fR blocks until a message arrives. If +no messages are available at the socket and \fBO_NONBLOCK\fR is set on the +socket's file descriptor, \fBrecv()\fR fails and sets \fBerrno\fR to +\fBEAGAIN\fR or \fBEWOULDBLOCK\fR. +.SH USAGE +.sp +.LP +The \fBrecv()\fR function is identical to \fBrecvfrom\fR(3XNET) with a zero +\fIaddress_len\fR argument, and to \fBread()\fR if no flags are used. +.sp +.LP +The \fBselect\fR(3C) and \fBpoll\fR(2) functions can be used to determine when +data is available to be received. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBrecv()\fR returns the length of the message in +bytes. If no messages are available to be received and the peer has performed +an orderly shutdown, \fBrecv()\fR returns 0. Otherwise, -1 is returned and +\fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBrecv()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR \fR +.ad +.br +.na +\fB\fBEWOULDBLOCK\fR\fR +.ad +.RS 15n +.rt +The socket's file descriptor is marked \fBO_NONBLOCK\fR and no data is waiting +to be received; or \fBMSG_OOB\fR is set and no out-of-band data is available +and either the socket's file descriptor is marked \fBO_NONBLOCK\fR or the +socket does not support blocking to await out-of-band data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 15n +.rt +The \fIsocket\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECONNRESET\fR\fR +.ad +.RS 15n +.rt +A connection was forcibly closed by a peer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 15n +.rt +The \fIbuffer\fR parameter can not be accessed or written. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 15n +.rt +The \fBrecv()\fR function was interrupted by a signal that was caught, before +any data was available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 15n +.rt +The \fBMSG_OOB\fR flag is set and no out-of-band data is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTCONN\fR\fR +.ad +.RS 15n +.rt +A receive is attempted on a connection-mode socket that is not connected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 15n +.rt +The \fIsocket\fR argument does not refer to a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 15n +.rt +The specified flags are not supported for this socket type or protocol. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBETIMEDOUT\fR\fR +.ad +.RS 15n +.rt +The connection timed out during connection establishment, or due to a +transmission timeout on active connection. +.RE + +.sp +.LP +The \fBrecv()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 11n +.rt +An I/O error occurred while reading from or writing to the file system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 11n +.rt +Insufficient resources were available in the system to perform the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 11n +.rt +Insufficient memory was available to fulfill the request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 11n +.rt +There were insufficient STREAMS resources available for the operation to +complete. +.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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpoll\fR(2), \fBrecvmsg\fR(3XNET), \fBrecvfrom\fR(3XNET), \fBselect\fR(3C), +\fBsend\fR(3XNET), \fBsendmsg\fR(3XNET), \fBsendto\fR(3XNET), +\fBshutdown\fR(3XNET), \fBsocket\fR(3XNET), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/recvfrom.3xnet b/usr/src/man/man3xnet/recvfrom.3xnet new file mode 100644 index 0000000000..a7d20e2c14 --- /dev/null +++ b/usr/src/man/man3xnet/recvfrom.3xnet @@ -0,0 +1,389 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 recvfrom 3XNET "10 Jun 2002" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +recvfrom \- receive a message from a socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> + +\fBssize_t\fR \fBrecvfrom\fR(\fBint\fR \fIsocket\fR, \fBvoid *restrict\fR \fIbuffer\fR, \fBsize_t\fR \fIlength\fR, + \fBint\fR \fIflags\fR, \fBstruct sockaddr *restrict\fR \fIaddress\fR, + \fBsocklen_t *restrict\fR \fIaddress_len\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBrecvfrom()\fR function receives a message from a connection-mode or +connectionless-mode socket. It is normally used with connectionless-mode +sockets because it permits the application to retrieve the source address of +received data. +.sp +.LP +The function takes the following arguments: +.sp +.ne 2 +.mk +.na +\fB\fIsocket\fR\fR +.ad +.RS 15n +.rt +Specifies the socket file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuffer\fR\fR +.ad +.RS 15n +.rt +Points to the buffer where the message should be stored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlength\fR\fR +.ad +.RS 15n +.rt +Specifies the length in bytes of the buffer pointed to by the \fIbuffer\fR +argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 15n +.rt +Specifies the type of message reception. Values of this argument are formed by +logically OR'ing zero or more of the following values: +.sp +.ne 2 +.mk +.na +\fBMSG_PEEK\fR +.ad +.RS 15n +.rt +Peeks at an incoming message. The data is treated as unread and the next +\fBrecvfrom()\fR or similar function will still return this data. +.RE + +.sp +.ne 2 +.mk +.na +\fBMSG_OOB\fR +.ad +.RS 15n +.rt +Requests out-of-band data. The significance and semantics of out-of-band data +are protocol-specific. +.RE + +.sp +.ne 2 +.mk +.na +\fBMSG_WAITALL\fR +.ad +.RS 15n +.rt +Requests that the function block until the full amount of data requested can be +returned. The function may return a smaller amount of data if a signal is +caught, if the connection is terminated, if MSG_PEEK was specified, or if an +error is pending for the socket. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddress\fR\fR +.ad +.RS 15n +.rt +A null pointer, or points to a \fBsockaddr\fR structure in which the sending +address is to be stored. The length and format of the address depend on the +address family of the socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddress_len\fR\fR +.ad +.RS 15n +.rt +Specifies the length of the \fBsockaddr\fR structure pointed to by the +\fIaddress\fR argument. +.RE + +.sp +.LP +The \fBrecvfrom()\fR function returns the length of the message written to the +buffer pointed to by the \fIbuffer\fR argument. For message-based sockets such +as \fBSOCK_DGRAM\fR and \fBSOCK_SEQPACKET\fR, the entire message must be read +in a single operation. If a message is too long to fit in the supplied buffer, +and \fBMSG_PEEK\fR is not set in the \fIflags\fR argument, the excess bytes are +discarded. For stream-based sockets such as \fBSOCK_STREAM\fR, message +boundaries are ignored. In this case, data is returned to the user as soon as +it becomes available, and no data is discarded. +.sp +.LP +If the \fBMSG_WAITALL\fR flag is not set, data will be returned only up to the +end of the first message. +.sp +.LP +Not all protocols provide the source address for messages. If the +\fIaddress\fR argument is not a null pointer and the protocol provides the +source address of messages, the source address of the received message is +stored in the \fBsockaddr\fR structure pointed to by the \fIaddress\fR +argument, and the length of this address is stored in the object pointed to by +the \fIaddress_len\fR argument. +.sp +.LP +If the actual length of the address is greater than the length of the supplied +\fBsockaddr\fR structure, the stored address will be truncated. +.sp +.LP +If the \fIaddress\fR argument is not a null pointer and the protocol does not +provide the source address of messages, the the value stored in the object +pointed to by \fIaddress\fR is unspecified. +.sp +.LP +If no messages are available at the socket and \fBO_NONBLOCK\fR is not set on +the socket's file descriptor, \fBrecvfrom()\fR blocks until a message arrives. +If no messages are available at the socket and \fBO_NONBLOCK\fR is set on the +socket's file descriptor, \fBrecvfrom()\fR fails and sets \fBerrno\fR to +\fBEAGAIN\fR or \fBEWOULDBLOCK\fR. +.SH USAGE +.sp +.LP +The \fBselect\fR(3C) and \fBpoll\fR(2) functions can be used to determine when +data is available to be received. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBrecvfrom()\fR returns the length of the message +in bytes. If no messages are available to be received and the peer has +performed an orderly shutdown, \fBrecvfrom()\fR returns 0. Otherwise the +function returns \(mi1 and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBrecvfrom()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.br +.na +\fB\fBEWOULDBLOCK\fR\fR +.ad +.RS 15n +.rt +The socket's file descriptor is marked \fBO_NONBLOCK\fR and no data is waiting +to be received, or \fBMSG_OOB\fR is set and no out-of-band data is available +and either the socket's file descriptor is marked \fBO_NONBLOCK\fR or the +socket does not support blocking to await out-of-band data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 15n +.rt +The \fIsocket\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECONNRESET\fR\fR +.ad +.RS 15n +.rt +A connection was forcibly closed by a peer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 15n +.rt +The \fIbuffer\fR, \fIaddress\fR or \fIaddress_len\fR parameter can not be +accessed or written. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 15n +.rt +A signal interrupted \fBrecvfrom()\fR before any data was available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 15n +.rt +The \fBMSG_OOB\fR flag is set and no out-of-band data is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTCONN\fR\fR +.ad +.RS 15n +.rt +A receive is attempted on a connection-mode socket that is not connected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 15n +.rt +The \fIsocket\fR argument does not refer to a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 15n +.rt +The specified flags are not supported for this socket type. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBETIMEDOUT\fR\fR +.ad +.RS 15n +.rt +The connection timed out during connection establishment, or due to a +transmission timeout on active connection. +.RE + +.sp +.LP +The \fBrecvfrom()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 11n +.rt +An I/O error occurred while reading from or writing to the file system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 11n +.rt +Insufficient resources were available in the system to perform the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 11n +.rt +Insufficient memory was available to fulfill the request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 11n +.rt +There were insufficient STREAMS resources available for the operation to +complete. +.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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpoll\fR(2), \fBrecv\fR(3XNET), \fBrecvmsg\fR(3XNET), \fBselect\fR(3C) +\fBsend\fR(3XNET), \fBsendmsg\fR(3XNET), \fBsendto\fR(3XNET), +\fBshutdown\fR(3XNET), \fBsocket\fR(3XNET), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/recvmsg.3xnet b/usr/src/man/man3xnet/recvmsg.3xnet new file mode 100644 index 0000000000..c15d4dbcb7 --- /dev/null +++ b/usr/src/man/man3xnet/recvmsg.3xnet @@ -0,0 +1,440 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 recvmsg 3XNET "27 Feb 2006" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +recvmsg \- receive a message from a socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> + +\fBssize_t\fR \fBrecvmsg\fR(\fBint\fR \fIsocket\fR, \fBstruct msghdr *\fR\fImessage\fR, \fBint\fR \fIflags\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBrecvmsg()\fR function receives a message from a connection-mode or +connectionless-mode socket. It is normally used with connectionless-mode +sockets because it permits the application to retrieve the source address of +received data. +.sp +.LP +The \fBrecvmsg()\fR function receives messages from unconnected or connected +sockets and returns the length of the message. +.sp +.LP +The \fBrecvmsg()\fR function returns the total length of the message. For +message-based sockets such as \fBSOCK_DGRAM\fR and \fBSOCK_SEQPACKET\fR, the +entire message must be read in a single operation. If a message is too long to +fit in the supplied buffers, and \fBMSG_PEEK\fR is not set in the \fIflags\fR +argument, the excess bytes are discarded, and \fBMSG_TRUNC\fR is set in the +\fBmsg_flags\fR member of the \fBmsghdr\fR structure. For stream-based sockets +such as \fBSOCK_STREAM\fR, message boundaries are ignored. In this case, data +is returned to the user as soon as it becomes available, and no data is +discarded. +.sp +.LP +If the \fBMSG_WAITALL\fR flag is not set, data will be returned only up to the +end of the first message. +.sp +.LP +If no messages are available at the socket, and \fBO_NONBLOCK\fR is not set on +the socket's file descriptor, \fBrecvmsg()\fR blocks until a message arrives. +If no messages are available at the socket and \fBO_NONBLOCK\fR is set on the +socket's file descriptor, the \fBrecvmsg()\fR function fails and sets +\fBerrno\fR to \fBEAGAIN\fR or \fBEWOULDBLOCK\fR. +.sp +.LP +In the \fBmsghdr\fR structure, defined in \fBsocket.h\fR(3HEAD), the +\fBmsg_name\fR and \fBmsg_namelen\fR members specify the source address if the +socket is unconnected. If the socket is connected, the \fBmsg_name\fR and +\fBmsg_namelen\fR members are ignored. The \fBmsg_name\fR member may be a null +pointer if no names are desired or required. +.sp +.LP +The \fBmsg_control\fR and \fBmsg_controllen\fR members specify a buffer to +receive ancillary data sent along with a message. Ancillary data consists of a +sequence of pairs. Each pair is composed of a \fBcmsghdr\fR structure followed +by a data array. The \fBcmsghdr\fR structure, defined in \fBsocket.h\fR(3HEAD), +contains descriptive information which allows an application to correctly parse +data. The data array contains the ancillary data message. +.sp +.LP +If ancillary data is not transferred, \fBmsg_control\fR is set to \fBNULL\fR +and \fBmsg_controllen\fR is set to \fB0\fR. +.sp +.LP +The \fBmsg_iov\fR and \fBmsg_iovlen\fR fields of the \fBmsghdr\fR structure are +used to specify where the received data will be stored. \fBmsg_iov\fR points to +an array of \fBiovec\fR structures. The \fBmsg_iovlen\fR must be set to the +dimension of this array. In each \fBiovec\fR structure, the \fBiov_base\fR +field specifies a storage area and the \fBiov_len\fR field gives its size in +bytes. Each storage area indicated by \fBmsg_iov\fR is filled with received +data in turn until all of the received data is stored or all of the areas have +been filled. +.sp +.LP +If the \fBSO_TIMESTAMP\fR option has been enabled through \fBsetsockopt()\fR, +then a struct \fBtimeval\fR is returned following the \fBcmsghdr\fR, and the +\fBcmsg_len\fR field of the \fBcmsghdr\fR indicates the size of the struct +\fBtimeval\fR. +.sp +.LP +On successful completion, the \fBmsg_flags\fR member of the message header is +the bitwise-inclusive OR of all of the following flags that indicate conditions +detected for the received message: +.sp +.ne 2 +.mk +.na +\fB\fBMSG_EOR\fR\fR +.ad +.RS 14n +.rt +End of record was received (if supported by the protocol). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMSG_OOB\fR\fR +.ad +.RS 14n +.rt +Out-of-band data was received. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMSG_TRUNC\fR\fR +.ad +.RS 14n +.rt +Normal data was truncated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMSG_CTRUNC\fR\fR +.ad +.RS 14n +.rt +Control data was truncated. +.RE + +.SH PARAMETERS +.sp +.LP +The function takes the following arguments: +.sp +.ne 2 +.mk +.na +\fB\fIsocket\fR\fR +.ad +.RS 11n +.rt +Specifies the socket file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImessage\fR\fR +.ad +.RS 11n +.rt +Points to a \fBmsghdr\fR structure, containing both the buffer to store the +source address and the buffers for the incoming message. The length and format +of the address depend on the address family of the socket. The \fBmsg_flags\fR +member is ignored on input, but may contain meaningful values on output. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 11n +.rt +Specifies the type of message reception. Values of this argument are formed by +logically OR'ing zero or more of the following values: +.sp +.ne 2 +.mk +.na +\fB\fBMSG_OOB\fR\fR +.ad +.RS 15n +.rt +Requests out-of-band data. The significance and semantics of out-of-band data +are protocol-specific. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMSG_PEEK\fR\fR +.ad +.RS 15n +.rt +Peeks at the incoming message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMSG_WAITALL\fR\fR +.ad +.RS 15n +.rt +Requests that the function block until the full amount of data requested can be +returned. The function may return a smaller amount of data if a signal is +caught, if the connection is terminated, if \fBMSG_PEEK\fR was specified, or if +an error is pending for the socket. +.RE + +.RE + +.SH USAGE +.sp +.LP +The \fBselect\fR(3C) and \fBpoll\fR(2) functions can be used to determine when +data is available to be received. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBrecvmsg()\fR returns the length of the message +in bytes. If no messages are available to be received and the peer has +performed an orderly shutdown, \fBrecvmsg()\fR returns \fB0\fR. Otherwise, +\fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBrecvmsg()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.br +.na +\fB\fBEWOULDBLOCK\fR\fR +.ad +.RS 15n +.rt +The socket's file descriptor is marked \fBO_NONBLOCK\fR and no data is waiting +to be received; or \fBMSG_OOB\fR is set and no out-of-band data is available +and either the socket's file descriptor is marked \fBO_NONBLOCK\fR or the +socket does not support blocking to await out-of-band data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 15n +.rt +The \fIsocket\fR argument is not a valid open file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECONNRESET\fR\fR +.ad +.RS 15n +.rt +A connection was forcibly closed by a peer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 15n +.rt +The \fImessage\fR parameter, or storage pointed to by the \fImsg_name\fR, +\fImsg_control\fR or \fImsg_iov\fR fields of the \fImessage\fR parameter, or +storage pointed to by the \fBiovec\fR structures pointed to by the +\fImsg_iov\fR field can not be accessed or written. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 15n +.rt +This function was interrupted by a signal before any data was available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 15n +.rt +The sum of the \fBiov_len\fR values overflows an \fBssize_t\fR. or the MSG_OOB +flag is set and no out-of-band data is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMSGSIZE\fR\fR +.ad +.RS 15n +.rt +The \fBmsg_iovlen\fR member of the \fBmsghdr\fR structure pointed to by +\fImessage\fR is less than or equal to 0, or is greater than \fBIOV_MAX\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTCONN\fR\fR +.ad +.RS 15n +.rt +A receive is attempted on a connection-mode socket that is not connected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 15n +.rt +The \fIsocket\fR argument does not refer to a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 15n +.rt +The specified flags are not supported for this socket type. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBETIMEDOUT\fR\fR +.ad +.RS 15n +.rt +The connection timed out during connection establishment, or due to a +transmission timeout on active connection. +.RE + +.sp +.LP +The \fBrecvmsg()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 11n +.rt +An \fBIO\fR error occurred while reading from or writing to the file system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 11n +.rt +Insufficient resources were available in the system to perform the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 11n +.rt +Insufficient memory was available to fulfill the request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 11n +.rt +There were insufficient STREAMS resources available for the operation to +complete. +.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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpoll\fR(2), \fBrecv\fR(3XNET), \fBrecvfrom\fR(3XNET), \fBselect\fR(3C), +\fBsend\fR(3XNET), \fBsendmsg\fR(3XNET), \fBsendto\fR(3XNET), +\fBsetsockopt\fR(3XNET), \fBshutdown\fR(3XNET), \fBsocket\fR(3XNET), +\fBsocket.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/send.3xnet b/usr/src/man/man3xnet/send.3xnet new file mode 100644 index 0000000000..ea8c6c8ca9 --- /dev/null +++ b/usr/src/man/man3xnet/send.3xnet @@ -0,0 +1,359 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 3XNET "1 Nov 2003" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +send \- send a message on a socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> + +\fBssize_t\fR \fBsend\fR(\fBint\fR \fIsocket\fR, \fBconst void *\fR\fIbuffer\fR, \fBsize_t\fR \fIlength\fR, \fBint flags\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsocket\fR\fR +.ad +.RS 10n +.rt +Specifies the socket file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuffer\fR\fR +.ad +.RS 10n +.rt +Points to the buffer containing the message to send. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlength\fR\fR +.ad +.RS 10n +.rt +Specifies the length of the message in bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 10n +.rt +Specifies the type of message transmission. Values of this argument are formed +by logically OR'ing zero or more of the following flags: +.sp +.ne 2 +.mk +.na +\fB\fBMSG_EOR\fR\fR +.ad +.RS 11n +.rt +Terminates a record (if supported by the protocol) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMSG_OOB\fR\fR +.ad +.RS 11n +.rt +Sends out-of-band data on sockets that support out-of-band communications. The +significance and semantics of out-of-band data are protocol-specific. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBsend()\fR function initiates transmission of a message from the +specified socket to its peer. The \fBsend()\fR function sends a message only +when the socket is connected (including when the peer of a connectionless +socket has been set via \fBconnect\fR(3XNET)). +.sp +.LP +The length of the message to be sent is specified by the \fIlength\fR argument. +If the message is too long to pass through the underlying protocol, +\fBsend()\fR fails and no data is transmitted. +.sp +.LP +Successful completion of a call to \fBsend()\fR does not guarantee delivery of +the message. A return value of \(mi1 indicates only locally-detected errors. +.sp +.LP +If space is not available at the sending socket to hold the message to be +transmitted and the socket file descriptor does not have \fBO_NONBLOCK\fR set, +\fBsend()\fR blocks until space is available. If space is not available at the +sending socket to hold the message to be transmitted and the socket file +descriptor does have \fBO_NONBLOCK\fR set, \fBsend()\fR will fail. The +\fBselect\fR(3C) and \fBpoll\fR(2) functions can be used to determine when it +is possible to send more data. +.sp +.LP +The socket in use may require the process to have appropriate privileges to use +the \fBsend()\fR function. +.SH USAGE +.sp +.LP +The \fBsend()\fR function is identical to \fBsendto\fR(3XNET) with a null +pointer \fIdest_len\fR argument, and to \fBwrite()\fR if no flags are used. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBsend()\fR returns the number of bytes sent. +Otherwise, \(mi1 is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsend()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR \fR +.ad +.br +.na +\fB\fBEWOULDBLOCK\fR\fR +.ad +.RS 16n +.rt +The socket's file descriptor is marked \fBO_NONBLOCK\fR and the requested +operation would block. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 16n +.rt +The \fIsocket\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECONNRESET\fR\fR +.ad +.RS 16n +.rt +A connection was forcibly closed by a peer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEDESTADDRREQ\fR\fR +.ad +.RS 16n +.rt +The socket is not connection-mode and no peer address is set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 16n +.rt +The \fIbuffer\fR parameter can not be accessed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 16n +.rt +A signal interrupted \fBsend()\fR before any data was transmitted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMSGSIZE\fR\fR +.ad +.RS 16n +.rt +The message is too large be sent all at once, as the socket requires. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTCONN\fR\fR +.ad +.RS 16n +.rt +The socket is not connected or otherwise has not had the peer prespecified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 16n +.rt +The \fIsocket\fR argument does not refer to a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 16n +.rt +The \fIsocket\fR argument is associated with a socket that does not support one +or more of the values set in \fIflags\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPIPE\fR\fR +.ad +.RS 16n +.rt +The socket is shut down for writing, or the socket is connection-mode and is no +longer connected. In the latter case, and if the socket is of type +\fBSOCK_STREAM\fR, the \fBSIGPIPE\fR signal is generated to the calling thread. +.RE + +.sp +.LP +The \fBsend()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 15n +.rt +The calling process does not have the appropriate privileges. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 15n +.rt +An I/O error occurred while reading from or writing to the file system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENETDOWN\fR\fR +.ad +.RS 15n +.rt +The local interface used to reach the destination is down. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENETUNREACH\fR\fR +.ad +.RS 15n +.rt +No route to the network is present. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 15n +.rt +Insufficient resources were available in the system to perform the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 15n +.rt +There were insufficient STREAMS resources available for the operation to +complete. +.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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBconnect\fR(3XNET), \fBgetsockopt\fR(3XNET), \fBpoll\fR(2), +\fBrecv\fR(3XNET), \fBrecvfrom\fR(3XNET), \fBrecvmsg\fR(3XNET), +\fBselect\fR(3C), \fBsendmsg\fR(3XNET), \fBsendto\fR(3XNET), +\fBsetsockopt\fR(3XNET), \fBshutdown\fR(3XNET), \fBsocket\fR(3XNET), +\fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/sendmsg.3xnet b/usr/src/man/man3xnet/sendmsg.3xnet new file mode 100644 index 0000000000..1b18e24509 --- /dev/null +++ b/usr/src/man/man3xnet/sendmsg.3xnet @@ -0,0 +1,505 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 sendmsg 3XNET "1 Nov 2003" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +sendmsg \- send a message on a socket using a message structure +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> + +\fBssize_t\fR \fBsendmsg\fR(\fBint\fR \fIsocket\fR, \fBconst struct msghdr *\fR\fImessage\fR, \fBint\fR \fIflags\fR); +.fi + +.SH PARAMETERS +.sp +.LP +The function takes the following arguments: +.sp +.ne 2 +.mk +.na +\fB\fIsocket\fR\fR +.ad +.RS 11n +.rt +Specifies the socket file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImessage\fR\fR +.ad +.RS 11n +.rt +Points to a \fBmsghdr\fR structure, containing both the destination address and +the buffers for the outgoing message. The length and format of the address +depend on the address family of the socket. The \fBmsg_flags\fR member is +ignored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 11n +.rt +Specifies the type of message transmission. The application may specify 0 or +the following flag: +.sp +.ne 2 +.mk +.na +\fBMSG_EOR\fR +.ad +.RS 11n +.rt +Terminates a record (if supported by the protocol) +.RE + +.sp +.ne 2 +.mk +.na +\fBMSG_OOB\fR +.ad +.RS 11n +.rt +Sends out-of-band data on sockets that support out-of-bound data. The +significance and semantics of out-of-band data are protocol-specific. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBsendmsg()\fR function sends a message through a connection-mode or +connectionless-mode socket. If the socket is connectionless-mode, the message +will be sent to the address specified by \fImsghdr\fR. If the socket is +connection-mode, the destination address in \fImsghdr\fR is ignored. +.sp +.LP +The \fImsg_iov\fR and \fImsg_iovlen\fR fields of message specify zero or more +buffers containing the data to be sent. \fImsg_iov\fR points to an array of +\fBiovec\fR structures; \fImsg_iovlen\fR must be set to the dimension of this +array. In each \fBiovec\fR structure, the \fIiov_base\fR field specifies a +storage area and the \fIiov_len\fR field gives its size in bytes. Some of +these sizes can be zero. The data from each storage area indicated by +\fImsg_iov\fR is sent in turn. +.sp +.LP +Successful completion of a call to \fBsendmsg()\fR does not guarantee delivery +of the message. A return value of \(mi1 indicates only locally-detected errors. +.sp +.LP +If space is not available at the sending socket to hold the message to be +transmitted and the socket file descriptor does not have \fBO_NONBLOCK\fR set, +\fBsendmsg()\fR function blocks until space is available. If space is not +available at the sending socket to hold the message to be transmitted and the +socket file descriptor does have \fBO_NONBLOCK\fR set, \fBsendmsg()\fR function +will fail. +.sp +.LP +If the socket protocol supports broadcast and the specified address is a +broadcast address for the socket protocol, \fBsendmsg()\fR will fail if the +\fBSO_BROADCAST\fR option is not set for the socket. +.sp +.LP +The socket in use may require the process to have appropriate privileges to use +the \fBsendmsg()\fR function. +.SH USAGE +.sp +.LP +The \fBselect\fR(3C) and \fBpoll\fR(2) functions can be used to determine when +it is possible to send more data. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBsendmsg()\fR function returns the number of +bytes sent. Otherwise, \(mi1 is returned and \fBerrno\fR is set to indicate +the error. +.SH ERRORS +.sp +.LP +The \fBsendmsg()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR \fR +.ad +.br +.na +\fB\fBEWOULDBLOCK\fR\fR +.ad +.RS 16n +.rt +The socket's file descriptor is marked O_NONBLOCK and the requested operation +would block. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAFNOSUPPORT\fR\fR +.ad +.RS 16n +.rt +Addresses in the specified address family cannot be used with this socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 16n +.rt +The \fIsocket\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECONNRESET\fR\fR +.ad +.RS 16n +.rt +A connection was forcibly closed by a peer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 16n +.rt +The \fImessage\fR parameter, or storage pointed to by the \fImsg_name\fR, +\fImsg_control\fR or \fImsg_iov\fR fields of the \fImessage\fR parameter, or +storage pointed to by the \fBiovec\fR structures pointed to by the +\fImsg_iov\fR field can not be accessed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 16n +.rt +A signal interrupted \fBsendmsg()\fR before any data was transmitted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The sum of the \fBiov_len\fR values overflows an \fBssize_t\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMSGSIZE\fR\fR +.ad +.RS 16n +.rt +The message is to large to be sent all at once (as the socket requires), or the +\fBmsg_iovlen\fR member of the \fBmsghdr\fR structure pointed to by +\fImessage\fR is less than or equal to 0 or is greater than \fBIOV_MAX\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTCONN\fR\fR +.ad +.RS 16n +.rt +The socket is connection-mode but is not connected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 16n +.rt +The \fIsocket\fR argument does not refer a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 16n +.rt +The \fIsocket\fR argument is associated with a socket that does not support one +or more of the values set in \fIflags\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPIPE\fR\fR +.ad +.RS 16n +.rt +The socket is shut down for writing, or the socket is connection-mode and is no +longer connected. In the latter case, and if the socket is of type SOCK_STREAM, +the \fBSIGPIPE\fR signal is generated to the calling thread. +.RE + +.sp +.LP +If the address family of the socket is \fBAF_UNIX\fR, then \fBsendmsg()\fR will +fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 16n +.rt +An I/O error occurred while reading from or writing to the file system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +Too many symbolic links were encountered in translating the pathname in the +socket address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +A component of a pathname exceeded \fINAME_MAX\fR characters, or an entire +pathname exceeded \fIPATH_MAX\fR characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 16n +.rt +A component of the pathname does not name an existing file or the pathname is +an empty string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 16n +.rt +A component of the path prefix of the pathname in the socket address is not a +directory. +.RE + +.sp +.LP +The \fBsendmsg()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +Search permission is denied for a component of the path prefix; or write access +to the named socket is denied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEDESTADDRREQ\fR\fR +.ad +.RS 16n +.rt +The socket is not connection-mode and does not have its peer address set, and +no destination address was specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEHOSTUNREACH\fR\fR +.ad +.RS 16n +.rt +The destination host cannot be reached (probably because the host is down or a +remote router cannot reach it). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 16n +.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 16n +.rt +A destination address was specified and the socket is already connected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENETDOWN\fR\fR +.ad +.RS 16n +.rt +The local interface used to reach the destination is down. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENETUNREACH\fR\fR +.ad +.RS 16n +.rt +No route to the network is present. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 16n +.rt +Insufficient resources were available in the system to perform the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 16n +.rt +Insufficient memory was available to fulfill the request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 16n +.rt +There were insufficient STREAMS resources available for the operation to +complete. +.RE + +.sp +.LP +If the address family of the socket is \fBAF_UNIX\fR, then \fBsendmsg()\fR may +fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +Pathname resolution of a symbolic link produced an intermediate result whose +length exceeds \fIPATH_MAX\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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpoll\fR(2) \fBgetsockopt\fR(3XNET), \fBrecv\fR(3XNET), +\fBrecvfrom\fR(3XNET), \fBrecvmsg\fR(3XNET), \fBselect\fR(3C), +\fBsend\fR(3XNET), \fBsendto\fR(3XNET), \fBsetsockopt\fR(3XNET), +\fBshutdown\fR(3XNET), \fBsocket\fR(3XNET), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/sendto.3xnet b/usr/src/man/man3xnet/sendto.3xnet new file mode 100644 index 0000000000..5c496238f7 --- /dev/null +++ b/usr/src/man/man3xnet/sendto.3xnet @@ -0,0 +1,527 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 sendto 3XNET "1 Nov 2003" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +sendto \- send a message on a socket +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> + +\fBssize_t\fR \fBsendto\fR(\fBint\fR \fIsocket\fR, \fBconst void *\fR\fImessage\fR, \fBsize_t\fR \fIlength\fR, \fBint\fR \fIflags\fR, + \fBconst struct sockaddr *\fR\fIdest_addr\fR, \fBsocklen_t\fR \fIdest_len\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsendto()\fR function sends a message through a connection-mode or +connectionless-mode socket. If the socket is connectionless-mode, the message +will be sent to the address specified by \fIdest_addr\fR. If the socket is +connection-mode, \fIdest_addr\fR is ignored. +.sp +.LP +If the socket protocol supports broadcast and the specified address is a +broadcast address for the socket protocol, \fBsendto()\fR will fail if the +\fBSO_BROADCAST\fR option is not set for the socket. +.sp +.LP +The \fIdest_addr\fR argument specifies the address of the target. The +\fIlength\fR argument specifies the length of the message. +.sp +.LP +Successful completion of a call to \fBsendto()\fR does not guarantee delivery +of the message. A return value of \fB\(mi1\fR indicates only locally-detected +errors. +.sp +.LP +If space is not available at the sending socket to hold the message to be +transmitted and the socket file descriptor does not have \fBO_NONBLOCK\fR set, +\fBsendto()\fR blocks until space is available. If space is not available at +the sending socket to hold the message to be transmitted and the socket file +descriptor does have \fBO_NONBLOCK\fR set, \fBsendto()\fR will fail. +.sp +.LP +The socket in use may require the process to have appropriate privileges to use +the \fBsendto()\fR function. +.SH PARAMETERS +.sp +.LP +The function takes the following arguments: +.sp +.ne 2 +.mk +.na +\fB\fIsocket\fR\fR +.ad +.RS 13n +.rt +Specifies the socket file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImessage\fR\fR +.ad +.RS 13n +.rt +Points to a buffer containing the message to be sent. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlength\fR\fR +.ad +.RS 13n +.rt +Specifies the size of the message in bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 13n +.rt +Specifies the type of message transmission. Values of this argument are formed +by logically OR'ing zero or more of the following flags: +.sp +.ne 2 +.mk +.na +\fBMSG_EOR\fR +.ad +.RS 11n +.rt +Terminates a record (if supported by the protocol) +.RE + +.sp +.ne 2 +.mk +.na +\fBMSG_OOB\fR +.ad +.RS 11n +.rt +Sends out-of-band data on sockets that support out-of-band data. The +significance and semantics of out-of-band data are protocol-specific. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdest_addr\fR\fR +.ad +.RS 13n +.rt +Points to a \fBsockaddr\fR structure containing the destination address. The +length and format of the address depend on the address family of the socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdest_len\fR\fR +.ad +.RS 13n +.rt +Specifies the length of the \fBsockaddr\fR structure pointed to by the +\fIdest_addr\fR argument. +.RE + +.SH USAGE +.sp +.LP +The \fBselect\fR(3C) and \fBpoll\fR(2) functions can be used to determine when +it is possible to send more data. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBsendto()\fR returns the number of bytes sent. +Otherwise, \fB-1\fR is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsendto()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAFNOSUPPORT\fR\fR +.ad +.RS 16n +.rt +Addresses in the specified address family cannot be used with this socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.br +.na +\fB\fBEWOULDBLOCK\fR\fR +.ad +.RS 16n +.rt +The socket's file descriptor is marked \fBO_NONBLOCK\fR and the requested +operation would block. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 16n +.rt +The \fIsocket\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBECONNRESET\fR\fR +.ad +.RS 16n +.rt +A connection was forcibly closed by a peer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 16n +.rt +The \fImessage\fR or \fIdestaddr\fR parameter cannot be accessed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINTR\fR\fR +.ad +.RS 16n +.rt +A signal interrupted \fBsendto()\fR before any data was transmitted. +.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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTCONN\fR\fR +.ad +.RS 16n +.rt +The socket is connection-mode but is not connected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 16n +.rt +The \fIsocket\fR argument does not refer to a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 16n +.rt +The \fIsocket\fR argument is associated with a socket that does not support one +or more of the values set in \fIflags\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPIPE\fR\fR +.ad +.RS 16n +.rt +The socket is shut down for writing, or the socket is connection-mode and is no +longer connected. In the latter case, and if the socket is of type +\fBSOCK_STREAM\fR, the \fBSIGPIPE\fR signal is generated to the calling thread. +.RE + +.sp +.LP +If the address family of the socket is \fBAF_UNIX\fR, then \fBsendto()\fR will +fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 16n +.rt +An I/O error occurred while reading from or writing to the file system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBELOOP\fR\fR +.ad +.RS 16n +.rt +Too many symbolic links were encountered in translating the pathname in the +socket address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +A component of a pathname exceeded \fINAME_MAX\fR characters, or an entire +pathname exceeded \fIPATH_MAX\fR characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 16n +.rt +A component of the pathname does not name an existing file or the pathname is +an empty string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTDIR\fR\fR +.ad +.RS 16n +.rt +A component of the path prefix of the pathname in the socket address is not a +directory. +.RE + +.sp +.LP +The \fBsendto()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 16n +.rt +Search permission is denied for a component of the path prefix; or write access +to the named socket is denied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEDESTADDRREQ\fR\fR +.ad +.RS 16n +.rt +The socket is not connection-mode and does not have its peer address set, and +no destination address was specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEHOSTUNREACH\fR\fR +.ad +.RS 16n +.rt +The destination host cannot be reached (probably because the host is down or a +remote router cannot reach it). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +The \fIdest_len\fR argument is not a valid length for the address family. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 16n +.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 16n +.rt +A destination address was specified and the socket is already connected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENETDOWN\fR\fR +.ad +.RS 16n +.rt +The local interface used to reach the destination is down. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENETUNREACH\fR\fR +.ad +.RS 16n +.rt +No route to the network is present. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 16n +.rt +Insufficient resources were available in the system to perform the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 16n +.rt +Insufficient memory was available to fulfill the request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 16n +.rt +There were insufficient STREAMS resources available for the operation to +complete. +.RE + +.sp +.LP +If the address family of the socket is \fBAF_UNIX\fR, then \fBsendto()\fR may +fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +Pathname resolution of a symbolic link produced an intermediate result whose +length exceeds \fIPATH_MAX\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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBpoll\fR(2), \fBgetsockopt\fR(3XNET), \fBrecv\fR(3XNET), +\fBrecvfrom\fR(3XNET), \fBrecvmsg\fR(3XNET), \fBselect\fR(3C), +\fBsend\fR(3XNET), \fBsendmsg\fR(3XNET), \fBsetsockopt\fR(3XNET), +\fBshutdown\fR(3XNET), \fBsocket\fR(3XNET), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/setsockopt.3xnet b/usr/src/man/man3xnet/setsockopt.3xnet new file mode 100644 index 0000000000..f87aa23c2a --- /dev/null +++ b/usr/src/man/man3xnet/setsockopt.3xnet @@ -0,0 +1,386 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 setsockopt 3XNET "21 Jan 2007" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +setsockopt \- set the socket options +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lxnet\fR [ \fIlibrary\fR... ] +#include <sys/socket.h> + +\fBint\fR \fBsetsockopt\fR(\fBint\fR \fIsocket\fR, \fBint\fR \fIlevel\fR, \fBint\fR \fIoption_name\fR, + \fBconst void*\fR\fIoption_value\fR, \fBsocklen_t\fR \fIoption_len\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsetsockopt()\fR function sets the option specified by the +\fIoption_name\fR argument, at the protocol level specified by the \fIlevel\fR +argument, to the value pointed to by the \fIoption_value\fR argument for the +socket associated with the file descriptor specified by the \fIsocket\fR +argument. +.sp +.LP +The \fIlevel\fR argument specifies the protocol level at which the option +resides. To set options at the socket level, specify the \fIlevel\fR argument +as \fBSOL_SOCKET\fR. To set options at other levels, supply the appropriate +protocol number for the protocol controlling the option. For example, to +indicate that an option will be interpreted by the TCP (Transport Control +Protocol), set \fIlevel\fR to the protocol number of TCP, as defined in +the<\fBnetinet/in.h\fR> header, or as determined by using +\fBgetprotobyname\fR(3XNET). +.sp +.LP +The \fIoption_name\fR argument specifies a single option to set. The +\fIoption_name\fR argument and any specified options are passed uninterpreted +to the appropriate protocol module for interpretations. The +<\fBsys/socket.h\fR> header defines the socket level options. The options are +as follow +.sp +.ne 2 +.mk +.na +\fB\fBSO_DEBUG\fR\fR +.ad +.RS 17n +.rt +Turns on recording of debugging information. This option enables or disables +debugging in the underlying protocol modules. This option takes an \fBint\fR +value. This is a boolean option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_BROADCAST\fR\fR +.ad +.RS 17n +.rt +Permits sending of broadcast messages, if this is supported by the protocol. +This option takes an \fBint\fR value. This is a boolean option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_REUSEADDR\fR\fR +.ad +.RS 17n +.rt +Specifies that the rules used in validating addresses supplied to +\fBbind\fR(3XNET) should allow reuse of local addresses, if this is supported +by the protocol. This option takes an \fBint\fR value. This is a boolean +option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_KEEPALIVE\fR\fR +.ad +.RS 17n +.rt +Keeps connections active by enabling the periodic transmission of messages, if +this is supported by the protocol. This option takes an \fBint\fR value. +.sp +If the connected socket fails to respond to these messages, the connection is +broken and threads writing to that socket are notified with a \fBSIGPIPE\fR +signal. +.sp +This is a boolean option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_LINGER\fR\fR +.ad +.RS 17n +.rt +Lingers on a \fBclose\fR(2) if data is present. This option controls the +action taken when unsent messages queue on a socket and \fBclose\fR(2) is +performed. If \fBSO_LINGER\fR is set, the system blocks the process during +\fBclose\fR(2) until it can transmit the data or until the time expires. If +\fBSO_LINGER\fR is not specified, and \fBclose\fR(2) is issued, the system +handles the call in a way that allows the process to continue as quickly as +possible. This option takes a \fBlinger\fR structure, as defined in the +<\fBsys/socket.h\fR> header, to specify the state of the option and linger +interval. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_OOBINLINE\fR\fR +.ad +.RS 17n +.rt +Leaves received out-of-band data (data marked urgent) in line. This option +takes an \fBint\fR value. This is a boolean option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_SNDBUF\fR\fR +.ad +.RS 17n +.rt +Sets send buffer size. This option takes an \fBint\fR value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_RCVBUF\fR\fR +.ad +.RS 17n +.rt +Sets receive buffer size. This option takes an \fBint\fR value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_DONTROUTE\fR\fR +.ad +.RS 17n +.rt +Requests that outgoing messages bypass the standard routing facilities. The +destination must be on a directly-connected network, and messages are directed +to the appropriate network interface according to the destination address. The +effect, if any, of this option depends on what protocol is in use. This option +takes an \fBint\fR value. This is a boolean option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_MAC_EXEMPT\fR\fR +.ad +.RS 17n +.rt +Sets the mandatory access control on the socket. A socket that has this option +enabled can communicate with an unlabeled peer if the socket 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. \fBSO_MAC_EXEMPT\fR is a boolean option that is available only +when the system is configured with Trusted Extensions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_ALLZONES\fR\fR +.ad +.RS 17n +.rt +Bypasses zone boundaries (privileged). This option stores an \fBint\fR value. +This is a boolean option. +.sp +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). +.RE + +.sp +.LP +For boolean options, \fB0\fR indicates that the option is disabled and \fB1\fR +indicates that the option is enabled. +.sp +.LP +Options at other protocol levels vary in format and name. +.SH USAGE +.sp +.LP +The \fBsetsockopt()\fR function provides an application program with the means +to control socket behavior. An application program can use \fBsetsockopt()\fR +to allocate buffer space, control timeouts, or permit socket data broadcasts. +The <\fBsys/socket.h\fR> header defines the socket-level options available to +\fBsetsockopt()\fR. +.sp +.LP +Options may exist at multiple protocol levels. The \fBSO_\fR options are always +present at the uppermost socket level. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBsetsockopt()\fR returns \fB0\fR. Otherwise, +\fB-1\fR is returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsetsockopt()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 15n +.rt +The \fIsocket\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEDOM\fR\fR +.ad +.RS 15n +.rt +The send and receive timeout values are too big to fit into the timeout fields +in the socket structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 15n +.rt +The \fIoption_value\fR parameter can not be accessed or written. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 15n +.rt +The specified option is invalid at the specified socket level or the socket has +been shut down. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEISCONN\fR\fR +.ad +.RS 15n +.rt +The socket is already connected, and a specified option can not be set while +the socket is connected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOPROTOOPT\fR\fR +.ad +.RS 15n +.rt +The option is not supported by the protocol. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSOCK\fR\fR +.ad +.RS 15n +.rt +The \fIsocket\fR argument does not refer to a socket. +.RE + +.sp +.LP +The \fBsetsockopt()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 11n +.rt +There was insufficient memory available for the operation to complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 11n +.rt +Insufficient resources are available in the system to complete the call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 11n +.rt +There were insufficient STREAMS resources available for the operation to +complete. +.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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBbind\fR(3XNET), \fBendprotoent\fR(3XNET), \fBgetsockopt\fR(3XNET), +\fBsocket\fR(3XNET), \fBattributes\fR(5), \fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/shutdown.3xnet b/usr/src/man/man3xnet/shutdown.3xnet new file mode 100644 index 0000000000..966de7e1ef --- /dev/null +++ b/usr/src/man/man3xnet/shutdown.3xnet @@ -0,0 +1,189 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions +.\" Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 3XNET "10 Jun 2002" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +shutdown \- shut down socket send and receive operations +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> + +\fBint\fR \fBshutdown\fR(\fBint\fR \fIsocket\fR, \fBint\fR \fIhow\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBshutdown()\fR function disables subsequent \fBsend()\fR and +\fBreceive()\fR operations on a socket, depending on the value of the \fIhow\fR +argument. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhow\fR\fR +.ad +.RS 10n +.rt +Specifies the type of shutdown. The values are as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSHUT_RD\fR\fR +.ad +.RS 13n +.rt +Disables further receive operations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSHUT_WR\fR\fR +.ad +.RS 13n +.rt +Disables further send operations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSHUT_RDWR\fR\fR +.ad +.RS 13n +.rt +Disables further send and receive operations. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsocket\fR\fR +.ad +.RS 10n +.rt +Specifies the file descriptor of the socket. +.RE + +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBshutdown()\fR returns 0. Otherwise, \(mi1 is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBshutdown()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 12n +.rt +The \fIsocket\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 12n +.rt +The \fIhow\fR argument is invalid. +.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 \fIsocket\fR argument does not refer to a socket. +.RE + +.sp +.LP +The \fBshutdown()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 11n +.rt +Insufficient resources were available in the system to perform the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 11n +.rt +There were insufficient STREAMS resources available for the operation to +complete. +.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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBgetsockopt\fR(3XNET), \fBrecv\fR(3XNET), \fBrecvfrom\fR(3XNET), +\fBrecvmsg\fR(3XNET), \fBselect\fR(3C), \fBsend\fR(3XNET), \fBsendto\fR(3XNET), +\fBsetsockopt\fR(3XNET), \fBsocket\fR(3XNET), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/sockatmark.3xnet b/usr/src/man/man3xnet/sockatmark.3xnet new file mode 100644 index 0000000000..025d7ebabf --- /dev/null +++ b/usr/src/man/man3xnet/sockatmark.3xnet @@ -0,0 +1,109 @@ +'\" te +.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 sockatmark 3XNET "1 Oct 2003" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +sockatmark \- determine whether a socket is at the out-of-band mark +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> + +\fBint\fR \fBsockatmark\fR(\fBint\fR \fIs\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsockatmark()\fR function determines whether the socket specified by the +descriptor \fIs\fR is at the out-of-band data mark. If the protocol for the +socket supports out-of-band data by marking the stream with an out-of-band data +mark, the \fBsockatmark()\fR function returns 1 when all data preceding the +mark has been read and the out-of-band data mark is the first element in the +receive queue. The \fBsockatmark()\fR function does not remove the mark from +the stream. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, the \fBsockatmark()\fR function returns a value +indicating whether the socket is at an out-of-band data mark. If the protocol +has marked the data stream and all data preceding the mark has been read, the +return value is 1. If there is no mark, or if data precedes the mark in the +receive queue, the \fBsockatmark()\fR function returns 0. Otherwise, it returns +\(mi1 and sets \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsockatmark()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The \fIs\fR argument is not a valid file descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTTY\fR\fR +.ad +.RS 10n +.rt +The \fIs\fR argument does not specify a descriptor for a socket. +.RE + +.SH USAGE +.sp +.LP +The use of this function between receive operations allows an application to +determine which received data precedes the out-of-band data and which follows +the out-of-band data. +.sp +.LP +There is an inherent race condition in the use of this function. On an empty +receive queue, the current read of the location might well be at the "mark", +but the system has no way of knowing that the next data segment that will +arrive from the network will carry the mark, and \fBsockatmark()\fR will return +false, and the next read operation will silently consume the mark. +.sp +.LP +Hence, this function can only be used reliably when the application already +knows that the out-of-band data has been seen by the system or that it is known +that there is data waiting to be read at the socket, either by \fBSIGURG\fR or +\fBselect\fR(3C). +.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 +\fBrecv\fR(3XNET), \fBrecvmsg\fR(3XNET), \fBselect\fR(3C), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/socket.3xnet b/usr/src/man/man3xnet/socket.3xnet new file mode 100644 index 0000000000..a345590df8 --- /dev/null +++ b/usr/src/man/man3xnet/socket.3xnet @@ -0,0 +1,314 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions +.\" Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 3XNET "10 Jun 2002" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +socket \- create an endpoint for communication +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#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 unbound socket in a communications +domain, and returns a file descriptor that can be used in later function calls +that operate on sockets. +.sp +.LP +The <\fBsys/socket.h\fR> header defines at least the following values for the +\fIdomain\fR argument: +.sp +.ne 2 +.mk +.na +\fB\fBAF_UNIX\fR\fR +.ad +.RS 12n +.rt +File system pathnames. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAF_INET\fR\fR +.ad +.RS 12n +.rt +Internet Protocol version 4 (IPv4) address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAF_INET6\fR\fR +.ad +.RS 12n +.rt +Internet Protocol version 6 (IPv6) address. +.RE + +.sp +.LP +The \fItype\fR argument specifies the socket type, which determines the +semantics of communication over the socket. The socket types supported by the +system are implementation-dependent. Possible socket types include: +.sp +.ne 2 +.mk +.na +\fB\fBSOCK_STREAM\fR\fR +.ad +.RS 18n +.rt +Provides sequenced, reliable, bidirectional, connection-mode byte streams, and +may provide a transmission mechanism for out-of-band data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSOCK_DGRAM\fR\fR +.ad +.RS 18n +.rt +Provides datagrams, which are connectionless-mode, unreliable messages of fixed +maximum length. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSOCK_SEQPACKET\fR\fR +.ad +.RS 18n +.rt +Provides sequenced, reliable, bidirectional, connection-mode transmission path +for records. A record can be sent using one or more output operations and +received using one or more input operations, but a single operation never +transfers part of more than one record. Record boundaries are visible to the +receiver via the MSG_EOR flag. +.RE + +.sp +.LP +If the \fIprotocol\fR argument is non-zero, it must specify a protocol that is +supported by the address family. The protocols supported by the system are +implementation-dependent. +.sp +.LP +The process may need to have appropriate privileges to use the \fBsocket()\fR +function or to create some sockets. +.SH PARAMETERS +.sp +.LP +The function takes the following arguments: +.sp +.ne 2 +.mk +.na +\fB\fIdomain\fR\fR +.ad +.RS 12n +.rt +Specifies the communications domain in which a socket is to be created. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 12n +.rt +Specifies the type of socket to be created. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprotocol\fR\fR +.ad +.RS 12n +.rt +Specifies a particular protocol to be used with the socket. Specifying a +\fIprotocol\fR of 0 causes \fBsocket()\fR to use an unspecified default +protocol appropriate for the requested socket type. +.RE + +.sp +.LP +The \fIdomain\fR argument specifies the address family used in the +communications domain. The address families supported by the system are +implementation-dependent. +.SH USAGE +.sp +.LP +The documentation for specific address families specify which protocols each +address family supports. The documentation for specific protocols specify +which socket types each protocol supports. +.sp +.LP +The application can determine if an address family is supported by trying to +create a socket with \fIdomain\fR set to the protocol in question. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBsocket()\fR returns a nonnegative integer, the +socket file descriptor. Otherwise a value of \fB-1\fR 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\fBEAFNOSUPPORT\fR\fR +.ad +.RS 19n +.rt +The implementation does not support the specified address family. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 19n +.rt +No more file descriptors are available for this process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 19n +.rt +No more file descriptors are available for the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPROTONOSUPPORT\fR\fR +.ad +.RS 19n +.rt +The protocol is not supported by the address family, or the protocol is not +supported by the implementation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPROTOTYPE\fR\fR +.ad +.RS 19n +.rt +The socket type is not supported by the protocol. +.RE + +.sp +.LP +The \fBsocket()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 11n +.rt +The process does not have appropriate privileges. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 11n +.rt +Insufficient resources were available in the system to perform the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 11n +.rt +Insufficient memory was available to fulfill the request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 11n +.rt +There were insufficient STREAMS resources available for the operation to +complete. +.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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBaccept\fR(3XNET), \fBbind\fR(3XNET), \fBconnect\fR(3XNET), +\fBgetsockname\fR(3XNET), \fBgetsockopt\fR(3XNET), \fBlisten\fR(3XNET), +\fBrecv\fR(3XNET), \fBrecvfrom\fR(3XNET), \fBrecvmsg\fR(3XNET), +\fBsend\fR(3XNET), \fBsendmsg\fR(3XNET), \fBsetsockopt\fR(3XNET), +\fBshutdown\fR(3XNET), \fBsocketpair\fR(3XNET), \fBattributes\fR(5), +\fBstandards\fR(5) diff --git a/usr/src/man/man3xnet/socketpair.3xnet b/usr/src/man/man3xnet/socketpair.3xnet new file mode 100644 index 0000000000..ab7e175bd8 --- /dev/null +++ b/usr/src/man/man3xnet/socketpair.3xnet @@ -0,0 +1,287 @@ +'\" te +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved Portions Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" 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 3XNET "10 Jun 2002" "SunOS 5.11" "X/Open Networking Services Library Functions" +.SH NAME +socketpair \- create a pair of connected sockets +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ] +#include <sys/socket.h> + +\fBint\fR \fBsocketpair\fR(\fBint\fR \fIdomain\fR, \fBint\fR \fItype\fR, \fBint\fR \fIprotocol\fR, \fBint\fR \fIsocket_vector\fR\fB[2]\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBsocketpair()\fR function creates an unbound pair of connected sockets in +a specified \fIdomain\fR, of a specified \fBtype\fR, under the protocol +optionally specified by the \fIprotocol\fR argument. The two sockets are +identical. The file descriptors used in referencing the created sockets are +returned in \fIsocket_vector\fR\fB0\fR and \fIsocket_vector\fR\fB1\fR. +.sp +.LP +The \fItype\fR argument specifies the socket type, which determines the +semantics of communications over the socket. The socket types supported by the +system are implementation-dependent. Possible socket types include: +.sp +.ne 2 +.mk +.na +\fB\fBSOCK_STREAM\fR\fR +.ad +.RS 18n +.rt +Provides sequenced, reliable, bidirectional, connection-mode byte streams, and +may provide a transmission mechanism for out-of-band data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSOCK_DGRAM\fR\fR +.ad +.RS 18n +.rt +Provides datagrams, which are connectionless-mode, unreliable messages of fixed +maximum length. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSOCK_SEQPACKET\fR\fR +.ad +.RS 18n +.rt +Provides sequenced, reliable, bidirectional, connection-mode transmission path +for records. A record can be sent using one or more output operations and +received using one or more input operations, but a single operation never +transfers part of more than one record. Record boundaries are visible to the +receiver via the MSG_EOR flag. +.RE + +.sp +.LP +If the \fIprotocol\fR argument is non-zero, it must specify a protocol that is +supported by the address family. The protocols supported by the system are +implementation-dependent. +.sp +.LP +The process may need to have appropriate privileges to use the +\fBsocketpair()\fR function or to create some sockets. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdomain\fR\fR +.ad +.RS 17n +.rt +Specifies the communications domain in which the sockets are to be created. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 17n +.rt +Specifies the type of sockets to be created. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprotocol\fR\fR +.ad +.RS 17n +.rt +Specifies a particular protocol to be used with the sockets. Specifying a +\fIprotocol\fR of 0 causes \fBsocketpair()\fR to use an unspecified default +protocol appropriate for the requested socket type. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsocket_vector\fR\fR +.ad +.RS 17n +.rt +Specifies a 2-integer array to hold the file descriptors of the created socket +pair. +.RE + +.SH USAGE +.sp +.LP +The documentation for specific address families specifies which protocols each +address family supports. The documentation for specific protocols specifies +which socket types each protocol supports. +.sp +.LP +The \fBsocketpair()\fR function is used primarily with UNIX domain sockets and +need not be supported for other domains. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, this function returns 0. Otherwise, \(mi1 is +returned and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBsocketpair()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAFNOSUPPORT\fR\fR +.ad +.RS 19n +.rt +The implementation does not support the specified address family. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEMFILE\fR\fR +.ad +.RS 19n +.rt +No more file descriptors are available for this process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENFILE\fR\fR +.ad +.RS 19n +.rt +No more file descriptors are available for the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEOPNOTSUPP\fR\fR +.ad +.RS 19n +.rt +The specified protocol does not permit creation of socket pairs. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPROTONOSUPPORT\fR\fR +.ad +.RS 19n +.rt +The protocol is not supported by the address family, or the protocol is not +supported by the implementation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEPROTOTYPE\fR\fR +.ad +.RS 19n +.rt +The socket type is not supported by the protocol. +.RE + +.sp +.LP +The \fBsocketpair()\fR function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 11n +.rt +The process does not have appropriate privileges. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 11n +.rt +Insufficient resources were available in the system to perform the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 11n +.rt +Insufficient memory was available to fulfill the request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSR\fR\fR +.ad +.RS 11n +.rt +There were insufficient STREAMS resources available for the operation to +complete. +.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 StabilityStandard +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsocket\fR(3XNET), \fBattributes\fR(5), \fBstandards\fR(5) |