[dragonfly.git] / lib / libbluetooth / bluetooth.3

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