lib/libbluetooth/bluetooth.3

   1 .\" $NetBSD: bluetooth.3,v 1.3 2006/07/30 00:15:54 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2003 Maksim Yevmenkin <m_evmenkin@yahoo.com>
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD: src/lib/libbluetooth/bluetooth.3,v 1.7 2005/01/21 10:26:11 ru Exp $
  28 .\"
  29 .Dd August 3, 2009
  30 .Dt BLUETOOTH 3
  31 .Os
  32 .Sh NAME
  33 .Nm bt_gethostbyname ,
  34 .Nm bt_gethostbyaddr ,
  35 .Nm bt_gethostent ,
  36 .Nm bt_sethostent ,
  37 .Nm bt_endhostent ,
  38 .Nm bt_getprotobyname ,
  39 .Nm bt_getprotobynumber ,
  40 .Nm bt_getprotoent ,
  41 .Nm bt_setprotoent ,
  42 .Nm bt_endprotoent ,
  43 .Nm bt_aton ,
  44 .Nm bt_ntoa ,
  45 .Nd Bluetooth host lookup routines
  46 .Sh LIBRARY
  47 .Lb libbluetooth
  48 .Sh SYNOPSIS
  49 .In bluetooth.h
  50 .Ft struct hostent *
  51 .Fn bt_gethostbyname "const char *name"
  52 .Ft struct hostent *
  53 .Fn bt_gethostbyaddr "const char *addr" "int len" "int type"
  54 .Ft struct hostent *
  55 .Fn bt_gethostent void
  56 .Ft void
  57 .Fn bt_sethostent "int stayopen"
  58 .Ft void
  59 .Fn bt_endhostent void
  60 .Ft struct protoent *
  61 .Fn bt_getprotobyname "const char *name"
  62 .Ft struct protoent *
  63 .Fn bt_getprotobynumber "int proto"
  64 .Ft struct protoent *
  65 .Fn bt_getprotoent void
  66 .Ft void
  67 .Fn bt_setprotoent "int stayopen"
  68 .Ft void
  69 .Fn bt_endprotoent void
  70 .Ft int
  71 .Fn bt_aton "const char *str" "bdaddr_t *ba"
  72 .Ft const char *
  73 .Fn bt_ntoa "const bdaddr_t *ba" "char *str"
  74 .Sh DESCRIPTION
  75 The
  76 .Fn bt_gethostent ,
  77 .Fn bt_gethostbyname ,
  78 and
  79 .Fn bt_gethostbyaddr
  80 functions each return a pointer to an object with the
  81 .Vt hostent
  82 structure describing a Bluetooth host
  83 referenced by name or by address, respectively.
  84 .Pp
  85 The
  86 .Fa name
  87 argument passed to
  88 .Fn bt_gethostbyname
  89 should point to a
  90 .Dv NUL Ns -terminated
  91 hostname.
  92 The
  93 .Fa addr
  94 argument passed to
  95 .Fn bt_gethostbyaddr
  96 should point to an address which is
  97 .Fa len
  98 bytes long,
  99 in binary form
 100 (i.e., not a Bluetooth BD_ADDR in human readable
 101 .Tn ASCII
 102 form).
 103 The
 104 .Fa type
 105 argument specifies the address family of this address and must be set to
 106 .Dv AF_BLUETOOTH .
 107 .Pp
 108 The structure returned contains the information obtained from a line in
 109 .Pa /etc/bluetooth/hosts
 110 file.
 111 .Pp
 112 The
 113 .Fn bt_sethostent
 114 function controls whether
 115 .Pa /etc/bluetooth/hosts
 116 file should stay open after each call to
 117 .Fn bt_gethostbyname
 118 or
 119 .Fn bt_gethostbyaddr .
 120 If the
 121 .Fa stayopen
 122 flag is non-zero, the file will not be closed.
 123 .Pp
 124 The
 125 .Fn bt_endhostent
 126 function closes the
 127 .Pa /etc/bluetooth/hosts
 128 file.
 129 .Pp
 130 The
 131 .Fn bt_getprotoent ,
 132 .Fn bt_getprotobyname ,
 133 and
 134 .Fn bt_getprotobynumber
 135 functions each return a pointer to an object with the
 136 .Vt protoent
 137 structure describing a Bluetooth Protocol Service Multiplexor referenced
 138 by name or number, respectively.
 139 .Pp
 140 The
 141 .Fa name
 142 argument passed to
 143 .Fn bt_getprotobyname
 144 should point to a
 145 .Dv NUL Ns -terminated
 146 Bluetooth Protocol Service Multiplexor name.
 147 The
 148 .Fa proto
 149 argument passed to
 150 .Fn bt_getprotobynumber
 151 should have numeric value of the desired Bluetooth Protocol Service
 152 Multiplexor.
 153 .Pp
 154 The structure returned contains the information obtained from a line in
 155 .Pa /etc/bluetooth/protocols
 156 file.
 157 .Pp
 158 The
 159 .Fn bt_setprotoent
 160 function controls whether
 161 .Pa /etc/bluetooth/protocols
 162 file should stay open after each call to
 163 .Fn bt_getprotobyname
 164 or
 165 .Fn bt_getprotobynumber .
 166 If the
 167 .Fa stayopen
 168 flag is non-zero, the file will not be closed.
 169 .Pp
 170 The
 171 .Fn bt_endprotoent
 172 function closes the
 173 .Pa /etc/bluetooth/protocols
 174 file.
 175 .Pp
 176 The
 177 .Fn bt_aton
 178 routine interprets the specified character string as a Bluetooth address,
 179 placing the address into the structure provided.
 180 It returns 1 if the string was successfully interpreted,
 181 or 0 if the string is invalid.
 182 .Pp
 183 The routine
 184 .Fn bt_ntoa
 185 takes a Bluetooth address and places an
 186 .Tn ASCII
 187 string representing the address into the buffer provided.
 188 It is up to the caller to ensure that provided buffer has enough space.
 189 If no buffer was provided then an internal static buffer will be used.
 190 .Sh FILES
 191 .Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact
 192 .It Pa /etc/bluetooth/hosts
 193 .It Pa /etc/bluetooth/protocols
 194 .El
 195 .Sh EXAMPLES
 196 Print out the hostname associated with a specific BD_ADDR:
 197 .Bd -literal -offset indent
 198 const char *bdstr = "00:01:02:03:04:05";
 199 bdaddr_t bd;
 200 struct hostent *hp;
 201
 202 if (!bt_aton(bdstr, \*[Am]bd))
 203         errx(1, "can't parse BD_ADDR %s", bdstr);
 204
 205 if ((hp = bt_gethostbyaddr((const char *)\*[Am]bd,
 206     sizeof(bd), AF_BLUETOOTH)) == NULL)
 207         errx(1, "no name associated with %s", bdstr);
 208
 209 printf("name associated with %s is %s\en", bdstr, hp-\*[Gt]h_name);
 210 .Ed
 211 .Sh DIAGNOSTICS
 212 Error return status from
 213 .Fn bt_gethostent ,
 214 .Fn bt_gethostbyname ,
 215 and
 216 .Fn bt_gethostbyaddr
 217 is indicated by return of a
 218 .Dv NULL
 219 pointer.
 220 The external integer
 221 .Va h_errno
 222 may then be checked to see whether this is a temporary failure
 223 or an invalid or unknown host.
 224 The routine
 225 .Xr herror 3
 226 can be used to print an error message describing the failure.
 227 If its argument
 228 .Fa string
 229 is
 230 .Pf non- Dv NULL ,
 231 it is printed, followed by a colon and a space.
 232 The error message is printed with a trailing newline.
 233 .Pp
 234 The variable
 235 .Va h_errno
 236 can have the following values:
 237 .Bl -tag -width ".Dv HOST_NOT_FOUND"
 238 .It Dv HOST_NOT_FOUND
 239 No such host is known.
 240 .It Dv NO_RECOVERY
 241 Some unexpected server failure was encountered.
 242 This is a non-recoverable error.
 243 .El
 244 .Pp
 245 The
 246 .Fn bt_getprotoent ,
 247 .Fn bt_getprotobyname ,
 248 and
 249 .Fn bt_getprotobynumber
 250 return
 251 .Dv NULL
 252 on EOF or error.
 253 .Sh SEE ALSO
 254 .Xr gethostbyaddr 3 ,
 255 .Xr gethostbyname 3 ,
 256 .Xr getprotobyname 3 ,
 257 .Xr getprotobynumber 3 ,
 258 .Xr herror 3 ,
 259 .Xr inet_aton 3 ,
 260 .Xr inet_ntoa 3
 261 .Sh HISTORY
 262 .Nm libbluetooth
 263 first appeared in
 264 .Fx
 265 was ported to
 266 .Nx 4.0
 267 and extended by
 268 .An Iain Hibbert
 269 for Itronix, Inc.
 270 .Sh AUTHORS
 271 .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
 272 .An Iain Hibbert
 273 .Sh CAVEATS
 274 The
 275 .Fn bt_gethostent
 276 function reads the next line of
 277 .Pa /etc/bluetooth/hosts ,
 278 opening the file if necessary.
 279 .Pp
 280 The
 281 .Fn bt_sethostent
 282 function opens and/or rewinds the
 283 .Pa /etc/bluetooth/hosts
 284 file.
 285 .Pp
 286 The
 287 .Fn bt_getprotoent
 288 function reads the next line of
 289 .Pa /etc/bluetooth/protocols ,
 290 opening the file if necessary.
 291 .Pp
 292 The
 293 .Fn bt_setprotoent
 294 function opens and/or rewinds the
 295 .Pa /etc/bluetooth/protocols
 296 file.
 297 .Sh BUGS
 298 These functions use static data storage;
 299 if the data is needed for future use, it should be
 300 copied before any subsequent calls overwrite it.