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