320 lines
8.0 KiB
Groff
320 lines
8.0 KiB
Groff
.\" $NetBSD: bluetooth.3,v 1.3 2006/07/30 00:15:54 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2003 Maksim Yevmenkin <m_evmenkin@yahoo.com>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $Id: bluetooth.3,v 1.3 2006/07/30 00:15:54 wiz Exp $
|
|
.\" $FreeBSD: src/lib/libbluetooth/bluetooth.3,v 1.7 2005/01/21 10:26:11 ru Exp $
|
|
.\"
|
|
.Dd July 26, 2006
|
|
.Dt BLUETOOTH 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm bt_gethostbyname ,
|
|
.Nm bt_gethostbyaddr ,
|
|
.Nm bt_gethostent ,
|
|
.Nm bt_sethostent ,
|
|
.Nm bt_endhostent ,
|
|
.Nm bt_getprotobyname ,
|
|
.Nm bt_getprotobynumber ,
|
|
.Nm bt_getprotoent ,
|
|
.Nm bt_setprotoent ,
|
|
.Nm bt_endprotoent ,
|
|
.Nm bt_aton ,
|
|
.Nm bt_ntoa ,
|
|
.Nm bt_devaddr ,
|
|
.Nm bt_devname ,
|
|
.Nd Bluetooth routines
|
|
.Sh LIBRARY
|
|
.Lb libbluetooth
|
|
.Sh SYNOPSIS
|
|
.In bluetooth.h
|
|
.Ft struct hostent *
|
|
.Fn bt_gethostbyname "const char *name"
|
|
.Ft struct hostent *
|
|
.Fn bt_gethostbyaddr "const char *addr" "int len" "int type"
|
|
.Ft struct hostent *
|
|
.Fn bt_gethostent void
|
|
.Ft void
|
|
.Fn bt_sethostent "int stayopen"
|
|
.Ft void
|
|
.Fn bt_endhostent void
|
|
.Ft struct protoent *
|
|
.Fn bt_getprotobyname "const char *name"
|
|
.Ft struct protoent *
|
|
.Fn bt_getprotobynumber "int proto"
|
|
.Ft struct protoent *
|
|
.Fn bt_getprotoent void
|
|
.Ft void
|
|
.Fn bt_setprotoent "int stayopen"
|
|
.Ft void
|
|
.Fn bt_endprotoent void
|
|
.Ft int
|
|
.Fn bt_aton "const char *str" "bdaddr_t *ba"
|
|
.Ft const char *
|
|
.Fn bt_ntoa "const bdaddr_t *ba" "char *str"
|
|
.Ft int
|
|
.Fn bt_devaddr "const char *name" "bdaddr_t *addr"
|
|
.Ft int
|
|
.Fn bt_devname "char *name" "const bdaddr_t *addr"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn bt_gethostent ,
|
|
.Fn bt_gethostbyname ,
|
|
and
|
|
.Fn bt_gethostbyaddr
|
|
functions each return a pointer to an object with the
|
|
.Vt hostent
|
|
structure describing a Bluetooth host
|
|
referenced by name or by address, respectively.
|
|
.Pp
|
|
The
|
|
.Fa name
|
|
argument passed to
|
|
.Fn bt_gethostbyname
|
|
should point to a
|
|
.Dv NUL Ns -terminated
|
|
hostname.
|
|
The
|
|
.Fa addr
|
|
argument passed to
|
|
.Fn bt_gethostbyaddr
|
|
should point to an address which is
|
|
.Fa len
|
|
bytes long,
|
|
in binary form
|
|
(i.e., not a Bluetooth BD_ADDR in human readable
|
|
.Tn ASCII
|
|
form).
|
|
The
|
|
.Fa type
|
|
argument specifies the address family of this address and must be set to
|
|
.Dv AF_BLUETOOTH .
|
|
.Pp
|
|
The structure returned contains the information obtained from a line in
|
|
.Pa /etc/bluetooth/hosts
|
|
file.
|
|
.Pp
|
|
The
|
|
.Fn bt_sethostent
|
|
function controls whether
|
|
.Pa /etc/bluetooth/hosts
|
|
file should stay open after each call to
|
|
.Fn bt_gethostbyname
|
|
or
|
|
.Fn bt_gethostbyaddr .
|
|
If the
|
|
.Fa stayopen
|
|
flag is non-zero, the file will not be closed.
|
|
.Pp
|
|
The
|
|
.Fn bt_endhostent
|
|
function closes the
|
|
.Pa /etc/bluetooth/hosts
|
|
file.
|
|
.Pp
|
|
The
|
|
.Fn bt_getprotoent ,
|
|
.Fn bt_getprotobyname ,
|
|
and
|
|
.Fn bt_getprotobynumber
|
|
functions each return a pointer to an object with the
|
|
.Vt protoent
|
|
structure describing a Bluetooth Protocol Service Multiplexor referenced
|
|
by name or number, respectively.
|
|
.Pp
|
|
The
|
|
.Fa name
|
|
argument passed to
|
|
.Fn bt_getprotobyname
|
|
should point to a
|
|
.Dv NUL Ns -terminated
|
|
Bluetooth Protocol Service Multiplexor name.
|
|
The
|
|
.Fa proto
|
|
argument passed to
|
|
.Fn bt_getprotobynumber
|
|
should have numeric value of the desired Bluetooth Protocol Service
|
|
Multiplexor.
|
|
.Pp
|
|
The structure returned contains the information obtained from a line in
|
|
.Pa /etc/bluetooth/protocols
|
|
file.
|
|
.Pp
|
|
The
|
|
.Fn bt_setprotoent
|
|
function controls whether
|
|
.Pa /etc/bluetooth/protocols
|
|
file should stay open after each call to
|
|
.Fn bt_getprotobyname
|
|
or
|
|
.Fn bt_getprotobynumber .
|
|
If the
|
|
.Fa stayopen
|
|
flag is non-zero, the file will not be closed.
|
|
.Pp
|
|
The
|
|
.Fn bt_endprotoent
|
|
function closes the
|
|
.Pa /etc/bluetooth/protocols
|
|
file.
|
|
.Pp
|
|
The
|
|
.Fn bt_aton
|
|
routine interprets the specified character string as a Bluetooth address,
|
|
placing the address into the structure provided.
|
|
It returns 1 if the string was successfully interpreted,
|
|
or 0 if the string is invalid.
|
|
.Pp
|
|
The routine
|
|
.Fn bt_ntoa
|
|
takes a Bluetooth address and places an
|
|
.Tn ASCII
|
|
string representing the address into the buffer provided.
|
|
It is up to the caller to ensure that provided buffer has enough space.
|
|
If no buffer was provided then an internal static buffer will be used.
|
|
.Pp
|
|
The
|
|
.Fn bt_devaddr
|
|
function interprets the specified character string as the
|
|
address or device name of a Bluetooth device on the local system, and
|
|
places the device address in the structure provided, if any.
|
|
It returns 1 if the string was successfully interpreted,
|
|
or 0 if the string did not match any local device. The
|
|
.Fn bt_devname
|
|
function takes a Bluetooth device address and copies the local device
|
|
name associated with that address into the buffer provided, if any.
|
|
It returns 1 when the device was found, otherwise 0.
|
|
.Sh FILES
|
|
.Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact
|
|
.It Pa /etc/bluetooth/hosts
|
|
.It Pa /etc/bluetooth/protocols
|
|
.El
|
|
.Sh EXAMPLES
|
|
Print out the hostname associated with a specific BD_ADDR:
|
|
.Bd -literal -offset indent
|
|
const char *bdstr = "00:01:02:03:04:05";
|
|
bdaddr_t bd;
|
|
struct hostent *hp;
|
|
|
|
if (!bt_aton(bdstr, \*[Am]bd))
|
|
errx(1, "can't parse BD_ADDR %s", bdstr);
|
|
|
|
if ((hp = bt_gethostbyaddr((const char *)\*[Am]bd,
|
|
sizeof(bd), AF_BLUETOOTH)) == NULL)
|
|
errx(1, "no name associated with %s", bdstr);
|
|
|
|
printf("name associated with %s is %s\en", bdstr, hp-\*[Gt]h_name);
|
|
.Ed
|
|
.Sh DIAGNOSTICS
|
|
Error return status from
|
|
.Fn bt_gethostent ,
|
|
.Fn bt_gethostbyname ,
|
|
and
|
|
.Fn bt_gethostbyaddr
|
|
is indicated by return of a
|
|
.Dv NULL
|
|
pointer.
|
|
The external integer
|
|
.Va h_errno
|
|
may then be checked to see whether this is a temporary failure
|
|
or an invalid or unknown host.
|
|
The routine
|
|
.Xr herror 3
|
|
can be used to print an error message describing the failure.
|
|
If its argument
|
|
.Fa string
|
|
is
|
|
.Pf non- Dv NULL ,
|
|
it is printed, followed by a colon and a space.
|
|
The error message is printed with a trailing newline.
|
|
.Pp
|
|
The variable
|
|
.Va h_errno
|
|
can have the following values:
|
|
.Bl -tag -width ".Dv HOST_NOT_FOUND"
|
|
.It Dv HOST_NOT_FOUND
|
|
No such host is known.
|
|
.It Dv NO_RECOVERY
|
|
Some unexpected server failure was encountered.
|
|
This is a non-recoverable error.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn bt_getprotoent ,
|
|
.Fn bt_getprotobyname ,
|
|
and
|
|
.Fn bt_getprotobynumber
|
|
return
|
|
.Dv NULL
|
|
on EOF or error.
|
|
.Sh SEE ALSO
|
|
.Xr gethostbyaddr 3 ,
|
|
.Xr gethostbyname 3 ,
|
|
.Xr getprotobyname 3 ,
|
|
.Xr getprotobynumber 3 ,
|
|
.Xr herror 3 ,
|
|
.Xr inet_aton 3 ,
|
|
.Xr inet_ntoa 3
|
|
.Sh HISTORY
|
|
.Nm libbluetooth
|
|
first appeared in
|
|
.Fx
|
|
was ported to
|
|
.Nx 4.0
|
|
and extended by
|
|
.An Iain Hibbert
|
|
for Itronix, Inc.
|
|
.Sh AUTHORS
|
|
.An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
|
|
.An Iain Hibbert
|
|
.Sh CAVEATS
|
|
The
|
|
.Fn bt_gethostent
|
|
function reads the next line of
|
|
.Pa /etc/bluetooth/hosts ,
|
|
opening the file if necessary.
|
|
.Pp
|
|
The
|
|
.Fn bt_sethostent
|
|
function opens and/or rewinds the
|
|
.Pa /etc/bluetooth/hosts
|
|
file.
|
|
.Pp
|
|
The
|
|
.Fn bt_getprotoent
|
|
function reads the next line of
|
|
.Pa /etc/bluetooth/protocols ,
|
|
opening the file if necessary.
|
|
.Pp
|
|
The
|
|
.Fn bt_setprotoent
|
|
function opens and/or rewinds the
|
|
.Pa /etc/bluetooth/protocols
|
|
file.
|
|
.Sh BUGS
|
|
These functions use static data storage;
|
|
if the data is needed for future use, it should be
|
|
copied before any subsequent calls overwrite it.
|