Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
BLUETOOTH(3)	       FreeBSD Library Functions Manual		  BLUETOOTH(3)

     bt_gethostbyname, bt_gethostbyaddr, bt_gethostent,	bt_sethostent,
     bt_endhostent, bt_getprotobyname, bt_getprotobynumber, bt_getprotoent,
     bt_setprotoent, bt_endprotoent, bt_aton, bt_ntoa, bdaddr_same,
     bdaddr_any, bdaddr_copy --	Bluetooth routines

     Bluetooth User Library (libbluetooth, -lbluetooth)

     #include <bluetooth.h>

     struct hostent *
     bt_gethostbyname(const char *name);

     struct hostent *
     bt_gethostbyaddr(const char *addr,	int len, int type);

     struct hostent *

     bt_sethostent(int stayopen);


     struct protoent *
     bt_getprotobyname(const char *name);

     struct protoent *
     bt_getprotobynumber(int proto);

     struct protoent *

     bt_setprotoent(int	stayopen);


     bt_aton(const char	*str, bdaddr_t *ba);

     const char	*
     bt_ntoa(const bdaddr_t *ba, char *str);

     bt_devaddr(const char *devname, bdaddr_t *addr);

     bt_devname(char *devname, const bdaddr_t *addr);

     (bt_devenum_cb_t)(int s, struct bt_devinfo	const *di, void	*arg);

     bt_devinfo(struct bt_devinfo *di);

     bt_devenum(bt_devenum_cb_t	*cb, void *arg);

     bdaddr_same(const bdaddr_t	*a, const bdaddr_t *b);

     bdaddr_any(const bdaddr_t *a);

     bdaddr_copy(const bdaddr_t	*dst, const bdaddr_t *src);

     The bt_gethostent(), bt_gethostbyname() and bt_gethostbyaddr() functions
     each return a pointer to an object	with the hostent structure describing
     a Bluetooth host referenced by name or by address,	respectively.

     The name argument passed to bt_gethostbyname() should point to a
     NUL-terminated hostname.  The addr	argument passed	to bt_gethostbyaddr()
     should point to an	address	which is len bytes long, in binary form	(i.e.,
     not a Bluetooth BD_ADDR in	human readable ASCII form).  The type argument
     specifies the address family of this address and must be set to

     The structure returned contains the information obtained from a line in
     /etc/bluetooth/hosts file.

     The bt_sethostent() function controls whether /etc/bluetooth/hosts	file
     should stay open after each call to bt_gethostbyname() or
     bt_gethostbyaddr().  If the stayopen flag is non-zero, the	file will not
     be	closed.

     The bt_endhostent() function closes the /etc/bluetooth/hosts file.

     The bt_getprotoent(), bt_getprotobyname() and bt_getprotobynumber() func-
     tions each	return a pointer to an object with the protoent	structure
     describing	a Bluetooth Protocol Service Multiplexor referenced by name or
     number, respectively.

     The name argument passed to bt_getprotobyname() should point to a
     NUL-terminated Bluetooth Protocol Service Multiplexor name.  The proto
     argument passed to	bt_getprotobynumber() should have numeric value	of the
     desired Bluetooth Protocol	Service	Multiplexor.

     The structure returned contains the information obtained from a line in
     /etc/bluetooth/protocols file.

     The bt_setprotoent() function controls whether /etc/bluetooth/protocols
     file should stay open after each call to bt_getprotobyname() or
     bt_getprotobynumber().  If	the stayopen flag is non-zero, the file	will
     not be closed.

     The bt_endprotoent() function closes the /etc/bluetooth/protocols file.

     The 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.

     The routine bt_ntoa() takes a Bluetooth address and places	an 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 internal	static buffer will be used.

     The bt_devaddr() function interprets the specified	devname	string as the
     address or	device name of a Bluetooth device on the local system, and
     places the	device address in the provided bdaddr, if any.	The function
     returns 1 if the string was successfully interpreted, or 0	if the string
     did not match any local device.  The bt_devname() function	takes a	Blue-
     tooth device address and copies the local device name associated with
     that address into the buffer provided, if any.  Caller must ensure	that
     provided buffer is	at least HCI_DEVNAME_SIZE characters in	size.  The
     function returns 1	when the device	was found, otherwise 0.

     The bt_devinfo() function populates prodivded bt_devinfo structure	with
     the information about given Bluetooth device.  The	caller is expected to
     pass Bluetooth device name	in the devname field of	the passed bt_devinfo
     structure.	 The function returns 0	when successful, otherwise -1.	The
     bt_devinfo	structure is defined as	follows

	   struct bt_devinfo
		   char		   devname[HCI_DEVNAME_SIZE];

		   uint32_t	   state;

		   bdaddr_t	   bdaddr;
		   uint16_t	   _reserved0;

		   uint8_t	   features[HCI_DEVFEATURES_SIZE];

		   /* buffer info */
		   uint16_t	   _reserved1;
		   uint16_t	   cmd_free;
		   uint16_t	   sco_size;
		   uint16_t	   sco_pkts;
		   uint16_t	   sco_free;
		   uint16_t	   acl_size;
		   uint16_t	   acl_pkts;
		   uint16_t	   acl_free;

		   /* stats */
		   uint32_t	   cmd_sent;
		   uint32_t	   evnt_recv;
		   uint32_t	   acl_recv;
		   uint32_t	   acl_sent;
		   uint32_t	   sco_recv;
		   uint32_t	   sco_sent;
		   uint32_t	   bytes_recv;
		   uint32_t	   bytes_sent;

		   /* misc/specific */
		   uint16_t	   link_policy_info;
		   uint16_t	   packet_type_info;
		   uint16_t	   role_switch_info;
		   uint16_t	   debug;

		   uint8_t	   _padding[20];

     The bt_devenum() function enumerates Bluetooth devices present in the
     system.  For every	device found, the function will	call provided cb call-
     back function which should	be of bt_devenum_cb_t type.  The callback
     function is passed	a HCI socket s,	fully populated	bt_devinfo structure
     di	and arg	argument provided to the bt_devenum().	The callback function
     can stop enumeration by returning a value that is greater than zero.  The
     function returns number of	successfully enumerated	devices, or -1 if an
     error occurred.

     The bdaddr_same(),	bdaddr_any() and bdaddr_copy() are handy shorthand
     Bluetooth address utility functions.  The bdaddr_same() function will
     test if two provided BD_ADDRs are the same.  The bdaddr_any() function
     will test if provided BD_ADDR is ANY BD_ADDR.  The	bdaddr_copy() function
     will copy provided	src BD_ADDR into provided dst BD_ADDR.


     Print out the hostname associated with a specific BD_ADDR:

	   const char *bdstr = "00:01:02:03:04:05";
	   bdaddr_t bd;
	   struct hostent *hp;

	   if (!bt_aton(bdstr, &bd))
		   errx(1, "can't parse	BD_ADDR	%s", bdstr);

	   if ((hp = bt_gethostbyaddr((const char *)&bd,
	       sizeof(bd), AF_BLUETOOTH)) == NULL)
		   errx(1, "no name associated with %s", bdstr);

	   printf("name	associated with	%s is %s\n", bdstr, hp->h_name);

     Error return status from bt_gethostent(), bt_gethostbyname() and
     bt_gethostbyaddr()	is indicated by	return of a NULL pointer.  The exter-
     nal integer h_errno may then be checked to	see whether this is a tempo-
     rary failure or an	invalid	or unknown host.  The routine herror(3)	can be
     used to print an error message describing the failure.  If	its argument
     string is non-NULL, it is printed,	followed by a colon and	a space.  The
     error message is printed with a trailing newline.

     The variable h_errno can have the following values:

     HOST_NOT_FOUND  No	such host is known.

     NO_RECOVERY     Some unexpected server failure was	encountered.  This is
		     a non-recoverable error.

     The bt_getprotoent(), bt_getprotobyname() and bt_getprotobynumber()
     return NULL on EOF	or error.

     gethostbyaddr(3), gethostbyname(3), getprotobyname(3),
     getprotobynumber(3), herror(3), inet_aton(3), inet_ntoa(3), ng_hci(4)

     The bt_gethostent() function reads	the next line of /etc/bluetooth/hosts,
     opening the file if necessary.

     The bt_sethostent() function opens	and/or rewinds the
     /etc/bluetooth/hosts file.

     The bt_getprotoent() function reads the next line of
     /etc/bluetooth/protocols, opening the file	if necessary.

     The bt_setprotoent() function opens and/or	rewinds	the
     /etc/bluetooth/protocols file.

     The bt_devenum() function enumerates up to	HCI_DEVMAX Bluetooth devices.
     During enumeration	the bt_devenum() function uses the same	HCI socket.
     The function guarantees that the socket, passed to	the callback function,
     will be bound and connected to the	Bluetooth device being enumerated.

     Maksim Yevmenkin <>

     These functions use static	data storage; if the data is needed for	future
     use, it should be copied before any subsequent calls overwrite it.

FreeBSD	11.0		       February	13, 2009		  FreeBSD 11.0


Want to link to this manual page? Use this URL:

home | help