Add a man page for rtrequest1(9) splitted from route(9) with some

improvements.

ok sthen@

3 files changed, 149 insertions, 103 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 47aa08fcf34..a5810c2fc56 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.205 2014/03/21 10:44:42 mpi Exp $
+#	$OpenBSD: Makefile,v 1.206 2014/04/02 13:10:48 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.
@@ -25,8 +25,8 @@ MAN=	altq.9 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 \
-	route.9 rt_timer_add.9 rtable_add.9 rtlabel_id2name.9 rwlock.9 \
-	sensor_attach.9 \
+	route.9 rt_timer_add.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 \
@@ -310,11 +310,9 @@ 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 rtalloc.9 \
-	route.9 rtalloc_noclone.9 route.9 rtalloc1.9 \
-	route.9 rtfree.9 route.9 rtrequest1.9 \
-	route.9 rt_setgate.9 route.9 rtredirect.9 \
-	route.9 rtdeletemsg.9
+MLINKS+=route.9 rt_lookup.9 route.9 rtalloc.9 route.9 rtalloc_noclone.9 \
+	route.9 rtalloc1.9 route.9 rtfree.9 route.9 rt_setgate.9 \
+	route.9 rtredirect.9 route.9 rtdeletemsg.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+=rt_timer_add.9 rt_timer_queue_create.9 \
diff --git a/share/man/man9/route.9 b/share/man/man9/route.9
index 42e879d22c3..1a50a931ff8 100644
--- a/share/man/man9/route.9
+++ b/share/man/man9/route.9
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: route.9,v 1.9 2014/03/18 09:01:11 mpi Exp $
+.\"     $OpenBSD: route.9,v 1.10 2014/04/02 13:10:48 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: March 18 2014 $
+.Dd $Mdocdate: April 2 2014 $
 .Dt ROUTE 9
 .Os
 .Sh NAME
@@ -35,9 +35,6 @@
 .Fn rtfree "struct rtentry *rt"
 .Fn RTFREE "struct rtentry *rt"
 .Ft int
-.Fn rtrequest1 "int req" "struct rt_addrinfo *info" "u_int8_t prio" \
-"struct rtentry **ret_nrt" "u_int tableid"
-.Ft int
 .Fn rt_setgate "struct rtentry *rt0" "struct sockaddr *dst" \
 "struct sockaddr *gate" "u_int tableid"
 .Ft void
@@ -46,29 +43,6 @@
 "struct rtentry **rtp" "u_int rdomain"
 .Ft int
 .Fn rtdeletemsg "struct rtentry *rt" "u_int tableid"
-.Bd -literal
-struct rt_addrinfo {
-	int	rti_addrs;
-	struct	sockaddr *rti_info[RTAX_MAX];
-	int	rti_flags;
-	struct	ifaddr *rti_ifa;
-	struct	ifnet *rti_ifp;
-	struct	rt_msghdr *rti_rtm;
-	u_char	rti_mpls;
-};
-
-#define RTAX_DST	0	/* destination sockaddr present */
-#define RTAX_GATEWAY	1	/* gateway sockaddr present */
-#define RTAX_NETMASK	2	/* netmask sockaddr present */
-#define RTAX_IFP	4	/* interface name sockaddr present */
-#define RTAX_IFA	5	/* interface addr sockaddr present */
-#define RTAX_AUTHOR	6	/* sockaddr for author of redirect */
-#define RTAX_BRD	7	/* for NEWADDR, broadcast or p-p dest */
-#define RTAX_SRC	8	/* source sockaddr present */
-#define RTAX_SRCMASK	9	/* source netmask present */
-#define RTAX_LABEL	10	/* route label present */
-#define RTAX_MAX	11	/* size of array to allocate */
-.Ed
 .Sh DESCRIPTION
 Routing entries describe the routes to be taken by packets in a router.
 .Bl -tag -width Ds
