usr/src/man/man3xnet/endhostent.3xnet

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright (c) 1997, The Open Group. All Rights Reserved.
  44 .\" Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
  45 .\"
  46 .TH ENDHOSTENT 3XNET "Nov 1, 2003"
  47 .SH NAME
  48 endhostent, gethostbyaddr, gethostbyname, gethostent, sethostent \- network
  49 host database functions
  50 .SH SYNOPSIS
  51 .LP
  52 .nf
  53 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ]
  54 #include <netdb.h>
  55 extern int h_errno;
  56
  57 \fBvoid\fR \fBendhostent\fR(void)
  58 .fi
  59
  60 .LP
  61 .nf
  62 \fBstruct hostent *\fR\fBgethostbyaddr\fR(\fBconst void *\fR\fIaddr\fR, \fBsocklen_t\fR \fIlen\fR, \fBint\fR \fItype\fR);
  63 .fi
  64
  65 .LP
  66 .nf
  67 \fBstruct hostent *\fR\fBgethostbyname\fR(\fBconst char *\fR\fIname\fR);
  68 .fi
  69
  70 .LP
  71 .nf
  72 \fBstruct hostent *\fR\fBgethostent\fR(void)
  73 .fi
  74
  75 .LP
  76 .nf
  77 \fBvoid\fR \fBsethostent\fR(\fBint\fR \fIstayopen\fR);
  78 .fi
  79
  80 .SH DESCRIPTION
  81 .sp
  82 .LP
  83 The \fBgethostent()\fR, \fBgethostbyaddr()\fR, and \fBgethostbyname()\fR
  84 functions each return a pointer to a \fBhostent\fR structure, the members of
  85 which contain the fields of an entry in the network host database.
  86 .sp
  87 .LP
  88 The \fBgethostent()\fR function reads the next entry of the database, opening a
  89 connection to the database if necessary.
  90 .sp
  91 .LP
  92 The \fBgethostbyaddr()\fR function searches the database and finds an entry
  93 which matches the address family specified by the \fBtype\fR argument and which
  94 matches the address pointed to by the \fIaddr\fR argument,  opening a
  95 connection to the database if necessary.  The \fIaddr\fR argument is a pointer
  96 to the binary-format (that is, not null-terminated) address in network byte
  97 order, whose length is specified by the \fIlen\fR argument.  The datatype of
  98 the address depends on the address family.  For an address of type
  99 \fBAF_INET\fR, this is an \fBin_addr\fR structure, defined in
 100 <\fBnetinet/in.h\fR>. For an address of type \fBAF_INET6\fR, there is an
 101 \fBin6_addr\fR structure defined in <\fBnetinet/in.h\fR>.
 102 .sp
 103 .LP
 104 The \fBgethostbyname()\fR function searches the database and finds an entry
 105 which matches the host name specified by the \fIname\fR argument, opening a
 106 connection to the database if necessary. If  \fIname\fR is an alias for a valid
 107 host name, the function returns information about the host name  to which the
 108 alias refers, and  \fIname\fR is included in the list of aliases returned.
 109 .sp
 110 .LP
 111 The \fBsethostent()\fR function opens a connection to the network host
 112 database, and sets the position of the next entry to the first entry.  If the
 113 \fIstayopen\fR argument is non-zero, the connection to the host database will
 114 not be closed after each call to \fBgethostent()\fR (either directly, or
 115 indirectly through one of the other \fBgethost*(\|)\fR functions).
 116 .sp
 117 .LP
 118 The \fBendhostent()\fR function closes the connection to the database.
 119 .SH USAGE
 120 .sp
 121 .LP
 122 The \fBgethostent()\fR, \fBgethostbyaddr()\fR, and \fBgethostbyname()\fR
 123 functions may return pointers to static data, which may be overwritten by
 124 subsequent calls to any of these functions.
 125 .sp
 126 .LP
 127 These functions are generally used with the Internet address family.
 128 .SH RETURN VALUES
 129 .sp
 130 .LP
 131 On successful completion, \fBgethostbyaddr()\fR, \fBgethostbyname()\fR and
 132 \fBgethostent()\fR return a pointer to a \fBhostent\fR structure if the
 133 requested entry was found, and a null pointer if the end of the database was
 134 reached or the requested entry was not found.  Otherwise, a null pointer is
 135 returned.
 136 .sp
 137 .LP
 138 On unsuccessful completion, \fBgethostbyaddr()\fR and \fBgethostbyname()\fR
 139 functions set \fIh_errno\fR to indicate the error.
 140 .SH ERRORS
 141 .sp
 142 .LP
 143 No errors are defined for \fBendhostent()\fR, \fBgethostent()\fR and
 144 \fBsethostent()\fR.
 145 .sp
 146 .LP
 147 The \fBgethostbyaddr()\fR and \fBgethostbyname()\fR functions will fail in the
 148 following cases, setting \fIh_errno\fR to the value shown in the list below.
 149 Any changes to \fBerrno\fR are unspecified.
 150 .sp
 151 .ne 2
 152 .na
 153 \fB\fBHOST_NOT_FOUND\fR\fR
 154 .ad
 155 .RS 18n
 156 No such host is known.
 157 .RE
 158
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fBNO_DATA\fR\fR
 163 .ad
 164 .RS 18n
 165 The server recognised the request and the name but no address is available.
 166 Another type of request to the name server for the domain might return an
 167 answer.
 168 .RE
 169
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fBNO_RECOVERY\fR\fR
 174 .ad
 175 .RS 18n
 176 An unexpected server failure occurred which can not be recovered.
 177 .RE
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBTRY_AGAIN\fR\fR
 183 .ad
 184 .RS 18n
 185 A temporary and possibly transient error occurred, such as a failure of a
 186 server to respond.
 187 .RE
 188
 189 .SH ATTRIBUTES
 190 .sp
 191 .LP
 192 See \fBattributes\fR(5) for descriptions of the following attributes:
 193 .sp
 194
 195 .sp
 196 .TS
 197 box;
 198 c | c
 199 l | l .
 200 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 201 _
 202 Interface Stability     Standard
 203 _
 204 MT-Level        MT-Safe
 205 .TE
 206
 207 .SH SEE ALSO
 208 .sp
 209 .LP
 210 \fBendservent\fR(3XNET), \fBhtonl\fR(3XNET), \fBinet_addr\fR(3XNET),
 211 \fBattributes\fR(5), \fBstandards\fR(5)