lib/libbluetooth/bluetooth.3

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