Annotation of src/lib/libbluetooth/bluetooth.3, Revision 1.6
1.6 ! wiz 1: .\" $NetBSD: bluetooth.3,v 1.5 2011/10/25 09:33:55 plunky 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: .\"
27: .\" $FreeBSD: src/lib/libbluetooth/bluetooth.3,v 1.7 2005/01/21 10:26:11 ru Exp $
28: .\"
1.5 plunky 29: .Dd October 25, 2011
1.1 gdamore 30: .Dt BLUETOOTH 3
31: .Os
32: .Sh NAME
33: .Nm bt_gethostbyname ,
34: .Nm bt_gethostbyaddr ,
35: .Nm bt_gethostent ,
36: .Nm bt_sethostent ,
37: .Nm bt_endhostent ,
38: .Nm bt_getprotobyname ,
39: .Nm bt_getprotobynumber ,
40: .Nm bt_getprotoent ,
41: .Nm bt_setprotoent ,
42: .Nm bt_endprotoent ,
43: .Nm bt_aton ,
1.5 plunky 44: .Nm bt_ntoa
1.4 plunky 45: .Nd Bluetooth host lookup routines
1.1 gdamore 46: .Sh LIBRARY
47: .Lb libbluetooth
48: .Sh SYNOPSIS
49: .In bluetooth.h
50: .Ft struct hostent *
51: .Fn bt_gethostbyname "const char *name"
52: .Ft struct hostent *
53: .Fn bt_gethostbyaddr "const char *addr" "int len" "int type"
54: .Ft struct hostent *
55: .Fn bt_gethostent void
56: .Ft void
57: .Fn bt_sethostent "int stayopen"
58: .Ft void
59: .Fn bt_endhostent void
60: .Ft struct protoent *
61: .Fn bt_getprotobyname "const char *name"
62: .Ft struct protoent *
63: .Fn bt_getprotobynumber "int proto"
64: .Ft struct protoent *
65: .Fn bt_getprotoent void
66: .Ft void
67: .Fn bt_setprotoent "int stayopen"
68: .Ft void
69: .Fn bt_endprotoent void
70: .Ft int
71: .Fn bt_aton "const char *str" "bdaddr_t *ba"
72: .Ft const char *
73: .Fn bt_ntoa "const bdaddr_t *ba" "char *str"
74: .Sh DESCRIPTION
75: The
76: .Fn bt_gethostent ,
1.3 wiz 77: .Fn bt_gethostbyname ,
1.1 gdamore 78: and
79: .Fn bt_gethostbyaddr
1.3 wiz 80: functions each return a pointer to an object with the
1.1 gdamore 81: .Vt hostent
82: structure describing a Bluetooth host
83: referenced by name or by address, respectively.
84: .Pp
85: The
86: .Fa name
87: argument passed to
88: .Fn bt_gethostbyname
89: should point to a
90: .Dv NUL Ns -terminated
91: hostname.
92: The
93: .Fa addr
94: argument passed to
95: .Fn bt_gethostbyaddr
96: should point to an address which is
97: .Fa len
98: bytes long,
99: in binary form
100: (i.e., not a Bluetooth BD_ADDR in human readable
101: .Tn ASCII
102: form).
103: The
104: .Fa type
105: argument specifies the address family of this address and must be set to
106: .Dv AF_BLUETOOTH .
107: .Pp
108: The structure returned contains the information obtained from a line in
109: .Pa /etc/bluetooth/hosts
110: file.
111: .Pp
112: The
113: .Fn bt_sethostent
114: function controls whether
115: .Pa /etc/bluetooth/hosts
116: file should stay open after each call to
117: .Fn bt_gethostbyname
118: or
119: .Fn bt_gethostbyaddr .
120: If the
121: .Fa stayopen
122: flag is non-zero, the file will not be closed.
123: .Pp
124: The
125: .Fn bt_endhostent
126: function closes the
127: .Pa /etc/bluetooth/hosts
128: file.
129: .Pp
130: The
131: .Fn bt_getprotoent ,
1.3 wiz 132: .Fn bt_getprotobyname ,
1.1 gdamore 133: and
134: .Fn bt_getprotobynumber
135: functions each return a pointer to an object with the
136: .Vt protoent
137: structure describing a Bluetooth Protocol Service Multiplexor referenced
138: by name or number, respectively.
139: .Pp
140: The
141: .Fa name
142: argument passed to
143: .Fn bt_getprotobyname
144: should point to a
145: .Dv NUL Ns -terminated
146: Bluetooth Protocol Service Multiplexor name.
147: The
148: .Fa proto
149: argument passed to
150: .Fn bt_getprotobynumber
1.3 wiz 151: should have numeric value of the desired Bluetooth Protocol Service
152: Multiplexor.
1.1 gdamore 153: .Pp
154: The structure returned contains the information obtained from a line in
155: .Pa /etc/bluetooth/protocols
156: file.
157: .Pp
158: The
159: .Fn bt_setprotoent
160: function controls whether
161: .Pa /etc/bluetooth/protocols
162: file should stay open after each call to
163: .Fn bt_getprotobyname
164: or
165: .Fn bt_getprotobynumber .
166: If the
167: .Fa stayopen
168: flag is non-zero, the file will not be closed.
169: .Pp
170: The
171: .Fn bt_endprotoent
172: function closes the
173: .Pa /etc/bluetooth/protocols
174: file.
175: .Pp
176: The
177: .Fn bt_aton
178: routine interprets the specified character string as a Bluetooth address,
179: placing the address into the structure provided.
180: It returns 1 if the string was successfully interpreted,
181: or 0 if the string is invalid.
182: .Pp
183: The routine
184: .Fn bt_ntoa
185: takes a Bluetooth address and places an
186: .Tn ASCII
187: string representing the address into the buffer provided.
188: It is up to the caller to ensure that provided buffer has enough space.
189: If no buffer was provided then an internal static buffer will be used.
190: .Sh FILES
191: .Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact
192: .It Pa /etc/bluetooth/hosts
193: .It Pa /etc/bluetooth/protocols
194: .El
195: .Sh EXAMPLES
196: Print out the hostname associated with a specific BD_ADDR:
197: .Bd -literal -offset indent
198: const char *bdstr = "00:01:02:03:04:05";
199: bdaddr_t bd;
200: struct hostent *hp;
201:
1.3 wiz 202: if (!bt_aton(bdstr, \*[Am]bd))
1.1 gdamore 203: errx(1, "can't parse BD_ADDR %s", bdstr);
204:
1.3 wiz 205: if ((hp = bt_gethostbyaddr((const char *)\*[Am]bd,
1.1 gdamore 206: sizeof(bd), AF_BLUETOOTH)) == NULL)
207: errx(1, "no name associated with %s", bdstr);
208:
1.3 wiz 209: printf("name associated with %s is %s\en", bdstr, hp-\*[Gt]h_name);
1.1 gdamore 210: .Ed
211: .Sh DIAGNOSTICS
212: Error return status from
213: .Fn bt_gethostent ,
1.3 wiz 214: .Fn bt_gethostbyname ,
1.1 gdamore 215: and
216: .Fn bt_gethostbyaddr
217: is indicated by return of a
218: .Dv NULL
219: pointer.
220: The external integer
221: .Va h_errno
222: may then be checked to see whether this is a temporary failure
223: or an invalid or unknown host.
224: The routine
225: .Xr herror 3
226: can be used to print an error message describing the failure.
227: If its argument
228: .Fa string
229: is
230: .Pf non- Dv NULL ,
231: it is printed, followed by a colon and a space.
232: The error message is printed with a trailing newline.
233: .Pp
234: The variable
235: .Va h_errno
236: can have the following values:
237: .Bl -tag -width ".Dv HOST_NOT_FOUND"
238: .It Dv HOST_NOT_FOUND
239: No such host is known.
240: .It Dv NO_RECOVERY
241: Some unexpected server failure was encountered.
242: This is a non-recoverable error.
243: .El
244: .Pp
245: The
246: .Fn bt_getprotoent ,
1.3 wiz 247: .Fn bt_getprotobyname ,
1.1 gdamore 248: and
249: .Fn bt_getprotobynumber
250: return
251: .Dv NULL
252: on EOF or error.
253: .Sh SEE ALSO
254: .Xr gethostbyaddr 3 ,
255: .Xr gethostbyname 3 ,
256: .Xr getprotobyname 3 ,
257: .Xr getprotobynumber 3 ,
258: .Xr herror 3 ,
259: .Xr inet_aton 3 ,
260: .Xr inet_ntoa 3
1.3 wiz 261: .Sh HISTORY
262: .Nm libbluetooth
263: first appeared in
264: .Fx
265: was ported to
266: .Nx 4.0
267: and extended by
268: .An Iain Hibbert
269: for Itronix, Inc.
270: .Sh AUTHORS
1.6 ! wiz 271: .An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com
1.3 wiz 272: .An Iain Hibbert
273: .Sh CAVEATS
1.1 gdamore 274: The
275: .Fn bt_gethostent
276: function reads the next line of
277: .Pa /etc/bluetooth/hosts ,
278: opening the file if necessary.
279: .Pp
280: The
281: .Fn bt_sethostent
282: function opens and/or rewinds the
283: .Pa /etc/bluetooth/hosts
284: file.
285: .Pp
286: The
287: .Fn bt_getprotoent
288: function reads the next line of
289: .Pa /etc/bluetooth/protocols ,
290: opening the file if necessary.
291: .Pp
292: The
293: .Fn bt_setprotoent
294: function opens and/or rewinds the
295: .Pa /etc/bluetooth/protocols
296: file.
297: .Sh BUGS
298: These functions use static data storage;
299: if the data is needed for future use, it should be
300: copied before any subsequent calls overwrite it.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to bluetooth.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libbluetooth