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 May 7, 2003
  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 .Nd get Bluetooth host entry
  38 .Pp
  39 .Nm bt_getprotobyname ,
  40 .Nm bt_getprotobynumber ,
  41 .Nm bt_getprotoent ,
  42 .Nm bt_setprotoent ,
  43 .Nm bt_endprotoent
  44 .Nd get Bluetooth Protocol Service Multiplexor entry
  45 .Pp
  46 .Nm bt_aton ,
  47 .Nm bt_ntoa
  48 .Nd Bluetooth address manipulation routines
  49 .Sh LIBRARY
  50 .Lb libbluetooth
  51 .Sh SYNOPSIS
  52 .In bluetooth.h
  53 .Ft struct hostent *
  54 .Fn bt_gethostbyname "const char *name"
  55 .Ft struct hostent *
  56 .Fn bt_gethostbyaddr "const char *addr" "int len" "int type"
  57 .Ft struct hostent *
  58 .Fn bt_gethostent void
  59 .Ft void
  60 .Fn bt_sethostent "int stayopen"
  61 .Ft void
  62 .Fn bt_endhostent void
  63 .Ft struct protoent *
  64 .Fn bt_getprotobyname "const char *name"
  65 .Ft struct protoent *
  66 .Fn bt_getprotobynumber "int proto"
  67 .Ft struct protoent *
  68 .Fn bt_getprotoent void
  69 .Ft void
  70 .Fn bt_setprotoent "int stayopen"
  71 .Ft void
  72 .Fn bt_endprotoent void
  73 .Ft int
  74 .Fn bt_aton "const char *str" "bdaddr_t *ba"
  75 .Ft const char *
  76 .Fn bt_ntoa "const bdaddr_t *ba" "char *str"
  77 .Sh DESCRIPTION
  78 The
  79 .Fn bt_gethostent ,
  80 .Fn bt_gethostbyname
  81 and
  82 .Fn bt_gethostbyaddr
  83 functions
  84 each return a pointer to an object with the
  85 .Vt hostent
  86 structure describing a Bluetooth host
  87 referenced by name or by address, respectively.
  88 .Pp
  89 The
  90 .Fa name
  91 argument passed to
  92 .Fn bt_gethostbyname
  93 should point to a
  94 .Dv NUL Ns -terminated
  95 hostname.
  96 The
  97 .Fa addr
  98 argument passed to
  99 .Fn bt_gethostbyaddr
 100 should point to an address which is
 101 .Fa len
 102 bytes long,
 103 in binary form
 104 (i.e. not an Bluetooth BD_ADDR in human readable
 105 .Tn ASCII
 106 form).
 107 The
 108 .Fa type
 109 argument specifies the address family of this address and must be set to
 110 .Dv AF_BLUETOOTH .
 111 .Pp
 112 The structure returned contains the information obtained from a line in
 113 .Pa /etc/bluetooth/hosts
 114 file.
 115 .Pp
 116 The
 117 .Fn bt_sethostent
 118 function controls whether
 119 .Pa /etc/bluetooth/hosts
 120 file should stay open after each call to
 121 .Fn bt_gethostbyname
 122 or
 123 .Fn bt_gethostbyaddr .
 124 If the
 125 .Fa stayopen
 126 flag is non-zero, the file will not be closed.
 127 .Pp
 128 The
 129 .Fn bt_endhostent
 130 function closes the
 131 .Pa /etc/bluetooth/hosts
 132 file.
 133 .Pp
 134 The
 135 .Fn bt_getprotoent ,
 136 .Fn bt_getprotobyname
 137 and
 138 .Fn bt_getprotobynumber
 139 functions each return a pointer to an object with the
 140 .Vt protoent
 141 structure describing a Bluetooth Protocol Service Multiplexor referenced
 142 by name or number, respectively.
 143 .Pp
 144 The
 145 .Fa name
 146 argument passed to
 147 .Fn bt_getprotobyname
 148 should point to a
 149 .Dv NUL Ns -terminated
 150 Bluetooth Protocol Service Multiplexor name.
 151 The
 152 .Fa proto
 153 argument passed to
 154 .Fn bt_getprotobynumber
 155 should have numeric value of the desired Bluetooth Protocol Service Multiplexor.
 156 .Pp
 157 The structure returned contains the information obtained from a line in
 158 .Pa /etc/bluetooth/protocols
 159 file.
 160 .Pp
 161 The
 162 .Fn bt_setprotoent
 163 function controls whether
 164 .Pa /etc/bluetooth/protocols
 165 file should stay open after each call to
 166 .Fn bt_getprotobyname
 167 or
 168 .Fn bt_getprotobynumber .
 169 If the
 170 .Fa stayopen
 171 flag is non-zero, the file will not be closed.
 172 .Pp
 173 The
 174 .Fn bt_endprotoent
 175 function closes the
 176 .Pa /etc/bluetooth/protocols
 177 file.
 178 .Pp
 179 The
 180 .Fn bt_aton
 181 routine interprets the specified character string as a Bluetooth address,
 182 placing the address into the structure provided.
 183 It returns 1 if the string was successfully interpreted,
 184 or 0 if the string is invalid.
 185 .Pp
 186 The routine
 187 .Fn bt_ntoa
 188 takes a Bluetooth address and places an
 189 .Tn ASCII
 190 string representing the address into the buffer provided.
 191 It is up to the caller to ensure that provided buffer has enough space.
 192 If no buffer was provided then internal static buffer will be used.
 193 .Sh FILES
 194 .Bl -tag -width /etc/bluetooth/hosts -compact
 195 .It Pa /etc/bluetooth/hosts
 196 .It Pa /etc/bluetooth/protocols
 197 .El
 198 .Sh EXAMPLES
 199 Print out the hostname associated with a specific BD_ADDR:
 200 .Bd -literal -offset indent
 201 const char *bdstr = "00:01:02:03:04:05";
 202 bdaddr_t bd;
 203 struct hostent *hp;
 204
 205 if (!bt_aton(bdstr, &bd))
 206         errx(1, "can't parse BD_ADDR %s", bdstr);
 207
 208 if ((hp = bt_gethostbyaddr((const char *)&bd,
 209     sizeof(bd), AF_BLUETOOTH)) == NULL)
 210         errx(1, "no name associated with %s", bdstr);
 211
 212 printf("name associated with %s is %s\en", bdstr, hp->h_name);
 213 .Ed
 214 .Sh DIAGNOSTICS
 215 Error return status from
 216 .Fn bt_gethostent ,
 217 .Fn bt_gethostbyname
 218 and
 219 .Fn bt_gethostbyaddr
 220 is indicated by return of a
 221 .Dv NULL
 222 pointer.
 223 The external integer
 224 .Va h_errno
 225 may then be checked to see whether this is a temporary failure
 226 or an invalid or unknown host.
 227 The routine
 228 .Fn herror
 229 can be used to print an error message describing the failure.
 230 If its argument
 231 .Fa string
 232 is
 233 .Pf non- Dv NULL ,
 234 it is printed, followed by a colon and a space.
 235 The error message is printed with a trailing newline.
 236 .Pp
 237 The variable
 238 .Va h_errno
 239 can have the following values:
 240 .Bl -tag -width HOST_NOT_FOUND
 241 .It Dv HOST_NOT_FOUND
 242 No such host is known.
 243 .It Dv NO_RECOVERY
 244 Some unexpected server failure was encountered.
 245 This is a non-recoverable error.
 246 .El
 247 .Pp
 248 The
 249 .Fn bt_getprotoent ,
 250 .Fn bt_getprotobyname
 251 and
 252 .Fn bt_getprotobynumber
 253 return Null pointer (0) on
 254 .Dv EOF
 255 or error.
 256 .Sh SEE ALSO
 257 .Xr gethostbyaddr 3 ,
 258 .Xr gethostbyname 3 ,
 259 .Xr getprotobyaddr 3 ,
 260 .Xr getprotobynumber 3 ,
 261 .Xr herror 3 ,
 262 .Xr inet_aton 3 ,
 263 .Xr inet_ntoa 3
 264 .Sh CAVEAT
 265 The
 266 .Fn bt_gethostent
 267 function reads the next line of
 268 .Pa /etc/bluetooth/hosts ,
 269 opening the file if necessary.
 270 .Pp
 271 The
 272 .Fn bt_sethostent
 273 function opens and/or rewinds the
 274 .Pa /etc/bluetooth/hosts
 275 file.
 276 .Pp
 277 The
 278 .Fn bt_getprotoent
 279 function reads the next line of
 280 .Pa /etc/bluetooth/protocols ,
 281 opening the file if necessary.
 282 .Pp
 283 The
 284 .Fn bt_setprotoent
 285 function opens and/or rewinds the
 286 .Pa /etc/bluetooth/protocols
 287 file.
 288 .Sh BUGS
 289 These functions use static data storage;
 290 if the data is needed for future use, it should be
 291 copied before any subsequent calls overwrite it.
 292 .Sh AUTHORS
 293 .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com