git: bc54f5f1cd5c - main - route(8): Add an example how to print the routing tables

[Rodney W. Grimes]

> On Wed, Apr 14, 2021 at 03:31:24AM -0700, Rodney W. Grimes wrote:
> > > On Tue, Apr 13, 2021 at 03:36:14AM -0700, Rodney W. Grimes wrote:
> > > > > The branch main has been updated by gbe (doc committer):
> > > > > 
> > > > > URL: https://cgit.FreeBSD.org/src/commit/?id=bc54f5f1cd5c01aa5f941234034839fb0b8f54ed
> > > > > 
> > > > > commit bc54f5f1cd5c01aa5f941234034839fb0b8f54ed
> > > > > Author:     Gordon Bergling <gbe at FreeBSD.org>
> > > > > AuthorDate: 2021-04-13 04:44:04 +0000
> > > > > Commit:     Gordon Bergling <gbe at FreeBSD.org>
> > > > > CommitDate: 2021-04-13 04:45:22 +0000
> > > > > 
> > > > >     route(8): Add an example how to print the routing tables
> > > > >     
> > > > >     The manual page currently doesn't show an example how to print
> > > > >     the routing table, so add one and .Xr netstat while here.
> > > > 
> > > > Because the route command does not print the routing table.
> > > > 
> > > > Manual pages should have examples of how to use that command,
> > > > not examples of how to do associated things that are done
> > > > using another command.
> > > > 
> > > > The add of xref to netstat is long overdue.
> > > 
> > > I know that examples in man pages should be specific for the command
> > > the man page is for, but I think we could make an exception for netstat at
> > > this point, because many people, who are looking for such an information
> > > are coming from the Windows world, where the route command has a print
> > > option.
> > 
> > Perhaps add in description of "route get":
> > 	To print the complete routing table refer to the netstat(8) -r flag.
> 
> I am currently working on a 'route show' implementation for FreeBSD. NetBSD and
> OpenBSD have this functionality already implemented. I would update the man page
> after I have finished the implementation and the review process through phabricator.

Be aware that the netstat -r implementation has serious issues
when your dealing with full view route tables.  The size of
that table can change rapid enough that the cycling of calls
to try to guess a proper chunk of memory to allocate is a
race condition.

See:
	https://reviews.freebsd.org/D15488
for some discussions and attempts at solutions.

> --Gordon
> 
> > > > >     PR:             231579
> > > > >     Reported by:    Pekka J?rvinen <pekka dot jarvinen at gmail dot com>
> > > > >     Reviewed by:    debdrup
> > > > >     MFC after:      5 days
> > > > >     Differential Revision:  https://reviews.freebsd.org/D29702
> > > > > ---
> > > > >  sbin/route/route.8 | 7 ++++++-
> > > > >  1 file changed, 6 insertions(+), 1 deletion(-)
> > > > > 
> > > > > diff --git a/sbin/route/route.8 b/sbin/route/route.8
> > > > > index 6f34795ce883..c353bfb73d62 100644
> > > > > --- a/sbin/route/route.8
> > > > > +++ b/sbin/route/route.8
> > > > > @@ -28,7 +28,7 @@
> > > > >  .\"     @(#)route.8	8.3 (Berkeley) 3/19/94
> > > > >  .\" $FreeBSD$
> > > > >  .\"
> > > > > -.Dd January 9, 2019
> > > > > +.Dd April 11, 2021
> > > > >  .Dt ROUTE 8
> > > > >  .Os
> > > > >  .Sh NAME
> > > > > @@ -453,6 +453,10 @@ Delete a static route from the routing table:
> > > > >  Remove all routes from the routing table:
> > > > >  .Pp
> > > > >  .Dl route flush
> > > > > +.Pp
> > > > > +List all routing tables:
> > > > > +.Pp
> > > > > +.Dl netstat -r
> > > > >  .Sh DIAGNOSTICS
> > > > >  .Bl -diag
> > > > >  .It "add [host \&| network ] %s: gateway %s flags %x"
> > > > > @@ -493,6 +497,7 @@ The next-hop gateway should be reachable through a different route.
> > > > >  .El
> > > > >  .Sh SEE ALSO
> > > > >  .\".Xr esis 4 ,
> > > > > +.Xr netstat 1 ,
> > > > >  .Xr netintro 4 ,
> > > > >  .Xr route 4 ,
> > > > >  .Xr arp 8 ,
> > > > > 
> > > > 
> > > > -- 
> > > > Rod Grimes                                                 rgrimes at freebsd.org
> > > 
> > > -- 
> > > 
> > 
> > -- 
> > Rod Grimes                                                 rgrimes at freebsd.org
> 
> -- 
> 

-- 
Rod Grimes                                                 rgrimes at freebsd.org