Annotation of src/lib/libbluetooth/bluetooth.3, Revision 1.1
1.1 ! gdamore 1: .\" $NetBSD: bluetooth.3$
! 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: .\" $Id: bluetooth.3,v 1.5 2003/05/20 23:04:30 max Exp $
! 28: .\" $FreeBSD: src/lib/libbluetooth/bluetooth.3,v 1.7 2005/01/21 10:26:11 ru Exp $
! 29: .\"
! 30: .Dd May 7, 2003
! 31: .Dt BLUETOOTH 3
! 32: .Os
! 33: .Sh NAME
! 34: .Nm bt_gethostbyname ,
! 35: .Nm bt_gethostbyaddr ,
! 36: .Nm bt_gethostent ,
! 37: .Nm bt_sethostent ,
! 38: .Nm bt_endhostent ,
! 39: .Nm bt_getprotobyname ,
! 40: .Nm bt_getprotobynumber ,
! 41: .Nm bt_getprotoent ,
! 42: .Nm bt_setprotoent ,
! 43: .Nm bt_endprotoent ,
! 44: .Nm bt_aton ,
! 45: .Nm bt_ntoa ,
! 46: .Nm bt_devaddr ,
! 47: .Nm bt_devname ,
! 48: .Nm bt_openconfig ,
! 49: .Nm bt_getconfig ,
! 50: .Nm bt_freeconfig ,
! 51: .Nm bt_eachconfig ,
! 52: .Nm bt_closeconfig ,
! 53: .Nm bt_printconfig
! 54: .Nd Bluetooth routines
! 55: .Sh LIBRARY
! 56: .Lb libbluetooth
! 57: .Sh SYNOPSIS
! 58: .In bluetooth.h
! 59: .Ft struct hostent *
! 60: .Fn bt_gethostbyname "const char *name"
! 61: .Ft struct hostent *
! 62: .Fn bt_gethostbyaddr "const char *addr" "int len" "int type"
! 63: .Ft struct hostent *
! 64: .Fn bt_gethostent void
! 65: .Ft void
! 66: .Fn bt_sethostent "int stayopen"
! 67: .Ft void
! 68: .Fn bt_endhostent void
! 69: .Ft struct protoent *
! 70: .Fn bt_getprotobyname "const char *name"
! 71: .Ft struct protoent *
! 72: .Fn bt_getprotobynumber "int proto"
! 73: .Ft struct protoent *
! 74: .Fn bt_getprotoent void
! 75: .Ft void
! 76: .Fn bt_setprotoent "int stayopen"
! 77: .Ft void
! 78: .Fn bt_endprotoent void
! 79: .Ft int
! 80: .Fn bt_aton "const char *str" "bdaddr_t *ba"
! 81: .Ft const char *
! 82: .Fn bt_ntoa "const bdaddr_t *ba" "char *str"
! 83: .Ft int
! 84: .Fn bt_devaddr "const char *name" "bdaddr_t *addr"
! 85: .Ft int
! 86: .Fn bt_devname "char *name" "const bdaddr_t *addr"
! 87: .Ft bt_handle_t
! 88: .Fn bt_openconfig "const char *name"
! 89: .Ft bt_cfgentry_t
! 90: .Fn bt_getconfig "bt_handle_t handle" "const bdaddr_t *ba"
! 91: .Ft int
! 92: .Fn bt_eachconfig "bt_handle_t handle" "void (*func)(bt_cfgentry_t *, void *)" "void *arg"
! 93: .Ft void
! 94: .Fn bt_freeconfig "bt_cfgentry_t *cfg"
! 95: .Ft int
! 96: .Fn bt_closeconfig "bt_handle_t handle"
! 97: .Ft int
! 98: .Fn bt_printconfig "FILE *fp" "bt_cfgentry_t *cfg"
! 99: .Sh DESCRIPTION
! 100: The
! 101: .Fn bt_gethostent ,
! 102: .Fn bt_gethostbyname
! 103: and
! 104: .Fn bt_gethostbyaddr
! 105: functions
! 106: each return a pointer to an object with the
! 107: .Vt hostent
! 108: structure describing a Bluetooth host
! 109: referenced by name or by address, respectively.
! 110: .Pp
! 111: The
! 112: .Fa name
! 113: argument passed to
! 114: .Fn bt_gethostbyname
! 115: should point to a
! 116: .Dv NUL Ns -terminated
! 117: hostname.
! 118: The
! 119: .Fa addr
! 120: argument passed to
! 121: .Fn bt_gethostbyaddr
! 122: should point to an address which is
! 123: .Fa len
! 124: bytes long,
! 125: in binary form
! 126: (i.e., not a Bluetooth BD_ADDR in human readable
! 127: .Tn ASCII
! 128: form).
! 129: The
! 130: .Fa type
! 131: argument specifies the address family of this address and must be set to
! 132: .Dv AF_BLUETOOTH .
! 133: .Pp
! 134: The structure returned contains the information obtained from a line in
! 135: .Pa /etc/bluetooth/hosts
! 136: file.
! 137: .Pp
! 138: The
! 139: .Fn bt_sethostent
! 140: function controls whether
! 141: .Pa /etc/bluetooth/hosts
! 142: file should stay open after each call to
! 143: .Fn bt_gethostbyname
! 144: or
! 145: .Fn bt_gethostbyaddr .
! 146: If the
! 147: .Fa stayopen
! 148: flag is non-zero, the file will not be closed.
! 149: .Pp
! 150: The
! 151: .Fn bt_endhostent
! 152: function closes the
! 153: .Pa /etc/bluetooth/hosts
! 154: file.
! 155: .Pp
! 156: The
! 157: .Fn bt_getprotoent ,
! 158: .Fn bt_getprotobyname
! 159: and
! 160: .Fn bt_getprotobynumber
! 161: functions each return a pointer to an object with the
! 162: .Vt protoent
! 163: structure describing a Bluetooth Protocol Service Multiplexor referenced
! 164: by name or number, respectively.
! 165: .Pp
! 166: The
! 167: .Fa name
! 168: argument passed to
! 169: .Fn bt_getprotobyname
! 170: should point to a
! 171: .Dv NUL Ns -terminated
! 172: Bluetooth Protocol Service Multiplexor name.
! 173: The
! 174: .Fa proto
! 175: argument passed to
! 176: .Fn bt_getprotobynumber
! 177: should have numeric value of the desired Bluetooth Protocol Service Multiplexor.
! 178: .Pp
! 179: The structure returned contains the information obtained from a line in
! 180: .Pa /etc/bluetooth/protocols
! 181: file.
! 182: .Pp
! 183: The
! 184: .Fn bt_setprotoent
! 185: function controls whether
! 186: .Pa /etc/bluetooth/protocols
! 187: file should stay open after each call to
! 188: .Fn bt_getprotobyname
! 189: or
! 190: .Fn bt_getprotobynumber .
! 191: If the
! 192: .Fa stayopen
! 193: flag is non-zero, the file will not be closed.
! 194: .Pp
! 195: The
! 196: .Fn bt_endprotoent
! 197: function closes the
! 198: .Pa /etc/bluetooth/protocols
! 199: file.
! 200: .Pp
! 201: The
! 202: .Fn bt_aton
! 203: routine interprets the specified character string as a Bluetooth address,
! 204: placing the address into the structure provided.
! 205: It returns 1 if the string was successfully interpreted,
! 206: or 0 if the string is invalid.
! 207: .Pp
! 208: The routine
! 209: .Fn bt_ntoa
! 210: takes a Bluetooth address and places an
! 211: .Tn ASCII
! 212: string representing the address into the buffer provided.
! 213: It is up to the caller to ensure that provided buffer has enough space.
! 214: If no buffer was provided then an internal static buffer will be used.
! 215: .Pp
! 216: The
! 217: .Fn bt_devaddr
! 218: function interprets the specified character string as the
! 219: address or device name of a Bluetooth device on the local system, and
! 220: places the device address in the structure provided, if any.
! 221: It returns 1 if the string was successfully interpreted,
! 222: or 0 if the string did not match any local device. The
! 223: .Fn bt_devname
! 224: function takes a Bluetooth device address and copies the local device
! 225: name associated with that address into the buffer provided, if any.
! 226: It returns 1 when the device was found, otherwise 0.
! 227: .Pp
! 228: The
! 229: .Fn bt_openconfig ,
! 230: .Fn bt_getconfig ,
! 231: .Fn bt_eachconfig ,
! 232: and
! 233: .Fn bt_closeconfig
! 234: functions can be used to extract configuration entries from files in the
! 235: .Xr bluetooth.conf 5
! 236: file format. If
! 237: .Dv NULL
! 238: is specified as the file name to
! 239: .Fn bt_openconfig ,
! 240: the default file name of
! 241: .Pa /etc/bluetooth/bluetooth.conf
! 242: will be used.
! 243: .Fn bt_getconfig
! 244: will scan the config file for a matching BD_ADDR and return a
! 245: pointer to a dynamically allocated
! 246: .Ar bt_cfgentry_t
! 247: structure which must be freed with
! 248: .Fn bt_freeconfig .
! 249: The
! 250: .Fn bt_eachconfig
! 251: function can be used to iterate through all entries in the config file,
! 252: with each config entry being passed to the given function in turn, then
! 253: freed automatically.
! 254: .Pp
! 255: The
! 256: .Fn bt_printconfig
! 257: function will print a config entry to the file pointer
! 258: in a format compatible with reading it later.
! 259: .Sh FILES
! 260: .Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact
! 261: .It Pa /etc/bluetooth/bluetooth.conf
! 262: .It Pa /etc/bluetooth/hosts
! 263: .It Pa /etc/bluetooth/protocols
! 264: .El
! 265: .Sh EXAMPLES
! 266: Print out the hostname associated with a specific BD_ADDR:
! 267: .Bd -literal -offset indent
! 268: const char *bdstr = "00:01:02:03:04:05";
! 269: bdaddr_t bd;
! 270: struct hostent *hp;
! 271:
! 272: if (!bt_aton(bdstr, &bd))
! 273: errx(1, "can't parse BD_ADDR %s", bdstr);
! 274:
! 275: if ((hp = bt_gethostbyaddr((const char *)&bd,
! 276: sizeof(bd), AF_BLUETOOTH)) == NULL)
! 277: errx(1, "no name associated with %s", bdstr);
! 278:
! 279: printf("name associated with %s is %s\en", bdstr, hp->h_name);
! 280: .Ed
! 281: .Sh DIAGNOSTICS
! 282: Error return status from
! 283: .Fn bt_gethostent ,
! 284: .Fn bt_gethostbyname
! 285: and
! 286: .Fn bt_gethostbyaddr
! 287: is indicated by return of a
! 288: .Dv NULL
! 289: pointer.
! 290: The external integer
! 291: .Va h_errno
! 292: may then be checked to see whether this is a temporary failure
! 293: or an invalid or unknown host.
! 294: The routine
! 295: .Xr herror 3
! 296: can be used to print an error message describing the failure.
! 297: If its argument
! 298: .Fa string
! 299: is
! 300: .Pf non- Dv NULL ,
! 301: it is printed, followed by a colon and a space.
! 302: The error message is printed with a trailing newline.
! 303: .Pp
! 304: The variable
! 305: .Va h_errno
! 306: can have the following values:
! 307: .Bl -tag -width ".Dv HOST_NOT_FOUND"
! 308: .It Dv HOST_NOT_FOUND
! 309: No such host is known.
! 310: .It Dv NO_RECOVERY
! 311: Some unexpected server failure was encountered.
! 312: This is a non-recoverable error.
! 313: .El
! 314: .Pp
! 315: The
! 316: .Fn bt_getprotoent ,
! 317: .Fn bt_getprotobyname
! 318: and
! 319: .Fn bt_getprotobynumber
! 320: return
! 321: .Dv NULL
! 322: on EOF or error.
! 323: .Sh SEE ALSO
! 324: .Xr bluetooth.conf 5 ,
! 325: .Xr gethostbyaddr 3 ,
! 326: .Xr gethostbyname 3 ,
! 327: .Xr getprotobyname 3 ,
! 328: .Xr getprotobynumber 3 ,
! 329: .Xr herror 3 ,
! 330: .Xr inet_aton 3 ,
! 331: .Xr inet_ntoa 3
! 332: .Sh CAVEAT
! 333: The
! 334: .Fn bt_gethostent
! 335: function reads the next line of
! 336: .Pa /etc/bluetooth/hosts ,
! 337: opening the file if necessary.
! 338: .Pp
! 339: The
! 340: .Fn bt_sethostent
! 341: function opens and/or rewinds the
! 342: .Pa /etc/bluetooth/hosts
! 343: file.
! 344: .Pp
! 345: The
! 346: .Fn bt_getprotoent
! 347: function reads the next line of
! 348: .Pa /etc/bluetooth/protocols ,
! 349: opening the file if necessary.
! 350: .Pp
! 351: The
! 352: .Fn bt_setprotoent
! 353: function opens and/or rewinds the
! 354: .Pa /etc/bluetooth/protocols
! 355: file.
! 356: .Sh AUTHORS
! 357: .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
! 358: .An Iain Hibbert
! 359: .Sh BUGS
! 360: These functions use static data storage;
! 361: if the data is needed for future use, it should be
! 362: copied before any subsequent calls overwrite it.
! 363: .Sh HISTORY
! 364: .Nm libbluetooth
! 365: first appeard in
! 366: .Fx
! 367: was ported to
! 368: .Nx 4.0
! 369: and extended by
! 370: .An Iain Hibbert
! 371: for Itronix, Inc.
CVSweb <webmaster@jp.NetBSD.org>