@@ -79,30 +53,6 @@ with a mask of
 .Fa mask
 from table
 .Fa tableid .
-.It Fn rtrequest1 "int req" "struct rt_addrinfo *info" "u_int8_t prio" \
-"struct rtentry **ret_nrt" "u_int tableid"
-Perform the action specified in
-.Fa req
-on table
-.Fa tableid .
-.Fa req
-can be any of the following:
-.Bl -tag -width "RTM_RESOLVEXXX" -offset indent
-.It RTM_ADD
-.\" XXX Describe adding an entry.
-.It RTM_RESOLVE
-.\" XXX Describe resolving an entry.
-.It RTM_DELETE
-.\" XXX Describe deleting an entry.
-.El
-.Pp
-If
-.Fa ret_nrt
-is non-NULL, a pointer to the routing entry which satisfied the request is
-placed there.
-If
-.Fa prio
-is 0, a default priority based on the egress interface is used.
 .It Fn rt_setgate "struct rtentry *rt0" "struct sockaddr *dst" \
 "struct sockaddr *gate" "u_int tableid"
 Set the address of the gateway for routes described by
@@ -146,45 +96,6 @@ A macro which calls
 .Fn rtfree .
 .El
 .Sh RETURN VALUES
-.Fn rtrequest1
-may fail with:
-.Pp
-.Bl -tag -width Er -compact
-.It Bq Er EAFNOSUPPORT
-The protocol used by
-.Fa info
-is not supported in table with ID of
-.Fa tableid .
-.It Bq Er ESEARCH
-No routing entry corresponding to
-.Fa info
-could be found.
-.It Bq Er ESEARCH
-Multipath route with no gateway provided in
-.Fa info .
-.It Bq Er ESEARCH
-The routing entry could not be found in the routing table.
-.It Bq Er EINVAL
-.Fa req
-specified
-.Fa RTM_RESOLVE
-with a
-.Fa ret_nrt
-argument which does not point to a cloneable routing entry.
-.It Bq Er EEXIST
-Multipath route conflicts with existing multipath route.
-.It Bq Er EEXIST
-The route could not be entered into the routing table.
-.It Bq Er ENOMEM
-Space for MPLS protocol data could not be allocated.
-.It Bq Er ENOBUFS
-Space for a new routing entry could not be allocated.
-.It Bq Er ENETUNREACH
-An interface address corresponding to the route described by
-.Fa info
-could not be found.
-.El
-.Pp
 .Fn rt_setgate
 returns non-0 if it cannot allocate memory.
 .Pp
@@ -210,7 +121,5 @@ is a multipath route that conflicts with existing multipath route.
 .Xr route 8 ,
 .Xr rt_timer_add 9 ,
 .Xr rtable_add 9 ,
