Annotation of src/lib/libbluetooth/bluetooth.3, Revision 1.2
1.2 ! tron 1: .\" $NetBSD: bluetooth.3,v 1.1 2006/06/19 15:44:36 gdamore Exp $
1.1 gdamore 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: .\"
1.2 ! tron 27: .\" $Id: bluetooth.3,v 1.1 2006/06/19 15:44:36 gdamore Exp $
1.1 gdamore 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: .Nd Bluetooth routines
49: .Sh LIBRARY
50: .Lb libbluetooth
51: .Sh SYNOPSIS
52: .In bluetooth.h
53: .Ft struct hostent *
54: .Fn bt_gethostbyname "const char *name"
55: .Ft struct hostent *
56: .Fn bt_gethostbyaddr "const char *addr" "int len" "int type"
57: .Ft struct hostent *
58: .Fn bt_gethostent void
59: .Ft void
60: .Fn bt_sethostent "int stayopen"
61: .Ft void
62: .Fn bt_endhostent void
63: .Ft struct protoent *
64: .Fn bt_getprotobyname "const char *name"
65: .Ft struct protoent *
66: .Fn bt_getprotobynumber "int proto"
67: .Ft struct protoent *
68: .Fn bt_getprotoent void
69: .Ft void
70: .Fn bt_setprotoent "int stayopen"
71: .Ft void
72: .Fn bt_endprotoent void
73: .Ft int
74: .Fn bt_aton "const char *str" "bdaddr_t *ba"
75: .Ft const char *
76: .Fn bt_ntoa "const bdaddr_t *ba" "char *str"
77: .Ft int
78: .Fn bt_devaddr "const char *name" "bdaddr_t *addr"
79: .Ft int
80: .Fn bt_devname "char *name" "const bdaddr_t *addr"
81: .Sh DESCRIPTION
82: The
83: .Fn bt_gethostent ,
84: .Fn bt_gethostbyname
85: and
86: .Fn bt_gethostbyaddr
87: functions
88: 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 Multiplexor.
160: .Pp
161: The structure returned contains the information obtained from a line in
162: .Pa /etc/bluetooth/protocols
163: file.
164: .Pp
165: The
166: .Fn bt_setprotoent
167: function controls whether
168: .Pa /etc/bluetooth/protocols
169: file should stay open after each call to
170: .Fn bt_getprotobyname
171: or
172: .Fn bt_getprotobynumber .
173: If the
174: .Fa stayopen
175: flag is non-zero, the file will not be closed.
176: .Pp
177: The
178: .Fn bt_endprotoent
179: function closes the
180: .Pa /etc/bluetooth/protocols
181: file.
182: .Pp
183: The
184: .Fn bt_aton
185: routine interprets the specified character string as a Bluetooth address,
186: placing the address into the structure provided.
187: It returns 1 if the string was successfully interpreted,
188: or 0 if the string is invalid.
189: .Pp
190: The routine
191: .Fn bt_ntoa
192: takes a Bluetooth address and places an
193: .Tn ASCII
194: string representing the address into the buffer provided.
195: It is up to the caller to ensure that provided buffer has enough space.
196: If no buffer was provided then an internal static buffer will be used.
197: .Pp
198: The
199: .Fn bt_devaddr
200: function interprets the specified character string as the
201: address or device name of a Bluetooth device on the local system, and
202: places the device address in the structure provided, if any.
203: It returns 1 if the string was successfully interpreted,
204: or 0 if the string did not match any local device. The
205: .Fn bt_devname
206: function takes a Bluetooth device address and copies the local device
207: name associated with that address into the buffer provided, if any.
208: It returns 1 when the device was found, otherwise 0.
209: .Pp
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, &bd))
223: errx(1, "can't parse BD_ADDR %s", bdstr);
224:
225: if ((hp = bt_gethostbyaddr((const char *)&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->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 CAVEAT
282: The
283: .Fn bt_gethostent
284: function reads the next line of
285: .Pa /etc/bluetooth/hosts ,
286: opening the file if necessary.
287: .Pp
288: The
289: .Fn bt_sethostent
290: function opens and/or rewinds the
291: .Pa /etc/bluetooth/hosts
292: file.
293: .Pp
294: The
295: .Fn bt_getprotoent
296: function reads the next line of
297: .Pa /etc/bluetooth/protocols ,
298: opening the file if necessary.
299: .Pp
300: The
301: .Fn bt_setprotoent
302: function opens and/or rewinds the
303: .Pa /etc/bluetooth/protocols
304: file.
305: .Sh AUTHORS
306: .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
307: .An Iain Hibbert
308: .Sh BUGS
309: These functions use static data storage;
310: if the data is needed for future use, it should be
311: copied before any subsequent calls overwrite it.
312: .Sh HISTORY
313: .Nm libbluetooth
314: first appeard in
315: .Fx
316: was ported to
317: .Nx 4.0
318: and extended by
319: .An Iain Hibbert
320: for Itronix, Inc.
CVSweb <webmaster@jp.NetBSD.org>