[BACK]Return to bluetooth.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libbluetooth

Annotation of src/lib/libbluetooth/bluetooth.3, Revision 1.1

1.1     ! gdamore     1: .\" $NetBSD: bluetooth.3$
        !             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: .\" $Id: bluetooth.3,v 1.5 2003/05/20 23:04:30 max Exp $
        !            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: .Nm bt_openconfig ,
        !            49: .Nm bt_getconfig ,
        !            50: .Nm bt_freeconfig ,
        !            51: .Nm bt_eachconfig ,
        !            52: .Nm bt_closeconfig ,
        !            53: .Nm bt_printconfig
        !            54: .Nd Bluetooth routines
        !            55: .Sh LIBRARY
        !            56: .Lb libbluetooth
        !            57: .Sh SYNOPSIS
        !            58: .In bluetooth.h
        !            59: .Ft struct hostent *
        !            60: .Fn bt_gethostbyname "const char *name"
        !            61: .Ft struct hostent *
        !            62: .Fn bt_gethostbyaddr "const char *addr" "int len" "int type"
        !            63: .Ft struct hostent *
        !            64: .Fn bt_gethostent void
        !            65: .Ft void
        !            66: .Fn bt_sethostent "int stayopen"
        !            67: .Ft void
        !            68: .Fn bt_endhostent void
        !            69: .Ft struct protoent *
        !            70: .Fn bt_getprotobyname "const char *name"
        !            71: .Ft struct protoent *
        !            72: .Fn bt_getprotobynumber "int proto"
        !            73: .Ft struct protoent *
        !            74: .Fn bt_getprotoent void
        !            75: .Ft void
        !            76: .Fn bt_setprotoent "int stayopen"
        !            77: .Ft void
        !            78: .Fn bt_endprotoent void
        !            79: .Ft int
        !            80: .Fn bt_aton "const char *str" "bdaddr_t *ba"
        !            81: .Ft const char *
        !            82: .Fn bt_ntoa "const bdaddr_t *ba" "char *str"
        !            83: .Ft int
        !            84: .Fn bt_devaddr "const char *name" "bdaddr_t *addr"
        !            85: .Ft int
        !            86: .Fn bt_devname "char *name" "const bdaddr_t *addr"
        !            87: .Ft bt_handle_t
        !            88: .Fn bt_openconfig "const char *name"
        !            89: .Ft bt_cfgentry_t
        !            90: .Fn bt_getconfig "bt_handle_t handle" "const bdaddr_t *ba"
        !            91: .Ft int
        !            92: .Fn bt_eachconfig "bt_handle_t handle" "void (*func)(bt_cfgentry_t *, void *)" "void *arg"
        !            93: .Ft void
        !            94: .Fn bt_freeconfig "bt_cfgentry_t *cfg"
        !            95: .Ft int
        !            96: .Fn bt_closeconfig "bt_handle_t handle"
        !            97: .Ft int
        !            98: .Fn bt_printconfig "FILE *fp" "bt_cfgentry_t *cfg"
        !            99: .Sh DESCRIPTION
        !           100: The
        !           101: .Fn bt_gethostent ,
        !           102: .Fn bt_gethostbyname
        !           103: and
        !           104: .Fn bt_gethostbyaddr
        !           105: functions
        !           106: each return a pointer to an object with the
        !           107: .Vt hostent
        !           108: structure describing a Bluetooth host
        !           109: referenced by name or by address, respectively.
        !           110: .Pp
        !           111: The
        !           112: .Fa name
        !           113: argument passed to
        !           114: .Fn bt_gethostbyname
        !           115: should point to a
        !           116: .Dv NUL Ns -terminated
        !           117: hostname.
        !           118: The
        !           119: .Fa addr
        !           120: argument passed to
        !           121: .Fn bt_gethostbyaddr
        !           122: should point to an address which is
        !           123: .Fa len
        !           124: bytes long,
        !           125: in binary form
        !           126: (i.e., not a Bluetooth BD_ADDR in human readable
        !           127: .Tn ASCII
        !           128: form).
        !           129: The
        !           130: .Fa type
        !           131: argument specifies the address family of this address and must be set to
        !           132: .Dv AF_BLUETOOTH .
        !           133: .Pp
        !           134: The structure returned contains the information obtained from a line in
        !           135: .Pa /etc/bluetooth/hosts
        !           136: file.
        !           137: .Pp
        !           138: The
        !           139: .Fn bt_sethostent
        !           140: function controls whether
        !           141: .Pa /etc/bluetooth/hosts
        !           142: file should stay open after each call to
        !           143: .Fn bt_gethostbyname
        !           144: or
        !           145: .Fn bt_gethostbyaddr .
        !           146: If the
        !           147: .Fa stayopen
        !           148: flag is non-zero, the file will not be closed.
        !           149: .Pp
        !           150: The
        !           151: .Fn bt_endhostent
        !           152: function closes the
        !           153: .Pa /etc/bluetooth/hosts
        !           154: file.
        !           155: .Pp
        !           156: The
        !           157: .Fn bt_getprotoent ,
        !           158: .Fn bt_getprotobyname
        !           159: and
        !           160: .Fn bt_getprotobynumber
        !           161: functions each return a pointer to an object with the
        !           162: .Vt protoent
        !           163: structure describing a Bluetooth Protocol Service Multiplexor referenced
        !           164: by name or number, respectively.
        !           165: .Pp
        !           166: The
        !           167: .Fa name
        !           168: argument passed to
        !           169: .Fn bt_getprotobyname
        !           170: should point to a
        !           171: .Dv NUL Ns -terminated
        !           172: Bluetooth Protocol Service Multiplexor name.
        !           173: The
        !           174: .Fa proto
        !           175: argument passed to
        !           176: .Fn bt_getprotobynumber
        !           177: should have numeric value of the desired Bluetooth Protocol Service Multiplexor.
        !           178: .Pp
        !           179: The structure returned contains the information obtained from a line in
        !           180: .Pa /etc/bluetooth/protocols
        !           181: file.
        !           182: .Pp
        !           183: The
        !           184: .Fn bt_setprotoent
        !           185: function controls whether
        !           186: .Pa /etc/bluetooth/protocols
        !           187: file should stay open after each call to
        !           188: .Fn bt_getprotobyname
        !           189: or
        !           190: .Fn bt_getprotobynumber .
        !           191: If the
        !           192: .Fa stayopen
        !           193: flag is non-zero, the file will not be closed.
        !           194: .Pp
        !           195: The
        !           196: .Fn bt_endprotoent
        !           197: function closes the
        !           198: .Pa /etc/bluetooth/protocols
        !           199: file.
        !           200: .Pp
        !           201: The
        !           202: .Fn bt_aton
        !           203: routine interprets the specified character string as a Bluetooth address,
        !           204: placing the address into the structure provided.
        !           205: It returns 1 if the string was successfully interpreted,
        !           206: or 0 if the string is invalid.
        !           207: .Pp
        !           208: The routine
        !           209: .Fn bt_ntoa
        !           210: takes a Bluetooth address and places an
        !           211: .Tn ASCII
        !           212: string representing the address into the buffer provided.
        !           213: It is up to the caller to ensure that provided buffer has enough space.
        !           214: If no buffer was provided then an internal static buffer will be used.
        !           215: .Pp
        !           216: The
        !           217: .Fn bt_devaddr
        !           218: function interprets the specified character string as the
        !           219: address or device name of a Bluetooth device on the local system, and
        !           220: places the device address in the structure provided, if any.
        !           221: It returns 1 if the string was successfully interpreted,
        !           222: or 0 if the string did not match any local device. The
        !           223: .Fn bt_devname
        !           224: function takes a Bluetooth device address and copies the local device
        !           225: name associated with that address into the buffer provided, if any.
        !           226: It returns 1 when the device was found, otherwise 0.
        !           227: .Pp
        !           228: The
        !           229: .Fn bt_openconfig ,
        !           230: .Fn bt_getconfig ,
        !           231: .Fn bt_eachconfig ,
        !           232: and
        !           233: .Fn bt_closeconfig
        !           234: functions can be used to extract configuration entries from files in the
        !           235: .Xr bluetooth.conf 5
        !           236: file format. If
        !           237: .Dv NULL
        !           238: is specified as the file name to
        !           239: .Fn bt_openconfig ,
        !           240: the default file name of
        !           241: .Pa /etc/bluetooth/bluetooth.conf
        !           242: will be used.
        !           243: .Fn bt_getconfig
        !           244: will scan the config file for a matching BD_ADDR and return a
        !           245: pointer to a dynamically allocated
        !           246: .Ar bt_cfgentry_t
        !           247: structure which must be freed with
        !           248: .Fn bt_freeconfig .
        !           249: The
        !           250: .Fn bt_eachconfig
        !           251: function can be used to iterate through all entries in the config file,
        !           252: with each config entry being passed to the given function in turn, then
        !           253: freed automatically.
        !           254: .Pp
        !           255: The
        !           256: .Fn bt_printconfig
        !           257: function will print a config entry to the file pointer
        !           258: in a format compatible with reading it later.
        !           259: .Sh FILES
        !           260: .Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact
        !           261: .It Pa /etc/bluetooth/bluetooth.conf
        !           262: .It Pa /etc/bluetooth/hosts
        !           263: .It Pa /etc/bluetooth/protocols
        !           264: .El
        !           265: .Sh EXAMPLES
        !           266: Print out the hostname associated with a specific BD_ADDR:
        !           267: .Bd -literal -offset indent
        !           268: const char *bdstr = "00:01:02:03:04:05";
        !           269: bdaddr_t bd;
        !           270: struct hostent *hp;
        !           271:
        !           272: if (!bt_aton(bdstr, &bd))
        !           273:        errx(1, "can't parse BD_ADDR %s", bdstr);
        !           274:
        !           275: if ((hp = bt_gethostbyaddr((const char *)&bd,
        !           276:     sizeof(bd), AF_BLUETOOTH)) == NULL)
        !           277:        errx(1, "no name associated with %s", bdstr);
        !           278:
        !           279: printf("name associated with %s is %s\en", bdstr, hp->h_name);
        !           280: .Ed
        !           281: .Sh DIAGNOSTICS
        !           282: Error return status from
        !           283: .Fn bt_gethostent ,
        !           284: .Fn bt_gethostbyname
        !           285: and
        !           286: .Fn bt_gethostbyaddr
        !           287: is indicated by return of a
        !           288: .Dv NULL
        !           289: pointer.
        !           290: The external integer
        !           291: .Va h_errno
        !           292: may then be checked to see whether this is a temporary failure
        !           293: or an invalid or unknown host.
        !           294: The routine
        !           295: .Xr herror 3
        !           296: can be used to print an error message describing the failure.
        !           297: If its argument
        !           298: .Fa string
        !           299: is
        !           300: .Pf non- Dv NULL ,
        !           301: it is printed, followed by a colon and a space.
        !           302: The error message is printed with a trailing newline.
        !           303: .Pp
        !           304: The variable
        !           305: .Va h_errno
        !           306: can have the following values:
        !           307: .Bl -tag -width ".Dv HOST_NOT_FOUND"
        !           308: .It Dv HOST_NOT_FOUND
        !           309: No such host is known.
        !           310: .It Dv NO_RECOVERY
        !           311: Some unexpected server failure was encountered.
        !           312: This is a non-recoverable error.
        !           313: .El
        !           314: .Pp
        !           315: The
        !           316: .Fn bt_getprotoent ,
        !           317: .Fn bt_getprotobyname
        !           318: and
        !           319: .Fn bt_getprotobynumber
        !           320: return
        !           321: .Dv NULL
        !           322: on EOF or error.
        !           323: .Sh SEE ALSO
        !           324: .Xr bluetooth.conf 5 ,
        !           325: .Xr gethostbyaddr 3 ,
        !           326: .Xr gethostbyname 3 ,
        !           327: .Xr getprotobyname 3 ,
        !           328: .Xr getprotobynumber 3 ,
        !           329: .Xr herror 3 ,
        !           330: .Xr inet_aton 3 ,
        !           331: .Xr inet_ntoa 3
        !           332: .Sh CAVEAT
        !           333: The
        !           334: .Fn bt_gethostent
        !           335: function reads the next line of
        !           336: .Pa /etc/bluetooth/hosts ,
        !           337: opening the file if necessary.
        !           338: .Pp
        !           339: The
        !           340: .Fn bt_sethostent
        !           341: function opens and/or rewinds the
        !           342: .Pa /etc/bluetooth/hosts
        !           343: file.
        !           344: .Pp
        !           345: The
        !           346: .Fn bt_getprotoent
        !           347: function reads the next line of
        !           348: .Pa /etc/bluetooth/protocols ,
        !           349: opening the file if necessary.
        !           350: .Pp
        !           351: The
        !           352: .Fn bt_setprotoent
        !           353: function opens and/or rewinds the
        !           354: .Pa /etc/bluetooth/protocols
        !           355: file.
        !           356: .Sh AUTHORS
        !           357: .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
        !           358: .An Iain Hibbert
        !           359: .Sh BUGS
        !           360: These functions use static data storage;
        !           361: if the data is needed for future use, it should be
        !           362: copied before any subsequent calls overwrite it.
        !           363: .Sh HISTORY
        !           364: .Nm libbluetooth
        !           365: first appeard in
        !           366: .Fx
        !           367: was ported to
        !           368: .Nx 4.0
        !           369: and extended by
        !           370: .An Iain Hibbert
        !           371: for Itronix, Inc.

CVSweb <webmaster@jp.NetBSD.org>