Create a man page for bus_child_present(9), a function to see if a

given device is considered accessible by its parent device bus driver
(or its parent, etc).

2 files changed, 84 insertions, 1 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 118714b..0750a31 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -20,7 +20,8 @@ MAN=	BUF_LOCK.9 BUF_LOCKFREE.9 BUF_LOCKINIT.9 BUF_REFCNT.9 \
 	VOP_READLINK.9 VOP_REALLOCBLKS.9 VOP_REMOVE.9 VOP_RENAME.9 \
 	VOP_REVOKE.9 VOP_SETACL.9 VOP_SETEXTATTR.9 VOP_STRATEGY.9 \
 	accept_filter.9 accf_data.9 accf_http.9 acl.9 atomic.9 \
-	bios.9 boot.9 buf.9 bus_alloc_resource.9 bus_generic_attach.9 \
+	bios.9 boot.9 buf.9 bus_alloc_resource.9 bus_child_present.9 \
+	bus_generic_attach.9 \
 	bus_generic_detach.9 \
 	bus_generic_print_child.9 bus_generic_read_ivar.9 \
 	bus_generic_shutdown.9 bus_release_resource.9 \
diff --git a/share/man/man9/bus_child_present.9 b/share/man/man9/bus_child_present.9
new file mode 100644
index 0000000..995a482
--- /dev/null
+++ b/share/man/man9/bus_child_present.9
@@ -0,0 +1,82 @@
+.\" -*- nroff -*-
+.\"
+.\" Copyright (c) 2003 M. Warner Losh
+.\"
+.\" All rights reserved.
+.\"
+.\" This program is free software.
+.\"
+.\" 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 DEVELOPERS ``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 DEVELOPERS 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 March 27, 2003
+.Dt BUS_CHILD_PRESENT 9
+.Os
+.Sh NAME
+.Nm bus_child_present
+.Nd Ask the bus driver to see if this device is still really present.
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/bus.h
+.Pp
+.In machine/bus.h
+.In sys/rman.h
+.In machine/resource.h
+.Ft int
+.Fn bus_child_present "device_t dev"
+.Sh DESCRIPTION
+Requests that the parent device driver of
+.Fa dev
+check to see if the
+hardware represented by
+.Fa dev 
+is still physically accessible at this time.
+While the notion of accessible varies from bus to bus, generally
+hardware that is not acceessible cannot be accessed via the bus_space
+methods that would otherwise be used to acceess the device.
+.Pp
+This does not ask the question 'does this device have children?' which
+can better be answered by
+.Xr device_get_children 9 .
+.Sh RETURN VALUES
+A zero return value indicates that the device is not present in the
+system.
+A non-zero return value indicates that the device is present in the
+system, or that the state of the device cannot be determined.
+.Sh EXAMPLES
+This is some example code.
+It only calls stop when the dc device is actually present.
+.Bd -literal
+	device_t dev;
+	dc_softc *sc;
+
+	sc = device_get_softc(dev);
+	if (bus_child_present(dev))
+		dc_stop(sc);
+.Ed
+.Sh SEE ALSO
+.Xr device 9 ,
+.Xr driver 9
+.Sh AUTHORS
+.An -nosplit
+This man page was written by
+.An Warner Losh Aq imp@FreeBSD.org .