Document rtalloc(9).

3 files changed, 86 insertions, 15 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 5cef42c9406..bcaac45d0f9 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.220 2014/10/08 07:39:46 mpi Exp $
+#	$OpenBSD: Makefile,v 1.221 2014/11/01 21:45:54 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.
@@ -26,8 +26,8 @@ MAN=	aml_evalnode.9 atomic_add_int.9 atomic_cas_uint.9 \
 	panic.9 pci_conf_read.9 pci_intr_map.9 pfind.9 physio.9 pmap.9 \
 	pool.9 powerhook_establish.9 ppsratecheck.9 printf.9 psignal.9 \
 	radio.9 arc4random.9 rasops.9 ratecheck.9 resettodr.9 rssadapt.9 \
-	rt_ifa_add.9 rt_timer_add.9 route.9 rtable_add.9 rtlabel_id2name.9 \
-	rtrequest1.9 rwlock.9 sensor_attach.9 \
+	route.9 rt_ifa_add.9 rt_timer_add.9 rtalloc.9 rtable_add.9 \
+	rtlabel_id2name.9 rtrequest1.9 rwlock.9 sensor_attach.9 \
 	shutdownhook_establish.9 tsleep.9 spl.9 startuphook_establish.9 \
 	socreate.9 sosplice.9 style.9 syscall.9 systrace.9 sysctl_int.9 \
 	task_add.9 tc_init.9 time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 \
@@ -323,7 +323,7 @@ MLINKS+=rssadapt.9 ieee80211_rssadapt_choose.9 \
 	rssadapt.9 ieee80211_rssadapt_lower_rate.9 \
 	rssadapt.9 ieee80211_rssadapt_raise_rate.9 \
 	rssadapt.9 ieee80211_rssadapt_updatestats.9
-MLINKS+=route.9 rt_lookup.9 route.9 rtalloc1.9 route.9 rtfree.9 \
+MLINKS+=route.9 rt_lookup.9 \
 	route.9 rt_setgate.9 route.9 rtredirect.9 route.9 rtdeletemsg.9
 MLINKS+=rt_ifa_add.9 rt_ifa_del.9 rt_ifa_add.9 rt_ifa_addloop.9 \
 	rt_ifa_add.9 rt_ifa_delloop.9
@@ -332,6 +332,7 @@ MLINKS+=rt_timer_add.9 rt_timer_queue_create.9 \
 	rt_timer_add.9 rt_timer_queue_change.9 \
 	rt_timer_add.9 rt_timer_queue_destroy.9 \
 	rt_timer_add.9 rt_timer_remove_all.9
+MLINKS+=rtalloc.9 rtalloc_mpath.9 rtalloc.9 rtfree.9
 MLINKS+=rtable_add.9 rtable_exists.9 rtable_add.9 rtable_get.9 \
 	rtable_add.9 rtable_l2.9 rtable_add.9 rtable_l2set.9
 MLINKS+=rtlabel_id2name.9 rtlabel_name2id.9 \
diff --git a/share/man/man9/route.9 b/share/man/man9/route.9
index 3485df58e0a..51d11a84184 100644
--- a/share/man/man9/route.9
+++ b/share/man/man9/route.9
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: route.9,v 1.12 2014/10/14 10:56:10 mpi Exp $
+.\"     $OpenBSD: route.9,v 1.13 2014/11/01 21:45:54 mpi Exp $
 .\"
 .\" Copyright (c) 2011 Bret S. Lambert <blambert@openbsd.org>
 .\" All rights reserved.
@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: October 14 2014 $
+.Dd $Mdocdate: November 1 2014 $
 .Dt ROUTE 9
 .Os
 .Sh NAME
@@ -25,10 +25,6 @@
 .In net/route.h
 .Ft struct rtentry *
 .Fn rt_lookup "struct sockaddr *dst" "struct sockaddr *mask" "u_int tableid"
-.Ft struct rtentry *
-.Fn rtalloc1 "struct sockaddr *dst" "int flags" "u_int tableid"
-.Ft void
-.Fn rtfree "struct rtentry *rt"
 .Ft int
 .Fn rt_setgate "struct rtentry *rt0" "struct sockaddr *dst" \
 "struct sockaddr *gate" "u_int tableid"
@@ -82,10 +78,6 @@ from table
 and forward a notification message to all
 .Fa AF_ROUTE
 sockets.
-.It Fn rtfree "struct rtentry *rt"
-Release a reference to
-.Fa rt ,
-freeing it if the reference count drops to 0.
 .El
 .Sh RETURN VALUES
 .Fn rt_setgate
@@ -106,7 +98,7 @@ No routing entry for
 could be found.
 .It Bq Er ESRCH
 .Fa rt
-is a multipath route that conflicts with existing multipath route.
+is a multipath routing entry that conflicts with an existing one.
 .El
 .Sh SEE ALSO
 .Xr route 4 ,
diff --git a/share/man/man9/rtalloc.9 b/share/man/man9/rtalloc.9
new file mode 100644
index 00000000000..c57098c5466
--- /dev/null
+++ b/share/man/man9/rtalloc.9
@@ -0,0 +1,78 @@
+.\" $OpenBSD: rtalloc.9,v 1.1 2014/11/01 21:45:54 mpi Exp $
+.\"
+.\" Copyright (c) 2014 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: November 1 2014 $
+.Dt RTALLOC 9
+.Os
+.Sh NAME
+.Nm rtalloc, rtalloc_mpath, rtfree
+.Nd routing entries interface
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/socket.h
+.In net/route.h
+.Ft struct rtentry *
+.Fn rtalloc "struct sockaddr *dst" "int flags" "unsigned int rtableid"
+.Ft struct rtentry *
+.Fn rtalloc_mpath "struct sockaddr *dst" "uint32_t *src" "unsigned int rtableid"
+.Ft void
+.Fn rtfree "struct rtentry *rt"
+.Sh DESCRIPTION
+The
+.Fn rtalloc
+function looks up in the routing table specified by
+.Fa rtableid
+for an entry matching
+.Fa dst .
+The following
+.Fa flags
+can be specified:
+.Bl -tag -width RT_RESOLVE -offset indent
+.It Dv RT_REPORT
+Notify the routing sockets if the lookup fails.
+.It Dv RT_RESOLVE
+Allocate and return a cloned entry for
+.Fa dst
+if it does not exist and the lookup returned a cloning entry. 
+.El
+.Pp
+The
+.Fn rtalloc_mpath
+function does the same as
+.Fn rtalloc
+with the
+.Dv RT_REPORT
+and
+.Dv RT_RESOLVE 
+.Fa flags ,
+but selects a multipath routing entry corresponding to
+.Fa src
+when possible.
+.Pp
+The
+.Fn rtfree
+function releases a reference to the routing entry
+.Fa rt ,
+freeing it if the reference count drops to 0.
+.Sh CONTEXT
+.Fn rtalloc ,
+.Fn rtalloc_mpath ,
+and
+.Fn rtfree
+can be called during autoconf, from process context, or from interrupt context.
+.Sh SEE ALSO
+.Xr route 4 ,
+.Xr rtrequest1 9