- note that RTF_PRCLONING is obsoleted

- explain locking differencies between rtalloc(), rtalloc_ign(), rtalloc1()
  and rtfree(), RTFREE().

Reviewed by:	andre (1.5 months ago)
OK'd by:	ru

share/man/man9/rtalloc.9

@@ -27,13 +27,14 @@
 .\" SUCH DAMAGE.
 .\"
 .\" $FreeBSD$
-.Dd October 8, 1996
+.Dd October 7, 2004
 .Os
 .Dt RTALLOC 9
 .Sh NAME
 .Nm rtalloc ,
 .Nm rtalloc_ign ,
-.Nm rtalloc1
+.Nm rtalloc1 ,
+.Nm rtfree
 .Nd look up a route in the kernel routing table
 .Sh SYNOPSIS
 .In sys/types.h
@@ -45,6 +46,9 @@
 .Fn rtalloc_ign "struct route *ro" "u_long flags"
 .Ft "struct rtentry *"
 .Fn rtalloc1 "struct sockaddr *sa" "int report" "u_long flags"
+.Ft void
+.Fn rtfree "struct rt_entry *rt"
+.Fn RTFREE "struct rt_entry *rt"
 .Sh DESCRIPTION
 The kernel uses a radix tree structure to manage routes for the
 networking subsystem.
@@ -58,22 +62,21 @@ certain protocol\- and interface-specific actions to take place.
 .Pp
 When a route with the flag
 .Dv RTF_CLONING
-or
-.Dv RTF_PRCLONING
-is retrieved, and the action of those flags is not masked, the
+is retrieved, and the action of this flag is not masked, the
 .Nm
 facility automatically generates a new route using information in the
-old route as a template, and in the case of
-.Dv RTF_CLONING ,
+old route as a template, and
 sends an
 .Dv RTM_RESOLVE
 message to the appropriate interface-address route-management routine
 .Pq Fn ifa->ifa_rtrequest .
+This generated route is called
+.Em cloned ,
+and has
+.Dv RTF_WASCLONED
+flag set.
 .Dv RTF_PRCLONING
-routes are assumed to be managed by the protocol family and no
-resolution requests are made, but all routes generated by the cloning
-process retain a reference to the route from which they were
-generated.
+flag is obsoleted and thus ignored by facility.
 If the
 .Dv RTF_XRESOLVE
 flag is set, then the
@@ -95,6 +98,7 @@ struct route {
 	struct sockaddr ro_dst;
 	struct rtentry *ro_rt;
 };
+.Pp
 .Ed
 Thus, this function can only be used for address families which are
 smaller than the default
@@ -119,9 +123,7 @@ interface can be used when the default actions of
 .Fn rtalloc
 in the presence of the
 .Dv RTF_CLONING
-and
-.Dv RTF_PRCLONING
-flags are undesired.
+flag is undesired.
 The
 .Fa ro
 argument is the same as
@@ -130,10 +132,15 @@ but there is additionally a
 .Fa flags
 argument, which lists the flags in the route which are to be
 .Em ignored
-(ordinarily, one or both of
+(in most cases this is
 .Dv RTF_CLONING
-or
-.Dv RTF_PRCLONING ) .
+flag) .
+Both
+.Fn rtalloc
+and
+.Fn rtalloc_ign
+functions return an unlocked
+.Ft "struct rtentry" .
 .Pp
 The
 .Fn rtalloc1
@@ -166,11 +173,32 @@ The third argument,
 .Fa flags ,
 is a set of flags to ignore, as in
 .Fn rtalloc_ign .
+.Fn rtalloc1
+returns a locked
+.Ft "struct rtentry" .
+.Pp
+The
+.Fn rtfree
+function frees a locked route entry, e.g. previously allocated by
+.Fn rtalloc1 .
+.Pp
+.Fn RTFREE
+macro is used to free unlocked route entries, previously allocated by
+.Fn rtalloc
+or
+.Fn rtalloc_ign .
+The preferred usage is allocating a route using
+.Fn rtalloc
+or
+.Fn rtalloc_ign
+and freeing using
+.Fn RTFREE .
 .Sh RETURN VALUES
 The
-.Fn rtalloc
-and
+.Fn rtalloc ,
 .Fn rtalloc_ign
+and
+.Fn rtfree
 functions do not return a value.
 The
 .Fn rtalloc1