Manual for if_get(9) and if_put(9).

ok dlg@

2 files changed, 66 insertions, 3 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 0c49444020d..89ef43d2c17 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.266 2015/12/03 16:27:32 mpi Exp $
+#	$OpenBSD: Makefile,v 1.267 2015/12/08 10:06:40 mpi Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -17,8 +17,8 @@ MAN=	aml_evalnode.9 atomic_add_int.9 atomic_cas_uint.9 \
 	hardclock.9 hook_establish.9 hz.9 idgen32.9 \
 	ieee80211.9 ieee80211_crypto.9 ieee80211_input.9 ieee80211_ioctl.9 \
 	ieee80211_node.9 ieee80211_output.9 ieee80211_proto.9 \
-	ieee80211_radiotap.9 if_rxr_init.9 ifq_enqueue.9 ifq_deq_begin.9 \
-	iic.9 intro.9 inittodr.9 intr_barrier.9 \
+	ieee80211_radiotap.9 if_get.9 if_rxr_init.9 ifq_enqueue.9 \
+	ifq_deq_begin.9 iic.9 intro.9 inittodr.9 intr_barrier.9 \
 	kern.9 km_alloc.9 knote.9 kthread.9 ktrace.9 \
 	loadfirmware.9 lock.9 log.9 \
 	malloc.9 membar_sync.9 mbuf.9 mbuf_tags.9 md5.9 mi_switch.9 \
@@ -213,6 +213,7 @@ MLINKS+=ieee80211_proto.9 ieee80211_proto_attach.9 \
 	ieee80211_proto.9 ieee80211_print_essid.9 \
 	ieee80211_proto.9 ieee80211_dump_pkt.9 \
 	ieee80211_proto.9 ieee80211_fix_rate.9
+MLINKS+=if_get.9 if_put.9
 MLINKS+=if_rxr_init.9 if_rxr_get.9 if_rxr_init.9 if_rxr_put.9 \
 	if_rxr_init.9 if_rxr_inuse.9 if_rxr_init.9 if_rxr_ioctl.9 \
 	if_rxr_init.9 if_rxr_info_ioctl.9
diff --git a/share/man/man9/if_get.9 b/share/man/man9/if_get.9
new file mode 100644
index 00000000000..7fe69de1bb5
--- /dev/null
+++ b/share/man/man9/if_get.9
@@ -0,0 +1,62 @@
+.\" $OpenBSD: if_get.9,v 1.1 2015/12/08 10:06:40 mpi Exp $
+.\"
+.\" Copyright (c) 2015 Martin Pieuchot
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: December 8 2015 $
+.Dt IF_GET 9
+.Os
+.Sh NAME
+.Nm if_get ,
+.Nm if_put
+.Nd get an interface pointer from an interface index
+.Sh SYNOPSIS
+.In net/if.h
+.Ft struct ifnet *
+.Fn if_get "unsigned int ifidx"
+.Ft void
+.Fn if_put "struct ifnet *ifp"
+.Sh DESCRIPTION
+The
+.Fn if_get
+function returns a pointer to the interface descriptor corresponding to the
+unique index
+.Fa ifidx .
+This descriptor is guaranteed to be valid until
+.Fn if_put
+is called on the returned pointer.
+.Pp
+The index value
+.Dv 0
+is never associated to an interface descriptor and can be used to determine if
+and interface index is valid or not.
+.Pp
+The
+.Fn if_put
+function releases a reference on the interface descriptor pointed by
+.Fa ifp .
+If
+.Fa ifp
+is a
+.Dv NULL
+pointer, no action occurs.
+.Sh CONTEXT
+.Fn if_get ,
+and
+.Fn if_put
+can be called during autoconf, from process context, or from interrupt context.
+.Sh RETURN VALUES
+.Fn if_get
+returns a pointer to an interface descriptor if the index is valid, otherwise
+.Dv NULL .