-.Xr rtlabel_id2name 9
-.Sh BUGS
-The current route entry reference counting code, while not incorrect, is also
-likely not correct either.
+.Xr rtlabel_id2name 9 ,
+.Xr rtrequest1 9
diff --git a/share/man/man9/rtrequest1.9 b/share/man/man9/rtrequest1.9
new file mode 100644
index 00000000000..f702131f41b
--- /dev/null
+++ b/share/man/man9/rtrequest1.9
@@ -0,0 +1,139 @@
+.\"     $OpenBSD: rtrequest1.9,v 1.1 2014/04/02 13:10:48 mpi Exp $
+.\"
+.\" Copyright (c) 2011 Bret S. Lambert <blambert@openbsd.org>
+.\" All rights reserved.
+.\"
+.\" 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: April 2 2014 $
+.Dt RTREQUEST1 9
+.Os
+.Sh NAME
+.Nm rtrequest1
+.Nd add or remove routes from a routing table
+.Sh SYNOPSIS
+.In net/route.h
+.Ft int
+.Fn rtrequest1 "int req" "struct rt_addrinfo *info" "u_int8_t prio" \
+"struct rtentry **rtp" "u_int rtableid"
+.Bd -literal
+struct rt_addrinfo {
+	int	rti_addrs;
+	struct	sockaddr *rti_info[RTAX_MAX];
+	int	rti_flags;
+	struct	ifaddr *rti_ifa;
+	struct	ifnet *rti_ifp;
+	struct	rt_msghdr *rti_rtm;
+	u_char	rti_mpls;
+};
+
+#define RTAX_DST	0	/* destination sockaddr present */
+#define RTAX_GATEWAY	1	/* gateway sockaddr present */
+#define RTAX_NETMASK	2	/* netmask sockaddr present */
+#define RTAX_IFP	4	/* interface name sockaddr present */
+#define RTAX_IFA	5	/* interface addr sockaddr present */
+#define RTAX_AUTHOR	6	/* sockaddr for author of redirect */
+#define RTAX_BRD	7	/* for NEWADDR, broadcast or p-p dest */
+#define RTAX_SRC	8	/* source sockaddr present */
+#define RTAX_SRCMASK	9	/* source netmask present */
+#define RTAX_LABEL	10	/* route label present */
+#define RTAX_MAX	11	/* size of array to allocate */
+.Ed
+.Sh DESCRIPTION
+The
+.Fn rtrequest1
+function is used to add or remove routes from a specific routing table.
+It takes the following arguments:
+.Bl -tag -width rtableid
+.It Fa req
+One of the following actions to perform:
+.Bl -tag -width RTM_RESOLVE -offset indent
+.It Dv RTM_ADD
+Add a route to a given routing table.
+.It Dv RTM_DELETE
+Remove a route from a given routing table.
+In case of a cloning route, all its children are deleted.
+.It Dv RTM_RESOLVE
+Add a cloned route, based on the parent cloning route pointed by
+.Fa rtp ,
+to a given routing table.
+.El
+.It Fa info
+Describes the route to add or remove.
+.It Fa prio
+Specifies the priority of the route described by
+.Fa info .
+If it is
+.Dv 0
+and the requested action is
+.Dv RTM_ADD
+then a default priority based on the priority of the associated
+interface is chosen.
+.It Fa rtp
+Points to the cloning route if the action is
+.Dv RTM_RESOLVE
+or, if the action is
+.Dv RTM_DELETE
+and it is non-NULL, a pointer to the removed route is placed there.
+In this case, the caller must take care of releasing the returned route by
+calling
+.Xr rtfree 9 .
+.It Fa rtableid
+The ID of the routing table to modify.
+.El
+.Sh CONTEXT
+.Fn rtrequest1
+can be called during autoconf, from process context, or from interrupt context.
+.Sh RETURN VALUES
+.Fn rtrequest1
+may fail with:
+.Pp
+.Bl -tag -width Er -compact
+.It Bq Er EAFNOSUPPORT
+The routing table with ID of
+.Fa rtableid
+does not exist or it does not support the protocol specified in
+.Fa info .
+.It Bq Er ESRCH
+No route corresponding to
+.Fa info
+could be found.
+.It Bq Er ESRCH
+Multipath route with no gateway provided in
+.Fa info .
+.It Bq Er ESRCH
+The route could not be found in the routing table of ID
+.Fa rtableid .
+specified
+.It Bq Er EINVAL
+The route pointed by
+.Fa rtp
+is not valid or does not point to a cloning route in the
+.Dv RTM_RESOLVE
+case.
+.It Bq Er EEXIST
+Multipath route conflicts with existing multipath route.
+.It Bq Er EEXIST
+The route could not be entered into the routing table.
+.It Bq Er ENOMEM
+Space for MPLS protocol data could not be allocated.
+.It Bq Er ENOBUFS
+Space for a new route could not be allocated.
+.It Bq Er ENETUNREACH
+An interface address corresponding to the route described by
+.Fa info
+could not be found.
+.El
+.Sh SEE ALSO
+.Xr rtable_get 9 ,
+.Xr rtfree 9