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 .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 .Nd Bluetooth routines
  45 .Sh LIBRARY
  46 .Lb libbluetooth
  47 .Sh SYNOPSIS
  48 .In bluetooth.h
  49 .Ft struct hostent *
  50 .Fn bt_gethostbyname "const char *name"
  51 .Ft struct hostent *
  52 .Fn bt_gethostbyaddr "const char *addr" "int len" "int type"
  53 .Ft struct hostent *
  54 .Fn bt_gethostent void
  55 .Ft void
  56 .Fn bt_sethostent "int stayopen"
  57 .Ft void
  58 .Fn bt_endhostent void
  59 .Ft struct protoent *
  60 .Fn bt_getprotobyname "const char *name"
  61 .Ft struct protoent *
  62 .Fn bt_getprotobynumber "int proto"
  63 .Ft struct protoent *
  64 .Fn bt_getprotoent void
  65 .Ft void
  66 .Fn bt_setprotoent "int stayopen"
  67 .Ft void
  68 .Fn bt_endprotoent void
  69 .Ft int
  70 .Fn bt_aton "const char *str" "bdaddr_t *ba"
  71 .Ft const char *
  72 .Fn bt_ntoa "const bdaddr_t *ba" "char *str"
  73 .Sh DESCRIPTION
  74 The
  75 .Fn bt_gethostent ,
  76 .Fn bt_gethostbyname
  77 and
  78 .Fn bt_gethostbyaddr
  79 functions
  80 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 Multiplexor.
 152 .Pp
 153 The structure returned contains the information obtained from a line in
 154 .Pa /etc/bluetooth/protocols
 155 file.
 156 .Pp
 157 The
 158 .Fn bt_setprotoent
 159 function controls whether
 160 .Pa /etc/bluetooth/protocols
 161 file should stay open after each call to
 162 .Fn bt_getprotobyname
 163 or
 164 .Fn bt_getprotobynumber .
 165 If the
 166 .Fa stayopen
 167 flag is non-zero, the file will not be closed.
 168 .Pp
 169 The
 170 .Fn bt_endprotoent
 171 function closes the
 172 .Pa /etc/bluetooth/protocols
 173 file.
 174 .Pp
 175 The
 176 .Fn bt_aton
 177 routine interprets the specified character string as a Bluetooth address,
 178 placing the address into the structure provided.
 179 It returns 1 if the string was successfully interpreted,
 180 or 0 if the string is invalid.
 181 .Pp
 182 The routine
 183 .Fn bt_ntoa
 184 takes a Bluetooth address and places an
 185 .Tn ASCII
 186 string representing the address into the buffer provided.
 187 It is up to the caller to ensure that provided buffer has enough space.
 188 If no buffer was provided then internal static buffer will be used.
 189 .Sh FILES
 190 .Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact
 191 .It Pa /etc/bluetooth/hosts
 192 .It Pa /etc/bluetooth/protocols
 193 .El
 194 .Sh EXAMPLES
 195 Print out the hostname associated with a specific BD_ADDR:
 196 .Bd -literal -offset indent
 197 const char *bdstr = "00:01:02:03:04:05";
 198 bdaddr_t bd;
 199 struct hostent *hp;
 200
 201 if (!bt_aton(bdstr, &bd))
 202         errx(1, "can't parse BD_ADDR %s", bdstr);
 203
 204 if ((hp = bt_gethostbyaddr((const char *)&bd,
 205     sizeof(bd), AF_BLUETOOTH)) == NULL)
 206         errx(1, "no name associated with %s", bdstr);
 207
 208 printf("name associated with %s is %s\en", bdstr, hp->h_name);
 209 .Ed
 210 .Sh DIAGNOSTICS
 211 Error return status from
 212 .Fn bt_gethostent ,
 213 .Fn bt_gethostbyname
 214 and
 215 .Fn bt_gethostbyaddr
 216 is indicated by return of a
 217 .Dv NULL
 218 pointer.
 219 The external integer
 220 .Va h_errno
 221 may then be checked to see whether this is a temporary failure
 222 or an invalid or unknown host.
 223 The routine
 224 .Xr herror 3
 225 can be used to print an error message describing the failure.
 226 If its argument
 227 .Fa string
 228 is
 229 .Pf non- Dv NULL ,
 230 it is printed, followed by a colon and a space.
 231 The error message is printed with a trailing newline.
 232 .Pp
 233 The variable
 234 .Va h_errno
 235 can have the following values:
 236 .Bl -tag -width ".Dv HOST_NOT_FOUND"
 237 .It Dv HOST_NOT_FOUND
 238 No such host is known.
 239 .It Dv NO_RECOVERY
 240 Some unexpected server failure was encountered.
 241 This is a non-recoverable error.
 242 .El
 243 .Pp
 244 The
 245 .Fn bt_getprotoent ,
 246 .Fn bt_getprotobyname
 247 and
 248 .Fn bt_getprotobynumber
 249 return
 250 .Dv NULL
 251 on EOF or error.
 252 .Sh SEE ALSO
 253 .Xr gethostbyaddr 3 ,
 254 .Xr gethostbyname 3 ,
 255 .Xr getprotobyname 3 ,
 256 .Xr getprotobynumber 3 ,
 257 .Xr herror 3 ,
 258 .Xr inet_aton 3 ,
 259 .Xr inet_ntoa 3
 260 .Sh CAVEAT
 261 The
 262 .Fn bt_gethostent
 263 function reads the next line of
 264 .Pa /etc/bluetooth/hosts ,
 265 opening the file if necessary.
 266 .Pp
 267 The
 268 .Fn bt_sethostent
 269 function opens and/or rewinds the
 270 .Pa /etc/bluetooth/hosts
 271 file.
 272 .Pp
 273 The
 274 .Fn bt_getprotoent
 275 function reads the next line of
 276 .Pa /etc/bluetooth/protocols ,
 277 opening the file if necessary.
 278 .Pp
 279 The
 280 .Fn bt_setprotoent
 281 function opens and/or rewinds the
 282 .Pa /etc/bluetooth/protocols
 283 file.
 284 .Sh AUTHORS
 285 .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
 286 .Sh BUGS
 287 These functions use static data storage;
 288 if the data is needed for future use, it should be
 289 copied before any subsequent calls overwrite it.