mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-13 10:02:38 +00:00
Add a manpage for libdevinfo.
This commit is contained in:
Mike Smith
parent
98689e1e70
commit
09247921e5
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=75741
@ -4,6 +4,6 @@ LIB= devinfo
|
||||
SRCS= devinfo.c
|
||||
INCS= devinfo.h devinfo_var.h
|
||||
|
||||
NOMAN= yes
|
||||
MAN3= devinfo.3
|
||||
|
||||
.include <bsd.lib.mk>
|
||||
|
||||
237
lib/libdevinfo/devinfo.3
Normal file
237
lib/libdevinfo/devinfo.3
Normal file
@ -0,0 +1,237 @@
|
||||
.\"
|
||||
.\" Copyright (c) 2001 Michael Smith <msmith@FreeBSD.org>
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd April 19, 2001
|
||||
.Dt DEVINFO 3
|
||||
.Os FreeBSD
|
||||
.Sh NAME
|
||||
.Nm devinfo ,
|
||||
.Nm devinfo_init ,
|
||||
.Nm devinfo_free ,
|
||||
.Nm devinfo_handle_to_device ,
|
||||
.Nm devinfo_handle_to_resource ,
|
||||
.Nm devinfo_handle_to_rman ,
|
||||
.Nm devinfo_foreach_device_child ,
|
||||
.Nm devinfo_foreach_device_resource ,
|
||||
.Nm devinfo_foreach_rman_resource ,
|
||||
.Nm devinfo_foreach_rman
|
||||
.Nd device and resource information utility library
|
||||
.Sh LIBRARY
|
||||
.Lb libdevinfo
|
||||
.Sh SYNOPSIS
|
||||
.Fd #include <devinfo.h>
|
||||
.Ft int
|
||||
.Fn devinfo_init "void"
|
||||
.Ft void
|
||||
.Fn devinfo_free "void"
|
||||
.Ft struct devinfo_dev *
|
||||
.Fn devinfo_handle_to_device "devinfo_handle_t handle"
|
||||
.Ft struct devinfo_res *
|
||||
.Fn devinfo_handle_to_resource "devinfo_handle_t handle"
|
||||
.Ft struct devinfo_rman *
|
||||
.Fn devinfo_handle_to_rman "devinfo_handle_t handle"
|
||||
.Ft int
|
||||
.Fo devinfo_foreach_device_child
|
||||
.Fa "struct devinfo_dev *parent"
|
||||
.Fa "int (* fn)(struct devinfo_dev *child, void *arg)"
|
||||
.Fa "void *arg"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo devinfo_foreach_device_resource
|
||||
.Fa "struct devinfo_dev *dev"
|
||||
.Fa "int (* fn)(struct devinfo_dev *dev, struct devinfo_res *res, void *arg)"
|
||||
.Fa "void *arg"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo devinfo_foreach_rman_resource
|
||||
.Fa "struct devinfo_rman *rman"
|
||||
.Fa "int (* fn)(struct devinfo_res *res, void *arg)"
|
||||
.Fa "void *arg"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo devinfo_foreach_rman
|
||||
.Fa "int (* fn)(struct devinfo_rman *rman, void *arg)"
|
||||
.Fa "void *arg"
|
||||
.Fc
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Nm
|
||||
library provides access to the kernel's internal device hierarchy
|
||||
and to the I/O resource manager.
|
||||
The library uses a
|
||||
.Xr sysctl 3
|
||||
interface to obtain a snapshot of the kernel's state,
|
||||
which is then made available to the application.
|
||||
.Pp
|
||||
Due to the fact that the information may be logically arranged
|
||||
in a number of different fashions,
|
||||
the library does not attempt to impose any structure on the data.
|
||||
.Pp
|
||||
Device, resource, and resource manager information is returned in
|
||||
datastructures defined in
|
||||
.Aq Pa devinfo.h :
|
||||
.Bd -literal -offset indent
|
||||
struct devinfo_dev {
|
||||
devinfo_handle_t dd_handle; /* device handle */
|
||||
devinfo_handle_t dd_parent; /* parent handle */
|
||||
char *dd_name; /* name of device */
|
||||
char *dd_desc; /* device description */
|
||||
char *dd_drivername; /* name of attached driver */
|
||||
};
|
||||
|
||||
struct devinfo_rman {
|
||||
devinfo_handle_t dm_handle; /* resource manager handle */
|
||||
u_long dm_start; /* resource start */
|
||||
u_long dm_size; /* resource size */
|
||||
char *dm_desc; /* resource description */
|
||||
};
|
||||
|
||||
struct devinfo_res {
|
||||
devinfo_handle_t dr_handle; /* resource handle */
|
||||
devinfo_handle_t dr_rman; /* resource manager handle */
|
||||
devinfo_handle_t dr_device; /* owning device */
|
||||
u_long dr_start; /* region start */
|
||||
u_long dr_size; /* region size */
|
||||
};
|
||||
.Ed
|
||||
.Pp
|
||||
The
|
||||
.Va devinfo_handle_t
|
||||
values can be used to look up the correspondingly referenced structures.
|
||||
.Pp
|
||||
.Fn devinfo_init
|
||||
takes a snapshot of the kernel's internal device and resource state.
|
||||
It returns nonzero
|
||||
if after a number of retries a consistent snapshot cannot be obtained.
|
||||
.Fn devinfo_init
|
||||
must be called before any other functions can be used.
|
||||
.Pp
|
||||
.Fn devinfo_free
|
||||
releases the memory associated with the snapshot.
|
||||
Any pointers returned by other functions are invalidated by this,
|
||||
and
|
||||
.Fn devinfo_init
|
||||
must be called again before using any other functions.
|
||||
.Pp
|
||||
.Fn devinfo_handle_to_device ,
|
||||
.Fn devinfo_handle_to_resource
|
||||
and
|
||||
.Fn devinfo_handle_to_rman
|
||||
return pointers to
|
||||
.Va devinfo_dev ,
|
||||
.Va devinfo_res
|
||||
and
|
||||
.Va devinfo_rman
|
||||
structures respectively based on the
|
||||
.Va devinfo_handle_t
|
||||
passed to them.
|
||||
These functions can be used to traverse the tree from any node to any
|
||||
other node.
|
||||
If
|
||||
.Fn devinfo_handle_to_device
|
||||
is passed the constant
|
||||
.Dv DEVINFO_ROOT_DEVICE
|
||||
it will return the handle to the root of the device tree.
|
||||
.Pp
|
||||
.Fn devinfo_foreach_device_child
|
||||
invokes its callback argument
|
||||
.Ar fn
|
||||
on every device which is an immediate child of
|
||||
.Ar device .
|
||||
.Ar fn
|
||||
is also passed
|
||||
.Ar arg ,
|
||||
allowing state to be passed to the callback function.
|
||||
If
|
||||
.Ar fn
|
||||
returns a nonzero error value the traversal is halted,
|
||||
and
|
||||
.Fn devinfo_foreach_device_child
|
||||
returns the error value to its caller.
|
||||
.Pp
|
||||
.Fr devinfo_foreach_device_resource
|
||||
invokes its callback argument
|
||||
.Ar fn
|
||||
on every resource which is owned by
|
||||
.Ar device .
|
||||
.Ar fn
|
||||
is also passed
|
||||
.Ar device
|
||||
and
|
||||
.Ar arg ,
|
||||
allowing state to be passed to the callback function.
|
||||
If
|
||||
.Ar fn
|
||||
returns a nonzero error value the traversal is halted,
|
||||
and
|
||||
.Fn devinfo_foreach_device_resource
|
||||
returns the error value to its caller.
|
||||
.Pp
|
||||
.Fn devinfo_foreach_rman_resource
|
||||
invokes its callback argument
|
||||
.Ar fn
|
||||
on every resource within the resource manager
|
||||
.Ar rman .
|
||||
.Ar fn
|
||||
is also passed
|
||||
.Ar arg ,
|
||||
allowing state to be passed to the callback function.
|
||||
If
|
||||
.Ar fn
|
||||
returns a nonzero error value the traversal is halted,
|
||||
and
|
||||
.Fn devinfo_foreach_rman_resource
|
||||
returns the error value to its caller.
|
||||
.Pp
|
||||
.Fn devinfo_foreach_rman
|
||||
invokes its callback argument
|
||||
.Ar fn
|
||||
on every resource manager.
|
||||
.Ar fn is also passed
|
||||
.Ar arg ,
|
||||
allowing state to be passed to the callback function.
|
||||
If
|
||||
.Ar fn
|
||||
returns a nonzero error value the traversal is halted,
|
||||
and
|
||||
.Fn devinfo_foreach_rman
|
||||
returns the error value to its caller.
|
||||
.Sh SEE ALSO
|
||||
.Xr devstat 3
|
||||
.Sh HISTORY
|
||||
.Nm
|
||||
first appeared in
|
||||
.Os
|
||||
version 5.0
|
||||
.Sh AUTHORS
|
||||
.An Michael Smith Aq msmith@FreeBSD.org
|
||||
.Sh BUGS
|
||||
This is the first implementation of the library,
|
||||
and the interface is still subject to refinement.
|
||||
.Pp
|
||||
The interface does not report device classes or drivers,
|
||||
making it hard to sort by class or driver.
|
||||
Loading…
Reference in New Issue
Block a user