@c ----------------------------------------------------------------------------- @node Functional Categories, Alphabetical List, Introduction, Top @unnumbered Functional Categories @menu * io functions:: * libsocket functions:: * resolver functions:: * rexec functions:: * socket functions:: @end menu @c ----------------------------------------------------------------------------- @node io functions, libsocket functions, , Functional Categories @unnumberedsec io functions @menu * isfdtype:: * readv:: * writev:: @end menu @c ----------------------------------------------------------------------------- @node libsocket functions, resolver functions, io functions, Functional Categories @unnumberedsec libsocket functions @menu * __lsck_get_copyright:: * __lsck_get_version:: @end menu @c ----------------------------------------------------------------------------- @node resolver functions, rexec functions, libsocket functions, Functional Categories @unnumberedsec resolver functions @menu * dn_comp:: * dn_expand:: * endhostent:: * endnetent:: * endprotoent:: * endservent:: * getdomainname:: * gethostbyaddr:: * gethostbyname:: * gethostent:: * gethostname:: * getnetbyaddr:: * getnetbyname:: * getnetent:: * getprotobyname:: * getprotobynumber:: * getprotoent:: * getservbyname:: * getservbyport:: * getservent:: * herror:: * res_init:: * res_mkquery:: * res_query:: * res_querydomain:: * res_search:: * res_send:: * setdomainname:: * sethostent:: * sethostname:: * setnetent:: * setprotoent:: * setservent:: @end menu @c ----------------------------------------------------------------------------- @node rexec functions, socket functions, resolver functions, Functional Categories @unnumberedsec rexec functions @menu * rcmd:: * rexec:: * rresvport:: * ruserok:: @end menu @c ----------------------------------------------------------------------------- @node socket functions, , rexec functions, Functional Categories @unnumberedsec socket functions @menu * accept:: * bind:: * connect:: * getpeername:: * getsockname:: * getsockopt:: * if_freenameindex:: * if_indextoname:: * if_nameindex:: * if_nametoindex:: * inet_addr:: * inet_aton:: * inet_lnaof:: * inet_makeaddr:: * inet_netof:: * inet_network:: * inet_ntoa:: * inet_ntop:: * inet_pton:: * ioctl_list:: * listen:: * recv:: * recvfrom:: * send:: * sendto:: * setsockopt:: * shutdown:: * sockatmark:: * socket:: * socketpair:: @end menu @c ----------------------------------------------------------------------------- @node Alphabetical List, Unimplemented, Functional Categories, Top @unnumbered Alphabetical List @menu * accept:: * bind:: * connect:: * dn_comp:: * dn_expand:: * endhostent:: * endnetent:: * endprotoent:: * endservent:: * getdomainname:: * gethostbyaddr:: * gethostbyname:: * gethostent:: * gethostname:: * getnetbyaddr:: * getnetbyname:: * getnetent:: * getpeername:: * getprotobyname:: * getprotobynumber:: * getprotoent:: * getservbyname:: * getservbyport:: * getservent:: * getsockname:: * getsockopt:: * herror:: * if_freenameindex:: * if_indextoname:: * if_nameindex:: * if_nametoindex:: * inet_addr:: * inet_aton:: * inet_lnaof:: * inet_makeaddr:: * inet_netof:: * inet_network:: * inet_ntoa:: * inet_ntop:: * inet_pton:: * ioctl_list:: * isfdtype:: * listen:: * __lsck_get_copyright:: * __lsck_get_version:: * rcmd:: * readv:: * recv:: * recvfrom:: * res_init:: * res_mkquery:: * res_query:: * res_querydomain:: * res_search:: * res_send:: * rexec:: * rresvport:: * ruserok:: * send:: * sendto:: * setdomainname:: * sethostent:: * sethostname:: * setnetent:: * setprotoent:: * setservent:: * setsockopt:: * shutdown:: * sockatmark:: * socket:: * socketpair:: * writev:: @end menu @c ----------------------------------------------------------------------------- @node accept, bind, , Alphabetical List @unnumberedsec accept @c From file ./accept.txh @findex accept @subheading Syntax @example #include #include int accept (int s, struct sockaddr *address, size_t *addresslen); @end example @subheading Description The @code{accept()} function returns the first completed connection from the the pending connection queue form a listening socket. The parameter @var{s} is a socket descriptor that has been created with @code{socket()}, bound to a local socket-address with @code{bind()} and is listening for connections after @code{listen()}. The @code{accept()} will return a brand new socket descriptor. If the socket is not marked non-blocking, @code{accept()} blocks the caller until a connection is present. If marked non-blocking and no pending connections are present it returns -1 and set @var{errno} to EWOULDBLOCK. If @var{address} is not NULL it specifies a buffer in which to return the socket address, the @var{addresslen} is a value-result that specified the amount of space for @var{address}. On return when @var{addresslen} will hold the size written to @var{address}. @subheading Return Value On successful completion the function returns the descriptor of the accepted socket. Otherwise, a value of -1, and @var{errno} is set. @table @samp @item EBADF The parameter s is not valid. @item ECONNABORTED The peer has closed the connection. @item EINTR The call was interrupted by a signal. @item EINVAL The socket was not in the listening state. @item EMFILE The per-process descriptor table is full. @item ENFILE The system file table is full. @item ENOBUFS Insufficient resources. @item ENOTSOCK The descriptor is not a socket. @item EOPNOTSUPP The interface does not support @code{accept()} @item EWOULDBLOCK The socket is marked non-blocking and no connections are present. @end table @subheading Portability POSIX, Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node bind, connect, accept, Alphabetical List @unnumberedsec bind @c From file ./bind.txh @findex bind @subheading Syntax @example #include #include int bind (int s, const struct sockaddr *address, size_t addresslen); @end example @subheading Description The @code{bind()} function assigns a local socket-address to socket @var{s} that has no local socket-address assigned. When a socket is created with @code{socket()} it is associated with a specific protocol from the protocol and in the case of libsocket also an interface, but has no local socket-address assigned. This function requests that the local socket-address @var{address} be assigned to it. The format of the socket-address depends on the address family, for example @code{AF_INET}, @code{AF_UNIX} (also known as @code{AF_LOCAL}). @subheading Return Value On successful completion the function returns 0. Otherwise, a value of -1, and @var{errno} is set. @table @samp @item EACCESS The requested socket-address is reserved, and the calling process does not have the appropriate privileges. @item EADDRINUSE The specified socket-address is already in use. @item EADDRNOTAVAIL THe specifeid socket-address is not available from the local machine. @item EBADF The parameter s is not valid. @item EINVAL The socket is already associated with a local socket-address or the parameter is not the size of a valid socket-address for the specified address family. @item ENOBUFS Insufficient resources. @item ENOTSOCK The descriptor is not a socket. @end table @subheading Portability POSIX, Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node connect, dn_comp, bind, Alphabetical List @unnumberedsec connect @c From file ./connct.txh @findex connect @subheading Syntax @example #include #include int connect (int s, struct sockaddr *serv_addr, size_t *addrlen); @end example @subheading Description If @var{s} refers to a stream socket (@code{SOCK_STREAM}), @code{connect()} will attempt to establish a connection to the specified destination address. If @var{s} refers to a datagram socket (@code{SOCK_DGRAM}), @code{connect()} associates a default destination address for use by @code{send()} and @code{sendto()}. It also limits @code{recv()} calls to receiving from this address, rather than the default of any. To remove the association, call @code{connect()} with an invalid address, e.g. a null address (0.0.0.0). @subheading Return Value On successful completion the function returns zero. Otherwise, a value of -1 is returned and @var{errno} is set appropriately. @table @samp @item EBADF The parameter @var{s} is not valid. @item EFAULT The address data cannot be accessed. @item ENOTSOCK The descriptor is not a socket. @item EISCONN The socket is already connected. @item ECONNREFUSED The connection was refused by the server. @item ETIMEDOUT The connection timed out. @item ENETUNREACH The network is unreachable. @item EADDRINUSE The address is already in use. @item EINTR The call was interrupted by a signal. @item EOPNOTSUPP The interface does not support @code{connect()}. @item EINPROGRESS The socket is non-blocking and the connection cannot be made immediately. On completion, the socket can be selected for writing (@pxref{select, , select, libc}). Use @code{getsockopt()} to read the option @code{SO_ERROR} at level @code{SOL_SOCKET} to check if the call completed successfully - @code{SO_ERROR}'s value will be 0 on success, or an @var{errno} value otherwise. @item EALREADY The socket is non-blocking and a previous @code{connect()} request is completing. @end table @subheading Portability POSIX, Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node dn_comp, dn_expand, connect, Alphabetical List @unnumberedsec dn_comp @c From file ./inet/dn_comp.txh @findex dn_comp @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sun Jul 25 11:01:53 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include int dn_comp (unsigned char *exp_dn, unsigned char *comp_dn, int length, unsigned char **dnptrs, unsigned char *exp_dn, unsigned char **lastdnptr); @end example @subheading Description The @code{dn_comp()} function compresses the domain name @var{exp_dn} and stores it in the buffer @var{comp_dn} of length @code{length}. The compression uses an array of pointers @code{dnptrs} to previously compressed names in the current message. The first pointer points to the beginning of the message and the list ends with NULL. The limit of the array is specified by @var{lastdnptr}. If @var{dnptr} is NULL, domain names are not compressed. If @var{lastdnptr} is NULL, the list of labels is not updated. @xref{dn_expand}. @subheading Return Value The @code{dn_comp()} function returns the length of the compressed name, or -1 if an error occurs. @subheading Portability This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux. @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node dn_expand, endhostent, dn_comp, Alphabetical List @unnumberedsec dn_expand @c From file ./inet/dn_exp.txh @findex dn_expand @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sun Jul 25 11:01:53 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include int dn_expand (unsigned char *msg, unsigned char *eomorig, unsigned char *comp_dn, unsigned char *exp_dn, int length); @end example @subheading Description The @code{dn_expand()} function expands the compressed domain name @var{comp_dn} to a full domain name, which is placed in the buffer @var{exp_dn} of size @var{length}. The compressed name is contained in a query or reply message, and @var{msg} points to the beginning of the message. @xref{dn_comp}. @subheading Return Value The @code{dn_expand()} function returns the length of the compressed name, or -1 if an error occurs. @subheading Portability This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux. @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node endhostent, endnetent, dn_expand, Alphabetical List @unnumberedsec endhostent @c From file ./inet/ehstent.txh @findex endhostent @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat May 22 18:43:54 1993, David Metcalfe @c Modified Sun Jul 25 10:42:30 1993, Rik Faith (faith@cs.unc.edu) @c Modified Sun Feb 16 13:23:10 1997, Andries Brouwer (aeb@cwi.nl) @c @subheading Syntax @example #include void endhostent (void); @end example @subheading Description The @code{endhostent()} function ends the use of a TCP connection for name server queries. @subheading Return Values None @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node endnetent, endprotoent, endhostent, Alphabetical List @unnumberedsec endnetent @c From file ./inet/enetent.txh @findex endnetent @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat Jul 24 21:48:06 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include void endnetent (void); @end example @subheading Description The @code{endnetent()} function closes @samp{networks} (@pxref{networks}). @subheading Return Values None @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node endprotoent, endservent, endnetent, Alphabetical List @unnumberedsec endprotoent @c From file ./inet/eprtent.txh @findex endprotoent @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat Jul 24 19:26:03 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include void endprotoent (void); @end example @subheading Description The @code{endprotoent()} function closes the @samp{protocols} file (@pxref{protocols}). @subheading Return Values None @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node endservent, getdomainname, endprotoent, Alphabetical List @unnumberedsec endservent @c From file ./inet/esrvent.txh @findex endservent @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat Jul 24 19:19:11 1993 by Rik Faith (faith@cs.unc.edu) @c Modified Wed Oct 18 20:23:54 1995 by Martin Schulze @c Modified Mon Apr 22 01:50:54 1996 by Martin Schulze @c @subheading Syntax @example #include void endservent (void); @end example @subheading Description The @code{endservent()} function closes @samp{services} (@pxref{services}). @subheading Return Values None @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node getdomainname, gethostbyaddr, endservent, Alphabetical List @unnumberedsec getdomainname @c From file ./gdomname.txh @findex getdomainname @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Hey Emacs! This file is -*- nroff -*- source. @c @c Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @subheading Syntax @example #include int getdomainname (char *name, size_t len); @end example @subheading Description This function is used to access the domain name. The domain name can be set by @code{setdomainname()} (@pxref{setdomainname}). The domain name is the last component of the host name (@pxref{gethostname}). @subheading Return Value On success, zero is returned. On error, -1 is returned, and @var{errno} is set appropriately. @table @samp @item EINVAL @var{name} points to @samp{NULL} or @var{name} is longer than @var{len}. @end table @subheading Portability not POSIX, not Unix98 This function is defined in @samp{unistd.h} on Linux. @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node gethostbyaddr, gethostbyname, getdomainname, Alphabetical List @unnumberedsec gethostbyaddr @c From file ./inet/ghstbyad.txh @findex gethostbyaddr @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat May 22 18:43:54 1993, David Metcalfe @c Modified Sun Jul 25 10:42:30 1993, Rik Faith (faith@cs.unc.edu) @c Modified Sun Feb 16 13:23:10 1997, Andries Brouwer (aeb@cwi.nl) @c @subheading Syntax @example #include #include extern int h_errno; struct hostent *gethostbyaddr (const char *addr, int len, int type); @end example @subheading Description The @code{gethostbyaddr()} function returns a structure of type @samp{hostent} for the given host address @var{addr} of length @var{len} and address type @var{type}. The only valid address type is currently AF_INET. The @samp{hostent} structure is defined in the description of @code{gethostbyname()} (@pxref{gethostbyname}). @subheading Return Values The @code{gethostbyaddr()} function return the @samp{hostent} structure or a NULL pointer if an error occurs. On error, the @code{h_errno} variable holds an error number. @code{h_errno} can have the same values as for @code{gethostbyname()} (@pxref{gethostbyname}). The @code{herror()} function will print an error message, based on the value of @var{h_errno} (@pxref{herror}). @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node gethostbyname, gethostent, gethostbyaddr, Alphabetical List @unnumberedsec gethostbyname @c From file ./inet/ghstbynm.txh @findex gethostbyname @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat May 22 18:43:54 1993, David Metcalfe @c Modified Sun Jul 25 10:42:30 1993, Rik Faith (faith@cs.unc.edu) @c Modified Sun Feb 16 13:23:10 1997, Andries Brouwer (aeb@cwi.nl) @c @subheading Syntax @example #include extern int h_errno; struct hostent *gethostbyname (const char *name) @end example @subheading Description The @code{gethostbyname()} function returns a structure of type @samp{hostent} for the given host @var{name}. Here @var{name} is either a host name, or an IPv4 address in standard dot notation, or an IPv6 address in colon (and possibly dot) notation. (See RFC 1884 for the description of IPv6 addresses.) If @var{name} doesn't end in a dot and the environment variable @var{HOSTALIASES} is set, the alias file pointed to by @var{HOSTALIASES} will first be searched for @var{name}. @c TODO: (See .BR hostname (7) for the file format.) The current domain and its parents are searched unless @var{name} ends in a dot. The domain name queries carried out by @code{gethostbyname()} use a combination of any or all of: @itemize @bullet @item the name server @samp{named}; @item a broken out line from @samp{hosts} (@pxref{hosts}); @item the Network Information Service (NIS or YP)@footnote{libsocket does not support this.}. @end itemize depending upon the contents of the @samp{order} line in host.conf (@pxref{host.conf}). The default action is to query @samp{hosts} (@pxref{hosts}). The @dfn{hostent} structure is defined in @code{netdb.h} as follows: @example struct hostent @{ char *h_name; /* official name of host */ char **h_aliases; /* alias list */ int h_addrtype; /* host address type */ int h_length; /* length of address */ char **h_addr_list; /* list of addresses */ @} #define h_addr h_addr_list[0] /* for backward compatibility */ @end example The members of the @samp{hostent} structure are: @vtable @samp @item h_name The official name of the host. @item h_aliases A zero-terminated array of alternative names for the host. @item h_addrtype The type of address; always AF_INET at present. @item h_length The length of the address in bytes. @item h_addr_list A zero-terminated array of network addresses for the host in network byte order. @item h_addr The first address in @code{h_addr_list} for backward compatibility. @end vtable @subheading Return Values The @code{gethostbyname()} function returns a @samp{hostent} structure or a NULL pointer if an error occurs. On error, the @var{h_errno} variable holds an error number. The variable @var{h_errno} can have the following values: @table @samp @item HOST_NOT_FOUND The specified host is unknown. @item NO_ADDRESS The requested name is valid but does not have an IP address. @item NO_RECOVERY A non-recoverable name server error occurred. @item TRY_AGAIN A temporary error occurred on an authoritative name server. Try again later. @end table The @code{herror()} function will print an error message, based on the value of @var{h_errno} (@pxref{herror}). @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node gethostent, gethostname, gethostbyname, Alphabetical List @unnumberedsec gethostent @c From file ./inet/ghstent.txh @findex gethostent @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat Jul 24 21:48:06 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include struct hostent *gethostent (void); @end example @subheading Description The @code{gethostent()} function reads the next line from the file @samp{hosts} (@pxref{hosts}) and returns a structure @samp{hostent} containing the broken out fields from the line. The @samp{hosts} file is opened if necessary. The @samp{hostent} structure is defined in the description of @code{gethostbyname()} (@pxref{gethostbyname}). @subheading Return Value The @code{gethostent()} function return the @samp{hostent} structure, or a NULL pointer if an error occurs or the end of the file is reached. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node gethostname, getnetbyaddr, gethostent, Alphabetical List @unnumberedsec gethostname @c From file ./ghstnm.txh @findex gethostname @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Hey Emacs! This file is -*- nroff -*- source. @c @c Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c Modified 22 July 1995 by Michael Chastain : @c 'gethostname' is real system call on Linux/Alpha. @c Modified Fri Jan 31 16:30:53 1997 by Eric S. Raymond @subheading Syntax @example #include int gethostname (char *name, size_t len); @end example @subheading Description This function is used to access the host name of the current processor. The host name is set using @code{sethostname()} (@pxref{sethostname}). The domain name component can be retrieved and set using @code{getdomainname()} and @code{setdomainname()} respectively (@pxref{getdomainname}, @pxref{setdomainname}). libsocket's implementation of @code{gethostname()} overrides DJGPP's implementation (@pxref{gethostname, , gethostname, libc}). libsocket will fall back the DJGPP's implementation when it cannot find the host name from its additional sources. If a host name has not been set using @code{sethostname()}, then it is determined in the following order: @enumerate 1 @item from the environment variable @code{HOSTNAME}; @item from libsocket's configuration file; @item from any automatic configuration; @item from DJGPP's original @code{gethostname()} implementation. @end enumerate @subheading Return value On success, zero is returned. On error, -1 is returned, and @samp{errno} is set appropriately. @subheading Errors @table @samp @item EINVAL @var{len} is negative or smaller than the actual size. @item EFAULT @var{name} is an invalid address. @end table @subheading Portability not POSIX, not Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node getnetbyaddr, getnetbyname, gethostname, Alphabetical List @unnumberedsec getnetbyaddr @c From file ./inet/gnetbyad.txh @findex getnetbyaddr @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat Jul 24 21:48:06 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include struct netent *getnetbyaddr (long net, int type); @end example @subheading Description The @code{getnetbyaddr()} function returns a @samp{netent} structure for the line from @samp{networks} (@pxref{networks}) that matches the network number @var{net} of type @var{type}. The @samp{netent} structure is defined in the description of @code{getnetbyname()} (@pxref{getnetbyname}). @subheading Return Values The @code{getnetbyaddr()} function return the @samp{netent} structure, or a NULL pointer if an error occurs or the end of the file is reached. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node getnetbyname, getnetent, getnetbyaddr, Alphabetical List @unnumberedsec getnetbyname @c From file ./inet/gnetbynm.txh @findex getnetbyname @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat Jul 24 21:48:06 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include struct netent *getnetbyname (const char *name); @end example @subheading Description The @code{getnetbyname()} function returns a @samp{netent} structure for the line from @code{networks} (@pxref{networks}) that matches the network @var{name}. The @samp{netent} structure is defined in @samp{netdb.h} as follows: @example struct netent @{ char *n_name; /* official network name */ char **n_aliases; /* alias list */ int n_addrtype; /* net address type */ unsigned long int n_net; /* network number */ @} @end example The members of the @samp{netent} structure are: @table @samp @item n_name The official name of the network. @item n_aliases A zero terminated list of alternative names for the network. @item n_addrtype The type of the network number; always AF_INET. @item n_net The network number in host byte order. @end table @subheading Return Values The @code{getnetbyname()} function return the @samp{netent} structure, or a NULL pointer if an error occurs or the end of the file is reached. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node getnetent, getpeername, getnetbyname, Alphabetical List @unnumberedsec getnetent @c From file ./inet/gnetent.txh @findex getnetent @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat Jul 24 21:48:06 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include struct netent *getnetent(void); @end example @subheading Description The @code{getnetent()} function reads the next line from the file @samp{networks} (@pxref{networks}) and returns a structure @samp{netent} containing the broken out fields from the line. The @samp{networks} file is opened if necessary. The @samp{netent} structure is defined in the description of @code{getnetbyname()} (@pxref{getnetbyname}). @subheading Return Values The @code{getnetent()} function return the @samp{netent} structure, or a NULL pointer if an error occurs or the end of the file is reached. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node getpeername, getprotobyname, getnetent, Alphabetical List @unnumberedsec getpeername @c From file ./gprnm.txh @findex getpeername @subheading Syntax @example #include int getpeername (int s, struct sockaddr *name, size_t *namelen); @end example @subheading Description @code{getpeername()} returns the name of the peer connected to the socket @var{s}. @var{namelen} should be set to the size of the space pointed to by @var{name}. On completion @var{namelen} will contain the length of the address returned. If the buffer is too small, the address is truncated to fit. @code{getsockname()} returns the local name for the socket (@pxref{getsockname}). @subheading Return Value On successful completion the function returns 0. Otherwise, a value of -1 is returned and @var{errno} is set appropriately. @table @samp @item EBADF @var{s} is not a valid file descriptor. @item ENOTSOCK @var{s} is not a socket. @item ENOTCONN The socket @var{s} is not connected. @item ENOBUFS There were not enough resources to complete this operation. @item EFAULT @var{name} could not be accessed. @end table @subheading Portability POSIX, Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node getprotobyname, getprotobynumber, getpeername, Alphabetical List @unnumberedsec getprotobyname @c From file ./inet/gprtbynm.txh @findex getprotobyname @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat Jul 24 19:26:03 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include struct protoent *getprotobyname (const char *name); @end example @subheading Description The @code{getprotobyname()} function returns a @samp{protoent} structure for the line from @samp{protocols} (@pxref{protocols}) that matches the protocol name @var{name}. The @samp{protoent} structure is defined in @samp{netdb.h} as follows: @example struct protoent @{ char *p_name; /* official protocol name */ char **p_aliases; /* alias list */ int p_proto; /* protocol number */ @} @end example The members of the @code{protoent} structure are: @table @samp @item p_name The official name of the protocol. @item p_aliases A zero terminated list of alternative names for the protocol. @item p_proto The protocol number. @end table @subheading Return Values The @code{getprotobyname()} function returns the @samp{protoent} structure, or a NULL pointer if an error occurs or the end of the file is reached. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node getprotobynumber, getprotoent, getprotobyname, Alphabetical List @unnumberedsec getprotobynumber @c From file ./inet/gprtbyn2.txh @findex getprotobynumber @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat Jul 24 19:26:03 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include struct protoent *getprotobynumber (int proto); @end example @subheading Description The @code{getprotobynumber()} function returns a @samp{protoent} structure for the line from @samp{protocols} (@pxref{protocols}) that matches the protocol number @var{number}. The @samp{protoent} structure is defined in the description of @code{getprotobyname()} (@pxref{getprotobyname}). @subheading Return Values The @code{getprotobynumber()} function return the @samp{protoent} structure, or a NULL pointer if an error occurs or the end of the file is reached. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node getprotoent, getservbyname, getprotobynumber, Alphabetical List @unnumberedsec getprotoent @c From file ./inet/gprtent.txh @findex getprotoent @subheading Syntax @example #include struct protoent *getprotoent (void); @end example @subheading Description The @code{getprotoent()} function reads the next line from the file @samp{protocols} (@pxref{protocols}) and returns a structure @samp{protoent} containing the broken out fields from the line. The @samp{protocols} file is opened if necessary. The @samp{protoent} structure is defined in the description of @code{getprotobyname()} (@pxref{getprotobyname}). @subheading Return Values On successful completion the function returns a @samp{protoent} structure, or a NULL pointer if an error occurs or the end of the file is reached. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node getservbyname, getservbyport, getprotoent, Alphabetical List @unnumberedsec getservbyname @c From file ./inet/gsrvbynm.txh @findex getservbyname @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat Jul 24 19:19:11 1993 by Rik Faith (faith@cs.unc.edu) @c Modified Wed Oct 18 20:23:54 1995 by Martin Schulze @c Modified Mon Apr 22 01:50:54 1996 by Martin Schulze @c @subheading Syntax @example #include struct servent *getservbyname (const char *name, const char *proto); @end example @subheading Description The @code{getservbyname()} function returns a @samp{servent} structure for the line from @samp{services} (@pxref{services}) that matches the service @var{name} using protocol @var{proto}. The @samp{servent} structure is defined in @samp{netdb.h} as follows: @example struct servent @{ char *s_name; /* official service name */ char **s_aliases; /* alias list */ int s_port; /* port number */ char *s_proto; /* protocol to use */ @} @end example The members of the @samp{servent} structure are: @table @samp @item s_name The official name of the service. @item s_aliases A zero terminated list of alternative names for the service. @item s_port The port number for the service given in network byte order. @item s_proto The name of the protocol to use with this service. @end table @subheading Return Values The @code{getservbyname()} function return the @samp{servent} structure, or a NULL pointer if an error occurs or the end of the file is reached. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node getservbyport, getservent, getservbyname, Alphabetical List @unnumberedsec getservbyport @c From file ./inet/gsrvbypt.txh @findex getservbyport @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat Jul 24 19:19:11 1993 by Rik Faith (faith@cs.unc.edu) @c Modified Wed Oct 18 20:23:54 1995 by Martin Schulze @c Modified Mon Apr 22 01:50:54 1996 by Martin Schulze @c @subheading Syntax @example #include struct servent *getservbyport (int port, const char *proto); @end example @subheading Description The @code{getservbyport()} function returns a @samp{servent} structure for the line from @samp{services} (@pxref{services}) that matches the port @var{port} given in network byte order using protocol @var{proto}. The @samp{servent} structure is defined in the description of @code{getservbyname()} (@pxref{getservbyname}). @subheading Return Values The @code{getservbyport()} function return the @samp{servent} structure, or a NULL pointer if an error occurs or the end of the file is reached. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node getservent, getsockname, getservbyport, Alphabetical List @unnumberedsec getservent @c From file ./inet/gsrvent.txh @findex getservent @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat Jul 24 19:19:11 1993 by Rik Faith (faith@cs.unc.edu) @c Modified Wed Oct 18 20:23:54 1995 by Martin Schulze @c Modified Mon Apr 22 01:50:54 1996 by Martin Schulze @c @subheading Syntax @example #include struct servent *getservent (void); @end example @subheading Description The @code{getservent()} function reads the next line from the file @samp{services} (@pxref{services}) and returns a structure @samp{servent} containing the broken out fields from the line. The @samp{services} file is opened if necessary. The @samp{servent} structure is defined in the description of @code{getservbyname()} (@pxref{getservbyname}). @subheading Return Values The @code{getservent()} function return the @samp{servent} structure, or a NULL pointer if an error occurs or the end of the file is reached. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node getsockname, getsockopt, getservent, Alphabetical List @unnumberedsec getsockname @c From file ./gscknm.txh @findex getsockname @subheading Syntax @example #include int getsockname (int s, struct sockaddr *name, size_t *namelen); @end example @subheading Description @code{getsockname()} returns the local name of the socket @var{s}. @var{namelen} should be set to the size of the space pointed to by @var{name}. On completion @var{namelen} will contain the length of the address returned. If the buffer is too small, the address is truncated to fit. @code{getpeername()} returns the peer name for the socket (@pxref{getpeername}). @subheading Return Value On successful completion the function returns 0. Otherwise, a value of -1 is returned and @var{errno} is set appropriately. @table @samp @item EBADF @var{s} is not a valid file descriptor. @item ENOTSOCK @var{s} is not a socket. @item ENOBUFS There were not enough resources to complete this operation. @item EFAULT @var{name} could not be accessed. @end table @subheading Portability POSIX, Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node getsockopt, herror, getsockname, Alphabetical List @unnumberedsec getsockopt @c From file ./gsckopt.txh @findex getsockopt @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright (c) 1983, 1991 The Regents of the University of California. @c All rights reserved. @c @c Redistribution and use in source and binary forms, with or without @c modification, are permitted provided that the following conditions @c are met: @c 1. Redistributions of source code must retain the above copyright @c notice, this list of conditions and the following disclaimer. @c 2. Redistributions in binary form must reproduce the above copyright @c notice, this list of conditions and the following disclaimer in the @c documentation and/or other materials provided with the distribution. @c 3. All advertising materials mentioning features or use of this software @c must display the following acknowledgement: @c This product includes software developed by the University of @c California, Berkeley and its contributors. @c 4. Neither the name of the University nor the names of its contributors @c may be used to endorse or promote products derived from this software @c without specific prior written permission. @c @c THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND @c ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE @c IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE @c ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE @c FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL @c DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS @c OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) @c HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT @c LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY @c OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF @c SUCH DAMAGE. @c @c @(#)getsockopt.2 6.9 (Berkeley) 5/1/91 @c @c Modified Sat Jul 24 16:19:32 1993 by Rik Faith (faith@cs.unc.edu) @c Modified Mon Apr 22 02:29:06 1996 by Martin Schulze (joey@infodrom.north.de) @c Modified Tue Aug 27 10:52:51 1996 by Andries Brouwer (aeb@cwi.nl) @c Modified Thu Jan 23 13:29:34 1997 by Andries Brouwer (aeb@cwi.nl) @c @subheading Syntax @example #include #include int getsockopt (int s, int level, int optname, void *optval, int *optlen); @end example @subheading Description The @code{getsockopt()} function manipulates the options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost socket level. When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, @var{level} is specified as @code{SOL_SOCKET}. To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, @var{level} should be set to the protocol number of TCP, e.g. @code{IPPROTO_TCP} (@pxref{getprotoent}). The parameters @var{optval} and @var{optlen} are used to identify a buffer in which the value for the requested option(s) are to be returned. @var{optlen} is a value-result parameter, initially containing the size of the buffer pointed to by @var{optval}, and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, @var{optval} may be NULL. @var{optname} and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file @samp{sys/socket.h} contains definitions for socket level options, described below. Options at other protocol levels vary in format and name. Most socket-level options utilize an @samp{int} parameter for @var{optval}. @code{SO_LINGER} uses a @code{struct linger} parameter, defined in @samp{sys/socket.h}, which specifies the desired state of the option and the linger interval (see below). @code{SO_SNDTIMEO} and @code{SO_RCVTIMEO} use a @code{struct timeval} parameter, defined in @samp{sys/time.h}. The following options are recognized at the socket level: @table @samp @item SO_DEBUG Enables recording of debugging information @item SO_REUSEADDR Enables local address reuse @item SO_KEEPALIVE Enables keep connections alive @item SO_DONTROUTE Enables routing bypass for outgoing messages @item SO_LINGER Linger on close if data present @item SO_BROADCAST Enables permission to transmit broadcast messages @item SO_OOBINLINE Enables reception of out-of-band data in band @item SO_SNDBUF Get buffer size for output @item SO_RCVBUF Get buffer size for input @item SO_SNDLOWAT Get minimum count for output @item SO_RCVLOWAT Get minimum count for input @item SO_SNDTIMEO Get timeout value for output @item SO_RCVTIMEO Get timeout value for input @item SO_TYPE Get the type of the socket @item SO_ERROR Get and clear error on the socket @end table @code{SO_DEBUG} enables debugging in the underlying protocol modules. @code{SO_REUSEADDR} indicates that the rules used in validating addresses supplied in a @code{bind()} call should allow reuse of local addresses (@pxref{bind}). @code{SO_KEEPALIVE} enables the periodic transmission of messages on a connected socket. Should the connected party fail to respond to these messages, the connection is considered broken and processes using the socket are notified via a @samp{SIGPIPE} signal when attempting to send data. @code{SO_DONTROUTE} indicates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface according to the network portion of the destination address. @code{SO_LINGER} controls the action taken when unsent messages are queued on socket and a @code{close()} is performed (@pxref{close, , close, libc}). If the socket promises reliable delivery of data and @code{SO_LINGER} is set, the system will block the process on the @code{close()} attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a timeout period, termed the linger interval, is specified in the @code{setsockopt()} call when @code{SO_LINGER} is requested). If @code{SO_LINGER} is disabled and a @code{close()} is issued, the system will process the close in a manner that allows the process to continue as quickly as possible. The @samp{linger} structure is defined in @samp{sys/socket.h} as follows: @example struct linger @{ int l_onoff; /* Linger active */ int l_linger; /* How long to linger for */ @}; @end example @var{l_onoff} indicates whether to linger or not. If it is set to 1 then @var{l_linger} contains the time in hundredths of seconds how long the process should linger to complete the @code{close()}. If @var{l_onoff} is set to zero the process returns immediately. The option @code{SO_BROADCAST} requests permission to send broadcast datagrams on the socket. Broadcast was a privileged operation in earlier versions of the system. With protocols that support out-of-band data, the @code{SO_OOBINLINE} option requests that out-of-band data be placed in the normal data input queue as received; it will then be accessible with @code{recv()} or @samp{read()} calls without the @code{MSG_OOB} flag (@pxref{recv}, @pxref{read, , read, libc}). Some protocols behave as if this option were always set. @code{SO_SNDBUF} and @code{SO_RCVBUF} are options to adjust the normal buffer sizes allocated for output and input buffers, respectively. The buffer size may be increased for high-volume connections, or may be decreased to limit the possible backlog of incoming data. The system places an absolute limit on these values. @code{SO_SNDLOWAT} is an option to set the minimum count for output operations. Most output operations process all of the data supplied by the call, delivering data to the protocol for transmission and blocking as necessary for flow control. Nonblocking output operations will process as much data as permitted subject to flow control without blocking, but will process no data if flow control does not allow the smaller of the low water mark value or the entire request to be processed. A @code{select()} (@pxref{select, , select, libc}) operation testing the ability to write to a socket will return true only if the low water mark amount could be processed. The default value for @code{SO_SNDLOWAT} is set to a convenient size for network efficiency, often 1024. @code{SO_RCVLOWAT} is an option to set the minimum count for input operations. In general, receive calls (@pxref{recv}, @pxref{recvfrom}) will block until any (non-zero) amount of data is received, then return with smaller of the amount available or the amount requested. The default value for @code{SO_RCVLOWAT} is 1. If @code{SO_RCVLOWAT} is set to a larger value, blocking receive calls normally wait until they have received the smaller of the low water mark value or the requested amount. Receive calls may still return less than the low water mark if an error occurs, a signal is caught, or the type of data next in the receive queue is different than that returned. @code{SO_SNDTIMEO} is an option to get the timeout value for output operations. It returns a @code{struct timeval} parameter with the number of seconds and microseconds used to limit waits for output operations to complete. If a send operation has blocked for this much time, it returns with a partial count or with the error @samp{EWOULDBLOCK} if no data were sent. In the current implementation, this timer is restarted each time additional data are delivered to the protocol, implying that the limit applies to output portions ranging in size from the low water mark to the high water mark for output. @code{SO_RCVTIMEO} is an option to get the timeout value for input operations. It returns a @code{struct timeval} parameter with the number of seconds and microseconds used to limit waits for input operations to complete. In the current implementation, this timer is restarted each time additional data are received by the protocol, and thus the limit is in effect an inactivity timer. If a receive operation has been blocked for this much time without receiving additional data, it returns with a short count or with the error @samp{EWOULDBLOCK} if no data were received. @code{SO_TYPE} returns the type of the socket, such as @code{SOCK_STREAM}; it is useful for servers that inherit sockets on startup. @code{SO_ERROR} returns any pending error on the socket and clears the error status. It may be used to check for asynchronous errors on connected datagram sockets or for other asynchronous errors. @subheading Return Values On success, zero is returned. On error, -1 is returned, and @samp{errno} is set appropriately. @subheading Errors @table @samp @item EBADF The argument @var{s} is not a valid descriptor. @item ENOTSOCK The argument @var{s} is a file, not a socket. @item ENOPROTOOPT The option is unknown at the level indicated. @item EFAULT The address pointed to by @var{optval} is not in a valid part of the process address space. This error may also be returned if @var{optlen} is not in a valid part of the process address space. @end table @subheading Portability POSIX, Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node herror, if_freenameindex, getsockopt, Alphabetical List @unnumberedsec herror @c From file ./inet/herror.txh @findex herror @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat May 22 18:43:54 1993, David Metcalfe @c Modified Sun Jul 25 10:42:30 1993, Rik Faith (faith@cs.unc.edu) @c Modified Sun Feb 16 13:23:10 1997, Andries Brouwer (aeb@cwi.nl) @c @subheading Syntax @example #include extern int h_errno; void herror (const char *s); @end example @subheading Description The @code{herror()} function prints the error message associated with the current value of @code{h_errno} on stderr. The values for @var{h_errno} are described with @code{gethostbyname()} (@pxref{gethostbyname}). @subheading Return Values None @subheading Portability not Unix98 While the @code{herror()} function is not portable to Unix98, the @var{h_errno} variable is. @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node if_freenameindex, if_indextoname, herror, Alphabetical List @unnumberedsec if_freenameindex @c From file ./if_fni.txh @findex if_freenameindex @subheading Syntax @example #include void if_freenameindex (struct if_nameindex *ptr); @end example @subheading Description This function frees the memory used by the array returned by @xref{if_nameindex}. The program should not use @var{ptr} after calling @code{if_freenameindex()}. @subheading Return Value None. However, an error may occur. The error code will be stored in @var{errno}. Possible errors for this function are: @table @samp @item EFAULT The memory pointed to by @var{ptr} could not be accessed. @end table @subheading Portability Open Group XNS 5.2 Draft 1.0 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node if_indextoname, if_nameindex, if_freenameindex, Alphabetical List @unnumberedsec if_indextoname @c From file ./if_i2n.txh @findex if_indextoname @subheading Syntax @example #include char *if_nametoindex (unsigned int ifindex, char *ifname); @end example @subheading Description This returns the interface name corresponding to @var{ifindex} in the buffer @var{ifname}. The buffer pointed to @var{ifname} must be at least @samp{IFNAMESIZE} bytes in size. @subheading Return Value The interface name will be placed into @var{ifname}, if @var{ifindex} is a valid interface index. Otherwise @samp{NULL} is returned and @var{errno} contains the error code. Possible errors for this function are: @table @samp @item EFAULT The name pointed to by @var{ifname} cannot be accessed. @item ENXIO There is no interface referred to by @var{ifindex}. @end table @subheading Portability Open Group XNS 5.2 Draft 1.0 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node if_nameindex, if_nametoindex, if_indextoname, Alphabetical List @unnumberedsec if_nameindex @c From file ./if_ni.txh @findex if_nameindex @subheading Syntax @example #include struct if_nameindex *if_nameindex (void); @end example @subheading Description This function returns an array of @code{if_nameindex} structures, one per interface. The array is terminated with an entry with a @code{if_index} field of 0 and a @code{if_name} field of @code{NULL}. The function @code{if_freenameindex()} (@pxref{if_freenameindex}) should be called, passing the pointer returned by this function, in order to free memory. @subheading Return Value A pointer to the array of @code{if_nameindex} structures or @code{NULL} on error. On error, @var{errno} will contain the error code. Possible errors for this function are: @table @samp @item ENOBUFS There were insufficient system resources to complete the request. @end table @subheading Portability Open Group XNS 5.2 Draft 1.0 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node if_nametoindex, inet_addr, if_nameindex, Alphabetical List @unnumberedsec if_nametoindex @c From file ./if_n2i.txh @findex if_nametoindex @subheading Syntax @example #include unsigned int if_nametoindex (const char *ifname); @end example @subheading Description This returns the interface index corresponding to @var{ifname}. @subheading Return Value The interface index will be returned if @var{ifname} is an interface name, else 0. If an error occurs, -1 will be returned and the error will be stored in @var{errno}. Possible errors for this function are: @table @samp @item EFAULT The name pointed to by @var{ifname} cannot be accessed. @end table @subheading Portability Open Group XNS 5.2 Draft 1.0 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node inet_addr, inet_aton, if_nametoindex, Alphabetical List @unnumberedsec inet_addr @c From file ./inet/i_addr.txh @findex inet_addr @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Hey Emacs! This file is -*- nroff -*- source. @c @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c libc.info (from glibc distribution) @c Modified Sat Jul 24 19:12:00 1993 by Rik Faith (faith@cs.unc.edu) @c Modified Sun Sep 3 20:29:36 1995 by Jim Van Zandt @subheading Syntax @example #include #include #include unsigned long int inet_addr (const char *cp); @end example @subheading Description The @code{inet_addr()} function converts the Internet host address @var{cp} from numbers-and-dots notation into binary data in network byte order. If the input is invalid, -1 is returned. This is an @emph{obsolete} interface to @code{inet_aton()} (@pxref{inet_aton}); it is obsolete because -1 is a valid address (255.255.255.255), and @code{inet_aton()} provides a cleaner way to indicate error return. @subheading Return Values If the input is invalid, -1 is returned. Otherwise, the IP address is returned as a 32-bit unsigned integer in network order. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node inet_aton, inet_lnaof, inet_addr, Alphabetical List @unnumberedsec inet_aton @c From file ./inet/i_aton.txh @findex inet_aton @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Hey Emacs! This file is -*- nroff -*- source. @c @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c libc.info (from glibc distribution) @c Modified Sat Jul 24 19:12:00 1993 by Rik Faith (faith@cs.unc.edu) @c Modified Sun Sep 3 20:29:36 1995 by Jim Van Zandt @subheading Syntax @example #include #include #include int inet_aton (const char *cp, struct in_addr *inp); @end example @subheading Description @code{inet_aton()} converts the Internet host address @var{cp} from the standard numbers-and-dots notation into binary data and stores it in the structure that @var{inp} points to. The structure @code{in_addr} is defined in the description of @code{inet_ntoa()} (@pxref{inet_ntoa}). @subheading Return Values Non-zero is returned, if the address is valid; otherwise zero is returned. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node inet_lnaof, inet_makeaddr, inet_aton, Alphabetical List @unnumberedsec inet_lnaof @c From file ./inet/i_lnaof.txh @findex inet_lnaof @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Hey Emacs! This file is -*- nroff -*- source. @c @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c libc.info (from glibc distribution) @c Modified Sat Jul 24 19:12:00 1993 by Rik Faith (faith@cs.unc.edu) @c Modified Sun Sep 3 20:29:36 1995 by Jim Van Zandt @subheading Syntax @example #include #include #include unsigned long int inet_lnaof (struct in_addr in); @end example @subheading Description The @code{inet_lnaof()} function returns the local host address part of the Internet address @var{in}. The local host address is returned in local host byte order. The structure @code{in_addr} is defined in the description of @code{inet_ntoa()} (@pxref{inet_ntoa}). @subheading Return Values The local host address portion is returned. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node inet_makeaddr, inet_netof, inet_lnaof, Alphabetical List @unnumberedsec inet_makeaddr @c From file ./inet/i_mkaddr.txh @findex inet_makeaddr @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Hey Emacs! This file is -*- nroff -*- source. @c @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c libc.info (from glibc distribution) @c Modified Sat Jul 24 19:12:00 1993 by Rik Faith (faith@cs.unc.edu) @c Modified Sun Sep 3 20:29:36 1995 by Jim Van Zandt @subheading Syntax @example #include #include #include struct in_addr inet_makeaddr (int net, int host); @end example @subheading Description The @code{inet_makeaddr()} function makes an Internet host address in network byte order by combining the network number @var{net} with the local address @var{host} in network @var{net}, both in local host byte order. The structure @code{in_addr} is defined in the description of @code{inet_ntoa()} (@pxref{inet_ntoa}). @subheading Return Values An Internet host addess is returned. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node inet_netof, inet_network, inet_makeaddr, Alphabetical List @unnumberedsec inet_netof @c From file ./inet/i_netof.txh @findex inet_netof @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Hey Emacs! This file is -*- nroff -*- source. @c @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c libc.info (from glibc distribution) @c Modified Sat Jul 24 19:12:00 1993 by Rik Faith (faith@cs.unc.edu) @c Modified Sun Sep 3 20:29:36 1995 by Jim Van Zandt @subheading Syntax @example #include #include #include unsigned long int inet_netof (struct in_addr in); @end example @subheading Description The @code{inet_netof()} function returns the network number part of the Internet Address @var{in}. The network number is returned in local host byte order. The structure @code{in_addr} is defined in the description of @code{inet_ntoa()} (@pxref{inet_ntoa}). @subheading Return Values The network number portion is returned. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node inet_network, inet_ntoa, inet_netof, Alphabetical List @unnumberedsec inet_network @c From file ./inet/i_net.txh @findex inet_network @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Hey Emacs! This file is -*- nroff -*- source. @c @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c libc.info (from glibc distribution) @c Modified Sat Jul 24 19:12:00 1993 by Rik Faith (faith@cs.unc.edu) @c Modified Sun Sep 3 20:29:36 1995 by Jim Van Zandt @subheading Syntax @example #include #include #include unsigned long int inet_network (const char *cp); @end example @subheading Description The @code{inet_network()} function extracts the network number in network byte order from the address @var{cp} in numbers-and-dots notation. @subheading Return Values If the input is invalid, -1 is returned. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node inet_ntoa, inet_ntop, inet_network, Alphabetical List @unnumberedsec inet_ntoa @c From file ./inet/i_ntoa.txh @findex inet_ntoa @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Hey Emacs! This file is -*- nroff -*- source. @c @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c libc.info (from glibc distribution) @c Modified Sat Jul 24 19:12:00 1993 by Rik Faith (faith@cs.unc.edu) @c Modified Sun Sep 3 20:29:36 1995 by Jim Van Zandt @subheading Syntax @example #include #include #include char *inet_ntoa (struct in_addr in); @end example @subheading Description The @code{inet_ntoa()} function converts the Internet host address @var{in} given in network byte order to a string in standard numbers-and-dots notation. The string is returned in a statically allocated buffer, which subsequent calls will overwrite. The structure @code{in_addr} is defined in @samp{netinet/in.h} as: @example struct in_addr @{ unsigned long int s_addr; @} @end example Note that on the i80x86 the host byte order is Least Significant Byte first, whereas the network byte order, as used on the Internet, is Most Significant Byte first. @subheading Return Value @code{inet_ntoa()} returns a pointer to the address in string form. @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node inet_ntop, inet_pton, inet_ntoa, Alphabetical List @unnumberedsec inet_ntop @c From file ./inet/i_ntop.txh @findex inet_ntop @subheading Syntax @example #include #include const char *inet_ntop (int af, const void *src, char *dst, size_t size); @end example @subheading Description This function converts network addresses from numeric format (i.e. binary) into presentation format (i.e. strings). This is a replacement for @code{inet_ntoa} (@pxref{inet_ntoa}), which cannot cope with IPv6 addresses. @var{af} specifies the address family of the numeric format, e.g. @code{AF_INET} or @code{AF_INET6}. The numeric data in @var{src} will be converted in presentation format and stored in @var{dst}. @var{size} specifies the size of the buffer pointed to by @var{dst} - it must be large enough to store the presentation format address. The constants @code{INET_ADDRSTRLEN} and @code{INET6_ADDRSTRLEN} are defined in @samp{netinet/in.h} as the maximum presentation string lengths, including terminating nuls. @subheading Return Values On successful completion the function returns a pointer to the presentation format string. Otherwise, a value of NULL is returned and @var{errno} is set appropriately. @table @samp @item EFAULT @var{dst} did not point to a valid buffer. @item ENOSPC The size of @var{dst} specified by @var{size} was not large enough to store the presentation format string. @item EAFNOSUPPORT The address family @var{af} is not known or supported. @end table @subheading Portability POSIX @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node inet_pton, ioctl_list, inet_ntop, Alphabetical List @unnumberedsec inet_pton @c From file ./inet/i_pton.txh @findex inet_pton @subheading Syntax @example #include #include int inet_pton (int af, const char *src, void *dst); @end example @subheading Description This function converts network addresses from presentation format (i.e. strings) into numeric format (i.e. binary). This is a replacement for @code{inet_aton} (@pxref{inet_aton}), which cannot cope with IPv6 addresses. @var{af} specifies the address family of the presentation format, e.g. @code{AF_INET} or @code{AF_INET6}. The address string @var{src} will be converted to the appropriate address format, e.g. @code{struct in_addr} or @code{struct in6_addr}, and stored in @var{dst}. @subheading Return Values On successful completion the function returns 1. If the presentation format is not understood, 0 is returned. If the address family @var{af} is not known or supported, -1 is returned and @var{errno} is set to @samp{EAFNOSUPPORT}. @subheading Portability POSIX @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node ioctl_list, isfdtype, inet_pton, Alphabetical List @unnumberedsec ioctl_list @c From file ./ioctl_l.txh @subheading Syntax @example #include #include #include #include @end example @subheading Description @c TODO: More ioctls? This page documents the ioctls that are supported by libsocket. These are used with the @code{ioctl()} function (@pxref{ioctl, , ioctl, libc}). Many BSD ioctls are not listed here, because libsocket does not support them. Some BSD socket ioctls are supported. @table @samp @item FIONBIO This can be used to toggle non-blocking I/O. @code{ioctl()} should be passed an integer - if this is non-zero, non-blocking I/O will be enabled, otherwise blocking I/O will be used. @example /* Flip into non-blocking mode */ int x = 1; ioctl(sock, FIONBIO, &x); @end example @code{FIONBIO} is like the @code{O_NONBLOCK} flag that can be set using @code{fcntl()} (@pxref{fcntl, , libc, libc}): @example /* Flip into non-blocking mode */ int flags = flags = fcntl(sock, F_GETFL); flags |= O_NONBLOCK; fcntl(sock, F_SETFL, flags); @end example @item FIONREAD This can be used to discover the maximum atomic read that can be performed on the socket, i.e. the largest single read operation. @code{ioctl()} should be passed an integer - on return this will contain the maximum read size. @example int maxsz = 0; ioctl(sock, FIONREAD, &maxsz) @end example @item SIOCATMARK This determines if all out-of-band data has been read. This only applies to @code{SOCK_STREAM} type sockets that have been set with the option @code{SO_OOBINLINE} (@pxref{getsockopt}, @pxref{setsockopt}). It returns 1 (true) or 0 (false) in the ioctl parameter. The @code{sockatmark()} function should be used instead (@pxref{sockatmark}). @item SIOCGIFNAME This copies the interface name into a user buffer of size @code{IFNAMSIZ}. The pointer to the buffer is passed as the parameter to ioctl, e.g. @example ioctl(sock, SIOCGIFNAME, (int *) name) @end example @item SIOCGIFADDR This copies the local socket address into a user structure of type @code{struct ifreq}. The pointer to the buffer is passed as the parameter to ioctl, e.g. @example ioctl(sock, SIOCGIFADDR, (int *) &ifr) @end example The socket address can then be accessed via the @code{ifr_ifru.ifru_addr} member of @code{struct ifreq}. @item SIOCGIFDSTADDR This copies the peer's socket address into a user structure of type @code{struct ifreq}. The pointer to the buffer is passed as the parameter to ioctl, e.g. @example ioctl(sock, SIOCGIFDSTADDR, (int *) &ifr) @end example The peer's socket address can then be accessed via the @code{ifr_ifru.ifru_dstaddr} member of @code{struct ifreq}. @item SIOCGIFNETMASK This copies the socket's network mask into a user structure of type @code{struct ifreq}. The pointer to the buffer is passed as the parameter to ioctl, e.g. @example ioctl(sock, SIOCGIFDSTADDR, (int *) &ifr) @end example The peer's socket address can then be accessed via the @code{ifr_ifru.ifru_netmask} member of @code{struct ifreq}. @end table @subheading Return Values @subheading Portability ioctls cannot be guaranteed to be portable. However, because of the ubiquity of BSD sockets, these ioctls should work on most Unices. @c ----------------------------------------------------------------------------- @node isfdtype, listen, ioctl_list, Alphabetical List @unnumberedsec isfdtype @c From file ./isfdtype.txh @findex isfdtype @subheading Syntax @example #include int isfdtype (int fd, int fd_type); @end example @subheading Description The @code{isfdtype()} function determines whether the file descriptor @var{fd} has the properties specified by @var{fd_type}. Valid values of @var{fd_type} include: @table @samp @item S_IFSOCK Tests whether @var{fd} is a socket @end table @subheading Return Value 1 if the type matches, 0 otherwise. If an error occurs, -1 is returned and @var{errno} is set to: @table @samp @item EBADF @var{fd} is not a valid file descriptor. @end table @subheading Portability POSIX, not Unix98 @code{isfdtype()} is usually declared in @samp{sys/stat.h} rather than @samp{sys/socket.h}. @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node listen, __lsck_get_copyright, isfdtype, Alphabetical List @unnumberedsec listen @c From file ./listen.txh @findex listen @subheading Syntax @example #include int listen (int s, int backlog); @end example @subheading Description To create a passive/listening (server) socket, a socket is created with @code{socket()} (@pxref{socket}), bound to a local address with @code{bind()} (@pxref{bind}) and then given a connection queue with @code{listen()}. Connections can then be accepted with @code{accept()} (@pxref{accept}). @code{listen()} sets the maximum number of connections, @var{backlog}, that can be waiting for handling by @code{accept()}. Any further waiting connections will be refused. @code{listen()} is only a valid operation for sockets of type @code{SOCK_STREAM} or @code{SOCK_SEQPACKET}. @subheading Return Value On successful completion the function returns 0. Otherwise, a value of -1 is returned and @var{errno} is set appropriately. @table @samp @item EBADF @var{s} is not a valid file descriptor. @item ENOTSOCK @var{s} is not a socket. @item EOPNOTSUPP @code{listen()} is not a valid operation on this type of socket. @end table @subheading Portability POSIX, Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node __lsck_get_copyright, __lsck_get_version, listen, Alphabetical List @unnumberedsec __lsck_get_copyright @c From file ./glcopy.txh @findex __lsck_get_copyright @subheading Syntax @example #include char *__lsck_get_copyright (void); @end example @subheading Description This function returns a string containing the copyright information for libsocket. If this is longer than one line, it will be formatted to fit on an 80-column terminal. @subheading Return Values A pointer to the string is returned on success; on failure, @samp{NULL} is returned. @subheading Portability not ANSI, not POSIX, not Unix98 This function is specific to libsocket. @subheading Example @example char *p = __lsck_get_copyright(); puts(p); @end example @c ----------------------------------------------------------------------------- @node __lsck_get_version, rcmd, __lsck_get_copyright, Alphabetical List @unnumberedsec __lsck_get_version @c From file ./glver.txh @findex __lsck_get_version @subheading Syntax @example #include char *__lsck_get_version (void); @end example @subheading Description This function returns a string containing the version information for libsocket. If this is longer than one line, it will be formatted to fit on an 80-column terminal. @vindex LSCK_VERSION_MAJOR @vindex LSCK_VERSION_MINOR @vindex LSCK_VERSION_SUBMINOR The version message is constructed from constants defined in @samp{lsck/copyrite.h}. The ones that should be used in user programs are listed in the table below. As an example, consider the version number 0.8.0. @table @samp @item LSCK_VERSION_MAJOR This is libsocket's major version, which is @samp{0} for the example. @item LSCK_VERSION_MINOR This is libsocket's minor version, which is @samp{8} for the example. @item LSCK_VERSION_SUBMINOR This is libsocket's minor-minor or subminor version, which is @samp{0} for the example. @end table @subheading Return Values A pointer to the string is returned on success; on failure, @samp{NULL} is returned. @subheading Portability not ANSI, not POSIX, not Unix98 This function is specific to libsocket. @subheading Example @example char *p = __lsck_get_version(); puts(p); @end example @c ----------------------------------------------------------------------------- @node rcmd, readv, __lsck_get_version, Alphabetical List @unnumberedsec rcmd @c From file ./inet/rcmd.txh @findex rcmd @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c $NetBSD: rcmd.3,v 1.9 1996/05/28 02:07:39 mrg Exp $ @c @c Copyright (c) 1983, 1991, 1993 @c The Regents of the University of California. All rights reserved. @c @c Redistribution and use in source and binary forms, with or without @c modification, are permitted provided that the following conditions @c are met: @c 1. Redistributions of source code must retain the above copyright @c notice, this list of conditions and the following disclaimer. @c 2. Redistributions in binary form must reproduce the above copyright @c notice, this list of conditions and the following disclaimer in the @c documentation and/or other materials provided with the distribution. @c 3. All advertising materials mentioning features or use of this software @c must display the following acknowledgement: @c This product includes software developed by the University of @c California, Berkeley and its contributors. @c 4. Neither the name of the University nor the names of its contributors @c may be used to endorse or promote products derived from this software @c without specific prior written permission. @c @c THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND @c ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE @c IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE @c ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE @c FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL @c DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS @c OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) @c HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT @c LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY @c OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF @c SUCH DAMAGE. @c @c @(#)rcmd.3 8.1 (Berkeley) 6/4/93 @c @c Contributed as Linux man page by David A. Holland, 970908 @c I have not checked whether the Linux situation is exactly the same. @c @c Modified by Richard Dawe for incorporation into @c libsocket 0.7.4. @c @subheading Syntax @example #include #include int rcmd (char **ahost, int inport, const char *locuser, const char *remuser, const char *cmd, int *fd2p); @end example @subheading Description The @code{rcmd()} function is used by the super-user to execute a command on a remote machine using an authentication scheme based on reserved port numbers. The @code{rcmd()} function looks up the host @var{*ahost} using @code{gethostbyname()} (@pxref{gethostbyname}), returning -1 if the host does not exist. Otherwise @var{*ahost} is set to the standard name of the host and a connection is established to a server residing at the well-known Internet port @var{inport}. If the connection succeeds, a socket in the Internet domain of type @code{SOCK_STREAM} is returned to the caller, and given to the remote command as stdin and stdout. If @var{fd2p} is non-zero, then an auxiliary channel to a control process will be set up, and a descriptor for it will be placed in @var{*fd2p}. The control process will return diagnostic output from the command (unit 2) on this channel, and will also accept bytes on this channel as being UNIX signal numbers, to be forwarded to the process group of the command. If @var{fd2p} is 0, then the stderr (unit 2 of the remote command) will be made the same as the stdout and no provision is made for sending arbitrary signals to the remote process, although you may be able to get its attention by using out-of-band data. The protocol is described in detail in the rshd documentation. @subheading Return Value The @code{rcmd()} function returns a valid socket descriptor on success. It returns -1 on error and prints a diagnostic message on the standard error. @subheading Portability libsocket declares this function in @samp{sys/socket.h}, but it's usually defined in @samp{unistd.h}. @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node readv, recv, rcmd, Alphabetical List @unnumberedsec readv @c From file ./readv.txh @findex readv @subheading Syntax @example #include ssize_t readv (int fd, const struct iovec *iov, int iovcnt); @end example @subheading Description @code{readv()} performs a scatter-gather read from the specified file descriptor @var{fd}. The data is written into a group of buffers described by the array @var{iov} with @var{iovcnt} entries in a similar way to @code{read()} (@pxref{read, , read, libc}). @code{struct iovec} is described in the section on @code{writev()} (@pxref{writev}). @subheading Return Value On successful completion the function returns the number of bytes read. Otherwise, a value of -1 is returned and @var{errno} is set appropriately. @table @samp @item EINVAL One of the following conditions is true: @itemize @bullet @item The total length to read could overflow a @code{ssize_t}. @item @var{iovcnt} was negative, zero or larger than @code{IOV_MAX}. @end itemize @end table @subheading Portability POSIX, Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node recv, recvfrom, readv, Alphabetical List @unnumberedsec recv @c From file ./recv.txh @findex recv @subheading Syntax @example #include #include ssize_t recv (int s, void * buf, size_t len, int flags); @end example @subheading Description The @code{recv()} function is used on a connected socket and is identical to @code{recvfrom()} (@pxref{recvfrom}) with NULL @var{from} and @var{fromlen} parameters. @subheading Return Values On success the number of octets received is return, or -1 and errno is set. @xref{recvfrom}. @subheading Portability POSIX, Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node recvfrom, res_init, recv, Alphabetical List @unnumberedsec recvfrom @c From file ./recvfm.txh @findex recvfrom @subheading Syntax @example #include #include ssize_t recvfrom (int s, void * buf, size_t len, unsigned int flags, struct sockaddr *from, size_t *fromlen); @end example @subheading Description @code{recvfrom()} is used to receive messages from a socket. If @var{from} is non-NULL, the source address of the message is stored in it. @var{fromlen} is a value-result parameter, it indicates the size of @var{from} on entry and the size of @var{from} stored. If @var{fromlen} was too small, it is truncated to the initial size. @var{flags} may have the value zero or be the bitwise OR of any combination of one or more of the values: @table @samp @item MSG_OOB Receipt of out-of-band data that would not be received in the normal data stream. Application should use MSG_OOB flag after catching a SIGURG or if @code{select()} (@pxref{select, , select, libc}) indicates an exception condition. @item MSG_PEEK The receive operation data from the beginning of the receive queue without removing that data from the queue. Thus, a subsequent receive call will return the same data. @item MSG_WAITALL Requests that the operation block until the full request is satisfied. However, the call may still return less data than requested if a signal is caught, an error or disconnect occurs, or the next data to be received is of a different type than that returned. @end table @subheading Return Values On success the number of octets received is return, or -1 and @var{errno} is set: @table @samp @item EWOULDBLOCK. The socket is marked non-blocking and the receive operation would block. @item EBADF The paramater is not a valid descriptor. @item ENOTCONN The socket is associated with a connection-oriented protocol and has not been connected. @item ENOTSOCK The argument does not refer to a socket. @item EINTR The receive was interrupted by delivery of a signal before any data were available. @item EFAULT The receive buffer pointer(s) point outside the process's address space. @end table @subheading Portability POSIX, Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node res_init, res_mkquery, recvfrom, Alphabetical List @unnumberedsec res_init @c From file ./inet/r_init.txh @findex res_init @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sun Jul 25 11:01:53 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include #include #include extern struct state _res; int res_init (void); @end example @subheading Description The @code{res_init()} function reads the configuration files (@pxref{host.conf}, @pxref{resolv.conf}) to get the default domain name, search order and name server address(es). If no server is given, the local host is tried. If no domain is given, that associated with the local host is used. It can be overridden with the environment variable @samp{LOCALDOMAIN}. @code{res_init()} is normally executed by the first call to one of the other resolver functions, e.g. @code{res_query()}, @code{gethostbyname()} (@pxref{res_query}, @pxref{gethostbyname}). @subheading Return Value The @code{res_init()} function returns 0 on success, or -1 if an error occurs. @subheading Portability This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux. @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node res_mkquery, res_query, res_init, Alphabetical List @unnumberedsec res_mkquery @c From file ./inet/r_mkqry.txh @findex res_mkquery @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sun Jul 25 11:01:53 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include #include #include extern struct state _res; int res_mkquery (int op, const char *dname, int class, int type, char *data, int datalen, struct rrec *newrr, char *buf, int buflen); @end example @subheading Description This function is a low-level routine used by @ref{res_query}. The @code{res_mkquery()} function constructs a query message in @var{buf} of length @var{buflen} for the domain name @var{dname}. The query type @var{op} is usually @samp{QUERY}, but can be any of the types defined in @samp{arpa/nameser.h}. @var{newrr} is currently unused. The resolver routines use global configuration and state information contained in the structure @code{_res}, which is described with @code{res_query()} (@pxref{res_query}). @subheading Return Value The @code{res_mkquery()} function returns the length of the response, or -1 if an error occurs. @subheading Portability This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux. @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node res_query, res_querydomain, res_mkquery, Alphabetical List @unnumberedsec res_query @c From file ./inet/r_qry.txh @findex res_query @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sun Jul 25 11:01:53 1993 by Rik Faith (faith@cs.unc.edu) @example #include #include #include extern struct state _res; int res_query (const char *dname, int class, int type, unsigned char *answer, int anslen); @end example @subheading Description The @code{res_query()} function queries the name server for the fully-qualified domain name @var{name} of specified @var{type} and @var{class}. The reply is left in the buffer @var{answer} of length @var{anslen} supplied by the caller. The resolver routines use global configuration and state information contained in the structure @code{_res}, which is defined in @samp{}. The only field that is normally manipulated by the user is @code{_res.options}. This field can contain the bitwise OR of the following options: @vtable @samp @item RES_INIT True if @code{res_init()} has been called. @item RES_DEBUG Print debugging messages. @item RES_AAONLY Accept authoritative answers only. @code{res_send()} continues until it fins an authoritative answer or returns an error. [Not currently implemented]. @item RES_USEVC Use TCP connections for queries rather than UDP datagrams. @item RES_PRIMARY Query primary domain name server only. @item RES_IGNTC Ignore truncation errors. Don't retry with TCP. [Not currently implemented]. @item RES_RECURSE Set the recursion desired bit in queries. Recursion is carried out by the domain name server, not by @code{res_send()}. [Enabled by default]. @item RES_DEFNAMES If set, @code{res_search()} will append the default domain name to single component names, ie. those that do not contain a dot. [Enabled by default]. @item RES_STAYOPEN Used with RES_USEVC to keep the TCP connection open between queries. @item RES_DNSRCH If set, @code{res_search()} will search for host names in the current domain and in parent domains. This option is used by @code{gethostbyname()} (@pxref{gethostbyname}). [Enabled by default]. @end vtable @subheading Return Value @code{res_query()} returns the length of the response, or -1 if an error occurs. @subheading Portability This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux. @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node res_querydomain, res_search, res_query, Alphabetical List @unnumberedsec res_querydomain @c From file ./inet/r_qrydom.txh @findex res_querydomain @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sun Jul 25 11:01:53 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include #include #include extern struct state _res; int res_querydomain (const char *name, const char *domain, int class, int type, unsigned char *answer, int anslen); @end example @subheading Description The @code{res_querydomain()} function makes a query using @code{res_query()} (@pxref{res_query}) on the concatenation of @var{name} and @var{domain}. The resolver routines use global configuration and state information contained in the structure @code{_res}, which is described in @code{res_query()} (@pxref{res_query}). @subheading Return Value The @code{res_querydomain()} function returns the length of the response, or -1 if an error occurs. @subheading Portability This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux. @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node res_search, res_send, res_querydomain, Alphabetical List @unnumberedsec res_search @c From file ./inet/r_search.txh @findex res_search @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sun Jul 25 11:01:53 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include #include #include extern struct state _res; int res_search(const char *dname, int class, int type, unsigned char *answer, int anslen); @end example @subheading Description The @code{res_search()} function makes a query and waits for the response like @code{res_query()} (@pxref{res_query}, but in addition implements the default and search rules controlled by @code{RES_DEFNAMES} and @code{RES_DNSRCH} (see description of @code{_res} with @code{res_query()} (@pxref{res_query})). @subheading Return Value The @code{res_search()} function returns the length of the response, or -1 if an error occurs. @subheading Portability This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux. @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node res_send, rexec, res_search, Alphabetical List @unnumberedsec res_send @c From file ./inet/r_send.txh @findex res_send @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sun Jul 25 11:01:53 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include #include #include extern struct state _res; int res_send (const char *msg, int msglen, char *answer, int anslen); @end example @subheading Description This function is a low-level routine used by @code{res_query()} (@pxref{res_query}). The @code{res_send()} function sends a pre-formatted query given in @var{msg} of length @var{msglen} and returns the answer in @var{answer} which is of length @var{anslen}. It will call @code{res_init()} (@pxref{res_init}), if it has not already been called. The resolver routines use global configuration and state information contained in the structure @code{_res}, which is described with @code{res_query()} (@pxref{res_query}). @subheading Return Value The @code{res_send()} function returns the length of the response, or -1 if an error occurs. @subheading Portability This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux. @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node rexec, rresvport, res_send, Alphabetical List @unnumberedsec rexec @c From file ./inet/rexec.txh @findex rexec @subheading Syntax @example #include int rexec (char **ahost, int rport, const char *name, const char *pass, const char *cmd, int *fd2p); @end example @subheading Description @c TODO: Write a description? OK, so what does it do? Under construction - if you have a good description, please inform the libsocket maintainer. @subheading Return Value @subheading Portability @c TODO @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node rresvport, ruserok, rexec, Alphabetical List @unnumberedsec rresvport @c From file ./inet/rresvpt.txh @findex rresvport @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c $NetBSD: rcmd.3,v 1.9 1996/05/28 02:07:39 mrg Exp $ @c @c Copyright (c) 1983, 1991, 1993 @c The Regents of the University of California. All rights reserved. @c @c Redistribution and use in source and binary forms, with or without @c modification, are permitted provided that the following conditions @c are met: @c 1. Redistributions of source code must retain the above copyright @c notice, this list of conditions and the following disclaimer. @c 2. Redistributions in binary form must reproduce the above copyright @c notice, this list of conditions and the following disclaimer in the @c documentation and/or other materials provided with the distribution. @c 3. All advertising materials mentioning features or use of this software @c must display the following acknowledgement: @c This product includes software developed by the University of @c California, Berkeley and its contributors. @c 4. Neither the name of the University nor the names of its contributors @c may be used to endorse or promote products derived from this software @c without specific prior written permission. @c @c THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND @c ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE @c IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE @c ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE @c FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL @c DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS @c OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) @c HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT @c LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY @c OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF @c SUCH DAMAGE. @c @c @(#)rcmd.3 8.1 (Berkeley) 6/4/93 @c @c Contributed as Linux man page by David A. Holland, 970908 @c I have not checked whether the Linux situation is exactly the same. @c @c Modified by Richard Dawe for incorporation into @c libsocket 0.7.4. @c @subheading Syntax @example #include #include int rresvport (int *port); @end example @subheading Description The @code{rresvport()} function is used to obtain a socket with a privileged address bound to it. This socket is suitable for use by @code{rcmd()} (@pxref{rcmd}) and several other functions. Privileged Internet ports are those in the range 0 to 1023. Only the super-user is allowed to bind an address of this sort to a socket. @subheading Return Value The @code{rresvport()} function returns a valid, bound socket descriptor on success. It returns -1 on error with @var{errno} set according to the reason for failure. The error code @samp{EAGAIN} is overloaded to mean "All network ports in use". @subheading Portability @c TODO libsocket declares this function in @samp{sys/socket.h}, but it's usually defined in @samp{unistd.h}. @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node ruserok, send, rresvport, Alphabetical List @unnumberedsec ruserok @c From file ./inet/ruserok.txh @findex ruserok @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c $NetBSD: rcmd.3,v 1.9 1996/05/28 02:07:39 mrg Exp $ @c @c Copyright (c) 1983, 1991, 1993 @c The Regents of the University of California. All rights reserved. @c @c Redistribution and use in source and binary forms, with or without @c modification, are permitted provided that the following conditions @c are met: @c 1. Redistributions of source code must retain the above copyright @c notice, this list of conditions and the following disclaimer. @c 2. Redistributions in binary form must reproduce the above copyright @c notice, this list of conditions and the following disclaimer in the @c documentation and/or other materials provided with the distribution. @c 3. All advertising materials mentioning features or use of this software @c must display the following acknowledgement: @c This product includes software developed by the University of @c California, Berkeley and its contributors. @c 4. Neither the name of the University nor the names of its contributors @c may be used to endorse or promote products derived from this software @c without specific prior written permission. @c @c THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND @c ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE @c IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE @c ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE @c FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL @c DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS @c OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) @c HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT @c LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY @c OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF @c SUCH DAMAGE. @c @c @(#)rcmd.3 8.1 (Berkeley) 6/4/93 @c @c Contributed as Linux man page by David A. Holland, 970908 @c I have not checked whether the Linux situation is exactly the same. @c @c Modified by Richard Dawe for incorporation into @c libsocket 0.7.4. @c @subheading Syntax @example #include #include int ruserok (const char *rhost, int superuser, const char *ruser, const char *luser); @end example @subheading Description The @code{ruserok()} function is used by servers to authenticate clients requesting service with @code{rcmd()} (@pxref{rcmd}). @c TODO: Doc /etc/hosts.equiv @c TODO: Doc .rhosts The @code{ruserok()} function takes a remote host's name, two user names and a flag indicating whether the local user's name is that of the super-user. Then, if the user is *NOT* the super-user, it checks the @samp{/etc/hosts.equiv} file. If that lookup is not done, or is unsuccessful, the @samp{.rhosts} in the local user's home directory is checked to see if the request for service is allowed. If this file does not exist, is not a regular file, is owned by anyone other than the user or the super-user, or is writeable by anyone other than the owner, the check automatically fails. If the local domain (as obtained from @code{gethostname()} (@pxref{gethostname}) is the same as the remote domain, only the machine name need be specified. @subheading Return Value Zero is returned if the machine name is listed in the @samp{hosts.equiv} file, or the host and remote user name are found in the @samp{.rhosts} file; otherwise -1 is returned. @subheading Portability @c TODO libsocket declares this function in @samp{sys/socket.h}, whereas it's usually defined in @samp{unistd.h}. @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node send, sendto, ruserok, Alphabetical List @unnumberedsec send @c From file ./send.txh @findex send @subheading Syntax @example #include #include int send (int s, const void * msg, size_t len, int flags); @end example @subheading Description The @code{send()} function is used to transmit data to a peer via socket, @code{send()} is equivalent to @code{sendto()} (@pxref{sendto}) call with a NULL to parameter to and tolen. @subheading Return values The function return the number of octets accepted for transmission, Otherwise -1 with errno set. See @xref{sendto}. @subheading Portability POSIX, Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node sendto, setdomainname, send, Alphabetical List @unnumberedsec sendto @c From file ./sendto.txh @findex sendto @subheading Syntax @example #include #include ssize_t sendto (int s, const void * msg, size_t len, int flags, const struct sockaddr *to, size_t tolen); @end example @subheading Description The function @code{sendto()} is used to transmit a message to another socket. The address of the target is given by @var{to} with @var{tolen} specifying its size. A NULL value fo @var{to} indicats that no socket-address is specifiend and the socket is in the CONNECTED state, the corresponding @var{tolen} is then ignored. The length of the message is given by @var{len}. If the message is too long to pass atomically through the underlying protocol, the error @samp{EMSGSIZE} is returned, and the message is not transmitted. If no messages space is available at the socket to hold the message to be transmitted, then @code{sendto} normally blocks, unless the socket has been placed in non-blocking I/O mode. The @code{select()} (@pxref{select, , select, libc}) call may be used to determine when it is possible to send more data. The @var{flags} parameter may include one or more of the following: @table @samp @item MSG_OOB Used to send @samp{out-of-band} data on sockets that support this notion. @item MSG_DONTROUTE Used only by diagnostic or routing programs. @item MSG_EOR Terminates a record for protocols which support that concept. @end table @subheading Return values The call returns the number of characters sent, or -1 and @var{errno} set, if an error occurred. @table @samp @item EBADF An invalid descriptor was specified. @item ENOTSOCK The argument @samp{s} is not a socket. @item EFAULT An invalid user space address was specified for a parameter. @item EMSGSIZE The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. @item EWOULDBLOCK The socket is marked non-blocking and the requested operation would block. @item EPIPE The socket is shut for writing (@pxref{shutdown}). If the socket is a stream, the SIGPIPE signal is raised (@pxref{signal, , signal, libc}). @item ENOBUFS The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. @end table @subheading Portability POSIX, Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node setdomainname, sethostent, sendto, Alphabetical List @unnumberedsec setdomainname @c From file ./sdomname.txh @findex setdomainname @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Hey Emacs! This file is -*- nroff -*- source. @c @c Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @subheading Syntax @example #include int setdomainname (const char *name, size_t len); @end example @subheading Description This function is used to change the domain name. The domain name can be accessed using @code{getdomainname()} (@pxref{getdomainname}). @subheading Return Value On success, zero is returned. On error, -1 is returned, and @var{errno} is set appropriately. @subheading Errors @table @samp @item EPERM The caller was not the superuser. @item EINVAL @var{len} was too long. @end table @subheading Portability not POSIX, not Unix98 This function is defined in @samp{unistd.h} on Linux. @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node sethostent, sethostname, setdomainname, Alphabetical List @unnumberedsec sethostent @c From file ./inet/shstent.txh @findex sethostent @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat May 22 18:43:54 1993, David Metcalfe @c Modified Sun Jul 25 10:42:30 1993, Rik Faith (faith@cs.unc.edu) @c Modified Sun Feb 16 13:23:10 1997, Andries Brouwer (aeb@cwi.nl) @c @subheading Syntax @example #include extern int h_errno; void sethostent (int stayopen); @end example @subheading Description The @code{sethostent()} function specifies, if @var{stayopen} is true (1), that a connected TCP socket should be used for the name server queries and that the connection should remain open during successive queries. Otherwise, name server queries will use UDP datagrams. @subheading Return Values None @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node sethostname, setnetent, sethostent, Alphabetical List @unnumberedsec sethostname @c From file ./shstnm.txh @findex sethostname @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Hey Emacs! This file is -*- nroff -*- source. @c @c Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c Modified 22 July 1995 by Michael Chastain : @c 'gethostname' is real system call on Linux/Alpha. @c Modified Fri Jan 31 16:30:53 1997 by Eric S. Raymond @example #include #include int sethostname (const char *name, size_t len); @end example @subheading Description This function is used to change the host name of the current processor. The host name is retrieved using @code{gethostname()} (@pxref{gethostname}). The domain name component can be retrieved and set using @code{getdomainname()} and @code{setdomainname()} respectively (@pxref{getdomainname}, @pxref{setdomainname}). @subheading Return value On success, zero is returned. On error, -1 is returned, and @samp{errno} is set appropriately. @subheading Errors @table @samp @item EINVAL @var{len} is negative or larger than the maximum allowed size. @item EPERM The caller was not the superuser. @item EFAULT @var{name} is an invalid address. @end table @subheading Portability not POSIX, not Unix98 @samp{lsck/hostname.h} is particular to libsocket. On Linux it is defined in @samp{unistd.h}. @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node setnetent, setprotoent, sethostname, Alphabetical List @unnumberedsec setnetent @c From file ./inet/snetent.txh @findex setnetent @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Actually, this was converted from the setprotoent() man page. @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat Jul 24 19:26:03 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include void setnetent (int stayopen); @end example @subheading Description The @code{setnetent()} function opens and rewinds the @samp{networks} file (@pxref{networks}). If @var{stayopen} is true (@samp{1}), then the file will not be closed between calls to @code{getnetbyname()} or @code{getnetbyaddr()} (@pxref{getnetbyname}, @pxref{getnetbyaddr}). @subheading Return Values None @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node setprotoent, setservent, setnetent, Alphabetical List @unnumberedsec setprotoent @c From file ./inet/sprtent.txh @findex setprotoent @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat Jul 24 19:26:03 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include void setprotoent (int stayopen); @end example @subheading Description The @code{setprotoent()} function opens and rewinds the @samp{protocols} file (@pxref{protocols}). If @var{stayopen} is true (@samp{1}), then the file will not be closed between calls to @code{getprotobyname()} or @code{getprotobynumber()} (@pxref{getprotobyname}, @pxref{getprotobynumber}). @subheading Return Values None @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node setservent, setsockopt, setprotoent, Alphabetical List @unnumberedsec setservent @c From file ./inet/ssrvent.txh @findex setservent @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Actually, this was converted from the setprotoent() man page. @c Copyright 1993 David Metcalfe (david@prism.demon.co.uk) @c @c Permission is granted to make and distribute verbatim copies of this @c manual provided the copyright notice and this permission notice are @c preserved on all copies. @c @c Permission is granted to copy and distribute modified versions of this @c manual under the conditions for verbatim copying, provided that the @c entire resulting derived work is distributed under the terms of a @c permission notice identical to this one @c @c Since the Linux kernel and libraries are constantly changing, this @c manual page may be incorrect or out-of-date. The author(s) assume no @c responsibility for errors or omissions, or for damages resulting from @c the use of the information contained herein. The author(s) may not @c have taken the same level of care in the production of this manual, @c which is licensed free of charge, as they might when working @c professionally. @c @c Formatted or processed versions of this manual, if unaccompanied by @c the source, must acknowledge the copyright and authors of this work. @c @c References consulted: @c Linux libc source code @c Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) @c 386BSD man pages @c Modified Sat Jul 24 19:26:03 1993 by Rik Faith (faith@cs.unc.edu) @subheading Syntax @example #include void setservent (int stayopen); @end example @subheading Description The @code{setservent()} function opens and rewinds the @samp{services} file (@pxref{services}). If @var{stayopen} is true (@samp{1}), then the file will not be closed between calls to @code{getservbyname()} or @code{getservbyport()} (@pxref{getservbyname}, @pxref{getservbyport}). @subheading Return Values None @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node setsockopt, shutdown, setservent, Alphabetical List @unnumberedsec setsockopt @c From file ./ssckopt.txh @findex setsockopt @c This file was originally a Linux man page - see the copyright below. It @c was modified for use in libsocket by Richard Dawe . @c Copyright (c) 1983, 1991 The Regents of the University of California. @c All rights reserved. @c @c Redistribution and use in source and binary forms, with or without @c modification, are permitted provided that the following conditions @c are met: @c 1. Redistributions of source code must retain the above copyright @c notice, this list of conditions and the following disclaimer. @c 2. Redistributions in binary form must reproduce the above copyright @c notice, this list of conditions and the following disclaimer in the @c documentation and/or other materials provided with the distribution. @c 3. All advertising materials mentioning features or use of this software @c must display the following acknowledgement: @c This product includes software developed by the University of @c California, Berkeley and its contributors. @c 4. Neither the name of the University nor the names of its contributors @c may be used to endorse or promote products derived from this software @c without specific prior written permission. @c @c THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND @c ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE @c IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE @c ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE @c FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL @c DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS @c OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) @c HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT @c LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY @c OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF @c SUCH DAMAGE. @c @c @(#)getsockopt.2 6.9 (Berkeley) 5/1/91 @c @c Modified Sat Jul 24 16:19:32 1993 by Rik Faith (faith@cs.unc.edu) @c Modified Mon Apr 22 02:29:06 1996 by Martin Schulze (joey@infodrom.north.de) @c Modified Tue Aug 27 10:52:51 1996 by Andries Brouwer (aeb@cwi.nl) @c Modified Thu Jan 23 13:29:34 1997 by Andries Brouwer (aeb@cwi.nl) @c @subheading Syntax @example #include #include int setsockopt (int s, int level, int optname, const void *optval, int optlen); @end example @subheading Description @code{setsockopt()} manipulates the options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost socket level. When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, @var{level} is specified as @code{SOL_SOCKET}. To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, @var{level} should be set to the protocol number of TCP (@pxref{getprotoent}). The parameters @var{optval} and @var{optlen} are used to access option values for @code{setsockopt()}. @var{optname} and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file @samp{sys/socket.h} contains definitions for socket level options, described below. Options at other protocol levels vary in format and name. Most socket-level options utilize an @samp{int} parameter for @var{optval}. The parameter should be non-zero to enable a boolean option, or zero if the option is to be disabled. @code{SO_LINGER} uses a @code{struct linger} parameter, defined in @samp{sys/socket.h}, which specifies the desired state of the option and the linger interval (see below). @code{SO_SNDTIMEO} and @code{SO_RCVTIMEO} use a @code{struct timeval} parameter, defined in @samp{sys/time.h}. The following options are recognized at the socket level. @table @samp @item SO_DEBUG enables recording of debugging information @item SO_REUSEADDR enables local address reuse @item SO_KEEPALIVE enables keep connections alive @item SO_DONTROUTE enables routing bypass for outgoing messages @item SO_LINGER linger on close if data present @item SO_BROADCAST enables permission to transmit broadcast messages @item SO_OOBINLINE enables reception of out-of-band data in band @item SO_SNDBUF set buffer size for output @item SO_RCVBUF set buffer size for input @item SO_SNDLOWAT set minimum count for output @item SO_RCVLOWAT set minimum count for input @end table @code{SO_DEBUG} enables debugging in the underlying protocol modules. @code{SO_REUSEADDR} indicates that the rules used in validating addresses supplied in @code{bind()} (@pxref{bind}) call should allow reuse of local addresses. @code{SO_KEEPALIVE} enables the periodic transmission of messages on a connected socket. Should the connected party fail to respond to these messages, the connection is considered broken and processes using the socket are notified via a @samp{SIGPIPE} signal when attempting to send data. @code{SO_DONTROUTE} indicates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface according to the network portion of the destination address. @code{SO_LINGER} controls the action taken when unsent messages are queued on socket and a @code{close()} is performed (@pxref{close, , close, libc}). If the socket promises reliable delivery of data and @code{SO_LINGER} is set, the system will block the process on the @code{close()} attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a timeout period, termed the linger interval, is specified in the @code{setsockopt()} call when @code{SO_LINGER} is requested). If @code{SO_LINGER} is disabled and a @code{close()} is issued, the system will process the close in a manner that allows the process to continue as quickly as possible. The @samp{linger} structure is defined in @samp{sys/socket.h} as follows: @example struct linger @{ int l_onoff; /* Linger active */ int l_linger; /* How long to linger for */ @}; @end example @code{l_onoff} indicates whether to linger or not. If it is set to 1 then @code{l_linger} contains the time in hundredths of seconds how long the process should linger to complete the @code{close()}. If @code{l_onoff} is set to zero the process returns immediately. The option @code{SO_BROADCAST} requests permission to send broadcast datagrams on the socket. Broadcast was a privileged operation in earlier versions of the system. With protocols that support out-of-band data, the @code{SO_OOBINLINE} option requests that out-of-band data be placed in the normal data input queue as received; it will then be accessible with @samp{recv} or @samp{read} calls without the @code{MSG_OOB} flag. Some protocols always behave as if this option is set. @code{SO_SNDBUF} and @code{SO_RCVBUF} are options to adjust the normal buffer sizes allocated for output and input buffers, respectively. The buffer size may be increased for high-volume connections, or may be decreased to limit the possible backlog of incoming data. The system places an absolute limit on these values. @code{SO_SNDLOWAT} is an option to set the minimum count for output operations. Most output operations process all of the data supplied by the call, delivering data to the protocol for transmission and blocking as necessary for flow control. Nonblocking output operations will process as much data as permitted subject to flow control without blocking, but will process no data if flow control does not allow the smaller of the low water mark value or the entire request to be processed. A @code{select()} (@pxref{select, , select, libc}) operation testing the ability to write to a socket will return true only if the low water mark amount could be processed. The default value for @code{SO_SNDLOWAT} is set to a convenient size for network efficiency, often 1024. @code{SO_RCVLOWAT} is an option to set the minimum count for input operations. In general, receive calls will block until any (non-zero) amount of data is received, then return with smaller of the amount available or the amount requested. The default value for @code{SO_RCVLOWAT} is 1. If @code{SO_RCVLOWAT} is set to a larger value, blocking receive calls normally wait until they have received the smaller of the low water mark value or the requested amount. Receive calls may still return less than the low water mark if an error occurs, a signal is caught, or the type of data next in the receive queue is different than that returned. @subheading Return value On success, zero is returned. On error, -1 is returned, and @var{errno} is set appropriately. Possible errors from this function are: @table @samp @item EBADF The argument @var{s} is not a valid descriptor. @item ENOTSOCK The argument @var{s} is a file, not a socket. @item ENOPROTOOPT The option is unknown at the @var{level} indicated. @item EFAULT The address pointed to by @var{optval} is not in a valid part of the process address space. @end table @subheading Portability Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node shutdown, sockatmark, setsockopt, Alphabetical List @unnumberedsec shutdown @c From file ./shtdwn.txh @findex shutdown @subheading Syntax @example #include int shutdown (int s, int how); @end example @subheading Description @code{shutdown()} stops communication in one or both directions of a full-duplex connection on socket @var{s}. @var{how} is one of the following: @table @samp @item SHUT_RD Receives will be disabled. @item SHUT_WR Sends will be disabled. @item SHUT_RDWR Receives and sends will be disabled. @end table These correspond to the values 0, 1 and 2 respectively. If sends are disabled for a stream socket (@code{SOCK_STREAM}), any further writes on the socket will return @code{EPIPE} and raise the signal @code{SIGPIPE} (@pxref{sendto}). @subheading Return Value On successful completion the function returns 0. Otherwise, a value of -1 is returned and @var{errno} is set appropriately. @table @samp @item EBADF @var{s} is not a valid file descriptor. @item ENOTSOCK @var{s} is not a socket. @item ENOTCONN The socket @var{s} is not connected. @end table @subheading Portability POSIX, Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node sockatmark, socket, shutdown, Alphabetical List @unnumberedsec sockatmark @c From file ./sockmark.txh @findex sockatmark @subheading Syntax @example #include int sockatmark (int s); @end example @subheading Description The @code{sockatmark()} function determines whether the socket descriptor @var{s} is at the out-of-band data mark. If the libsocket interface supports it, @code{sockatmark()} will return 1 when all data preceding the mark have been read and the out-of-band data mark is the first element in the receive queue. @code{sockatmark()} does not remove the mark from the stream. @subheading Return Values On successful initialization the function returns 1, if the protocol has marked the data stream and all data preceeding the mark have been read. It returns 0, if there is no mark, or if data preceeds the mark in the receive queue. Otherwise, -1 is return and errno is set: @table @samp @item EBADF The parameter is not a valid file descriptor. @item ENOSYS The inteface does not support the @code{sockatmark()} operation. @end table @subheading Portability not ANSI, POSIX @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node socket, socketpair, sockatmark, Alphabetical List @unnumberedsec socket @c From file ./socket.txh @findex socket @subheading Syntax @example #include int socket (int domain, int type, int protocol); @end example @subheading Description @code{socket()} creates a communication end-point and returns its file descriptor. @var{domain} refers to a communication domain, e.g. Internet domain, Unix domain. These are specified by the @code{AF_*} constants, e.g. @code{AF_INET}, @code{AF_UNIX}, as defined in @samp{sys/socket.h}. @var{type} specifies how the communication takes place, e.g. streams, datagrams. These are specified by the @code{SOCK_} constants, e.g. @code{SOCK_STREAM}, @code{SOCK_DGRAM}, as defined in @samp{sys/socket.h}. @code{SOCK_STREAM} supports reliable, sequenced, bidirectional streams of binary data. @code{SOCK_DGRAM} supports unreliable connectionless packets. These packets may have a maximum size. @var{protocol} specifies the communications protocol to use, e.g. TCP, UDP. For the Internet domain (i.e. IP), these are defined by the @code{IPPROTO_*} constants in @code{netinet/in.h}, e.g. @code{IPPROTO_TCP}, @code{IPPROTO_UDP}. If @var{protocol} is zero, the default protocol for the socket's domain & type is used, e.g. to create a TCP/IP socket: @example fd = socket(AF_INET, SOCK_STREAM, 0); @end example or a UDP/IP socket: @example fd = socket(AF_INET, SOCK_DGRAM, 0); @end example libsocket supports the following triplets: @itemize @bullet @item AF_INET, SOCK_STREAM, IPPROTO_TCP @item AF_INET, SOCK_DGRAM, IPPROTO_UDP @item AF_UNIX, SOCK_STREAM, 0 @item AF_UNIX, SOCK_DGRAM, 0 @end itemize @subheading Return Values -1 is returned and @var{errno} set on error. Otherwise, a positive non-zero integer number is returned, a file descriptor. Possible errors are: @table @samp @item EMFILE There is no space left in the per-process file descriptor table. @item ENFILE There is no space left in the system file descriptor table. @item ENODEV No socket transports were found. @item ENOAFSUPPORT The implementation does not support the specified address family. @item EPROTONOSUPPORT The protocol is not supported by the address family or the protocol is not supported by the implementation. @end table @subheading Portability POSIX, Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node socketpair, writev, socket, Alphabetical List @unnumberedsec socketpair @c From file ./sockpr.txh @findex socketpair @subheading Syntax @example #include int socketpair (int domain, int type, int protocol, int sv[2]); @end example @subheading Description @code{socketpair()} creates a pair of unbound connected sockets. The sockets are identical. @var{sv} contains two file descriptors, one for each socket. @var{domain}, @var{type} and @var{protocol} are described in the section on @code{socket()} (@pxref{socket}). Using a @var{protocol} of 0 will give a default protocol. @subheading Return Values 0 is returned on success. Otherwise -1 is returned and the error code is stored in @var{errno}. Possible errors for this function are: @table @samp @item EOPNOTSUPP The specified protocol does not permit creation of socket pairs. @item EAFNOTSUPP The specified address family is not supported. @item ENOPROTOSUPPORT The specified protocol is not supported. @end table @subheading Portability POSIX, Unix98 @subheading Example @example @end example @c ----------------------------------------------------------------------------- @node writev, , socketpair, Alphabetical List @unnumberedsec writev @c From file ./writev.txh @findex writev @subheading Syntax @example #include ssize_t writev (int fd, const struct iovec *iov, int iovcnt); @end example @subheading Description @code{writev()} performs a scatter-gather write to the specified file descriptor @var{fd}. A group of buffers described by the array @var{iov}, with @var{iovcnt} entries, is written to @var{fd} in a similar way to @code{write()} (@pxref{write, , write, libc}). @code{struct iovec} is defined as follows: @example struct iovec @{ void *iov_base; /* Base address of a memory region for I/O */ size_t iov_len; /* Size of memory region */ @}; @end example @subheading Return Value On successful completion the function returns the number of bytes written. Otherwise, a value of -1 is returned and @var{errno} is set appropriately. @table @samp @item EINVAL One of the following conditions is true: @itemize @bullet @item The total length to write would overflow a @code{ssize_t}. @item @var{iovcnt} was negative, zero or larger than @code{IOV_MAX}. @end itemize @end table @subheading Portability POSIX, Unix98 @subheading Example @example @end example