1 '\" te
   2 .\" Copyright 2015 Nexenta Systems, Inc.  All rights reserved.
   3 .\"  Copyright 1989 AT&T
   4 .\" Copyright (C) 2005, Sun Microsystems, Inc. All Rights Reserved
   5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   7 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   8 .TH NETDIR 3NSL "Feb 14, 2015"
   9 .SH NAME
  10 netdir, netdir_getbyname, netdir_getbyaddr, netdir_free, netdir_options,
  11 taddr2uaddr, uaddr2taddr, netdir_perror, netdir_sperror, netdir_mergeaddr \-
  12 generic transport name-to-address translation
  13 .SH SYNOPSIS
  14 .nf
  15 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lnsl\fR [ \fIlibrary\fR...]
  16 #include <netdir.h>
  17 
  18 \fBint\fR \fBnetdir_getbyname\fR(\fBstruct netconfig  *\fR\fIconfig\fR,
  19      \fBstruct nd_hostserv *\fR\fIservice\fR, \fBstruct nd_addrlist **\fR\fIaddrs\fR);
  20 .fi
  21 
  22 .LP
  23 .nf
  24 \fBint\fR \fBnetdir_getbyaddr\fR(\fBstruct netconfig  *\fR\fIconfig\fR,
  25      \fBstruct nd_hostservlist **\fR\fIservice\fR, \fBstruct netbuf  *\fR\fInetaddr\fR);
  26 .fi
  27 
  28 .LP
  29 .nf
  30 \fBvoid\fR \fBnetdir_free\fR(\fBvoid *\fR\fIptr\fR, \fBint\fR \fIstruct_type\fR);
  31 .fi
  32 
  33 .LP
  34 .nf
  35 \fBint\fR \fBnetdir_options\fR(\fBstruct netconfig  *\fR\fIconfig\fR, \fBint\fR \fIoption\fR, \fBint\fR \fIfildes\fR,
  36      \fBchar *\fR\fIpointer_to_args\fR);
  37 .fi
  38 
  39 .LP
  40 .nf
  41 \fBchar *\fR\fBtaddr2uaddr\fR(\fBstruct netconfig *\fR\fIconfig\fR, \fBstruct netbuf *\fR\fIaddr\fR);
  42 .fi
  43 
  44 .LP
  45 .nf
  46 \fBstruct netbuf *\fR\fBuaddr2taddr\fR(\fBstruct netconfig *\fR\fIconfig\fR, \fBchar *\fR\fIuaddr\fR);
  47 .fi
  48 
  49 .LP
  50 .nf
  51 \fBvoid\fR \fBnetdir_perror\fR(\fBchar *\fR\fIs\fR);
  52 .fi
  53 
  54 .LP
  55 .nf
  56 \fBchar *\fR\fBnetdir_sperror\fR(\fBvoid\fR);
  57 .fi
  58 
  59 .SH DESCRIPTION
  60 The \fBnetdir\fR functions provide a generic interface for name-to-address
  61 mapping that will work with all transport protocols. This interface provides a
  62 generic way for programs to convert transport specific addresses into common
  63 structures and back again. The \fBnetconfig\fR structure, described on the
  64 \fBnetconfig\fR(4) manual page, identifies the transport.
  65 .sp
  66 .LP
  67 The \fBnetdir_getbyname()\fR function maps the machine name and service name in
  68 the \fBnd_hostserv\fR structure to a collection of addresses of the type
  69 understood by the transport identified in the \fBnetconfig\fR structure. This
  70 function returns all addresses that are valid for that transport in the
  71 \fBnd_addrlist\fR structure. The \fBnd_hostserv\fR structure contains the
  72 following members:
  73 .sp
  74 .in +2
  75 .nf
  76 char *h_host;      /* host name */
  77 char *h_serv;      /* service name */
  78 .fi
  79 .in -2
  80 
  81 .sp
  82 .LP
  83 The \fBnd_addrlist\fR structure contains the following members:
  84 .sp
  85 .in +2
  86 .nf
  87 int  n_cnt;       /* number of addresses */
  88 struct netbuf *n_addrs;
  89 .fi
  90 .in -2
  91 
  92 .sp
  93 .LP
  94 The \fBnetdir_getbyname()\fR function accepts some special-case host names. The
  95 host names are defined in <\fBnetdir.h\fR>. The currently defined host names
  96 are:
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fBHOST_SELF\fR\fR
 101 .ad
 102 .RS 21n
 103 Represents the address to which local programs will bind their endpoints.
 104 \fBHOST_SELF\fR differs from the host name provided by \fBgethostname\fR(3C),
 105 which represents the address to which \fIremote\fR programs will bind their
 106 endpoints.
 107 .RE
 108 
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fBHOST_ANY\fR\fR
 113 .ad
 114 .RS 21n
 115 Represents any host accessible by this transport provider. \fBHOST_ANY\fR
 116 allows applications to specify a required service without specifying a
 117 particular host name.
 118 .RE
 119 
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fBHOST_SELF_CONNECT\fR\fR
 124 .ad
 125 .RS 21n
 126 Represents the host address that can be used to connect to the local host.
 127 .RE
 128 
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fBHOST_BROADCAST\fR\fR
 133 .ad
 134 .RS 21n
 135 Represents the address for all hosts accessible by this transport provider.
 136 Network requests to this address are received by all machines.
 137 .RE
 138 
 139 .sp
 140 .LP
 141 All fields of the \fBnd_hostserv\fR structure must be initialized.
 142 .sp
 143 .LP
 144 To find the address of a given host and service on all available transports,
 145 call the \fBnetdir_getbyname()\fR function with each \fBstruct netconfig\fR
 146 structure returned by \fBgetnetconfig\fR(3NSL).
 147 .sp
 148 .LP
 149 The \fBnetdir_getbyaddr()\fR function maps addresses to service names. The
 150 function returns \fIservice\fR, a list of host and service pairs that yield
 151 these addresses. If more than one tuple of host and service name is returned,
 152 the first tuple contains the preferred host and service names:
 153 .sp
 154 .in +2
 155 .nf
 156 struct nd_hostservlist {
 157    int  *h_cnt;                  /* number of hostservs found */
 158    struct hostserv *h_hostservs;
 159 }
 160 .fi
 161 .in -2
 162 
 163 .sp
 164 .LP
 165 The \fBnetdir_free()\fR structure is used to free the structures allocated by
 166 the name to address translation functions. The \fIptr\fR parameter points to
 167 the structure that has to be freed. The parameter \fBstruct_type\fR identifies
 168 the structure:
 169 .sp
 170 .in +2
 171 .nf
 172 struct netbuf            ND_ADDR
 173 struct nd_addrlist       ND_ADDRLIST
 174 struct hostserv          ND_HOSTSERV
 175 struct nd_hostservlist   ND_HOSTSERVLIST
 176 .fi
 177 .in -2
 178 
 179 .sp
 180 .LP
 181 The \fBnetdir_options()\fR function is used to do all transport-specific setups
 182 and option management. \fIfildes\fR is the associated file descriptor.
 183 \fIoption\fR, \fIfildes\fR, and \fIpointer_to_args\fR are passed to the
 184 \fBnetdir_options()\fR function for the transport specified in \fIconfig\fR.
 185 Currently four values are defined for \fIoption\fR:
 186 
 187 .in +2
 188 \fBND_SET_BROADCAST\fR
 189 .in -2
 190 .br
 191 .in +2
 192 \fBND_SET_RESERVEDPORT\fR
 193 .in -2
 194 .br
 195 .in +2
 196 \fBND_CHECK_RESERVEDPORT\fR
 197 .in -2
 198 .br
 199 .in +2
 200 \fBND_MERGEADDR\fR
 201 .sp
 202 .LP
 203 The specific actions of each option follow.
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fBND_SET_BROADCAST\fR\fR
 208 .ad
 209 .RS 25n
 210 Sets the transport provider up to allow broadcast if the transport supports
 211 broadcast. \fIfildes\fR is a file descriptor into the transport, that is, the
 212 result of a \fBt_open\fR of \fB/dev/udp\fR. \fIpointer_to_args\fR is not used.
 213 If this completes, broadcast operations can be performed on file descriptor
 214 \fIfildes\fR.
 215 .RE
 216 
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fBND_SET_RESERVEDPORT\fR\fR
 221 .ad
 222 .RS 25n
 223 Allows the application to bind to a reserved port if that concept exists for
 224 the transport provider. \fIfildes\fR is an unbound file descriptor into the
 225 transport. If \fIpointer_to_args\fR is \fINULL,\fR \fIfildes\fR is bound to a
 226 reserved port. If \fIpointer_to_args\fR is a pointer to a \fBnetbuf\fR
 227 structure, an attempt is made to bind to any reserved port on the specified
 228 address.
 229 .RE
 230 
 231 .sp
 232 .ne 2
 233 .na
 234 \fB\fBND_CHECK_RESERVEDPORT\fR\fR
 235 .ad
 236 .RS 25n
 237 Used to verify that the address corresponds to a reserved port if that concept
 238 exists for the transport provider. \fIfildes\fR is not used.
 239 \fIpointer_to_args\fR is a pointer to a \fBnetbuf\fR structure that contains
 240 the address. This option returns \fB0\fR only if the address specified in
 241 \fIpointer_to_args\fR is reserved.
 242 .RE
 243 
 244 .sp
 245 .ne 2
 246 .na
 247 \fB\fBND_MERGEADDR\fR\fR
 248 .ad
 249 .RS 25n
 250 Used to take a ``local address'' such as a \fB0.0.0.0\fR TCP address and return
 251 a ``real address'' to which client machines can connect. \fIfildes\fR is not
 252 used. \fIpointer_to_args\fR is a pointer to a \fBstruct nd_mergearg\fR which
 253 has the following members:
 254 .sp
 255 .in +2
 256 .nf
 257 \fBchar\fR \fIs_uaddr;\fR  /* server's universal address */
 258 \fBchar\fR \fIc_uaddr;\fR  /* client's universal address */
 259 \fBchar\fR \fIm_uaddr;\fR  /* the result */
 260 .fi
 261 .in -2
 262 
 263 If \fBs_uaddr\fR is an address such as \fB0.0.0.0.1.12\fR, and the call is
 264 successful \fBm_uaddr\fR is set to an address such as \fB192.11.109.89.1.12\fR.
 265 For most transports, \fBm_uaddr\fR is identical to \fBs_uaddr\fR.
 266 .RE
 267 .sp
 268 .LP
 269 If a transport provider does not support an option, \fBnetdir_options\fR
 270 returns \fB-1\fR and the error message can be printed through
 271 \fBnetdir_perror()\fR or \fBnetdir_sperror()\fR.
 272 
 273 .in -2
 274 .sp
 275 .LP
 276 The \fBtaddr2uaddr()\fR and \fBuaddr2taddr()\fR functions support translation
 277 between universal addresses and \fBTLI\fR type \fBnetbufs\fR. The
 278 \fBtaddr2uaddr()\fR function takes a \fBstruct\fR \fBnetbuf\fR data structure
 279 and returns a pointer to a string that contains the universal address. It
 280 returns \fINULL\fR if the conversion is not possible. This is not a fatal
 281 condition as some transports do not support a universal address form.
 282 .sp
 283 .LP
 284 The \fBfree()\fR function is used to free the universal address returned by the
 285 \fBtaddr2uaddr()\fR function.
 286 .sp
 287 .LP
 288 The \fBuaddr2taddr()\fR function is the reverse of the \fBtaddr2uaddr()\fR
 289 function. It returns the \fBstruct netbuf\fR data structure for the given
 290 universal address and \fINULL\fR on failure.
 291 
 292 .sp
 293 .LP
 294 The \fBnetdir_perror()\fR function prints an error message in standard output
 295 that states the cause of a name-to-address mapping failure. The error message
 296 is preceded by the string given as an argument.
 297 .sp
 298 .LP
 299 The \fBnetdir_sperror()\fR function returns a string with an error message that
 300 states the cause of a name-to-address mapping failure.
 301 
 302 .SH RETURN VALUES
 303 The \fBnetdir_sperror()\fR function returns a pointer to a buffer which
 304 contains the error message string. The buffer is overwritten on each call. In
 305 multithreaded applications, this buffer is implemented as thread-specific
 306 data.
 307 .sp
 308 .LP
 309 The \fBnetdir_getbyname()\fR, \fBnetdir_getbyaddr()\fR, and \fBnetdir_options()\fR
 310 functions return \fB0\fR on success and a non-zero value on failure.
 311 .SH ATTRIBUTES
 312 See \fBattributes\fR(5) for descriptions of the following attributes:
 313 .sp
 314 
 315 .sp
 316 .TS
 317 box;
 318 c | c
 319 l | l .
 320 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 321 _
 322 MT-Level        Safe
 323 .TE
 324 
 325 .SH SEE ALSO
 326 \fBgethostname\fR(3C), \fBgetnetconfig\fR(3NSL), \fBgetnetpath\fR(3NSL),
 327 \fBnetconfig\fR(4), \fBattributes\fR(5)