c32fb642e18660dc556c05ae8c3c607d22e08fcc
[dragonfly.git] / lib / libbluetooth / bluetooth.3
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 *
57 .Fn bt_gethostbyaddr "const char *addr" "int len" "int type"
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
225 if ((hp = bt_gethostbyaddr((const char *)\*[Am]bd,
226     sizeof(bd), AF_BLUETOOTH)) == NULL)
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.