rtable_walk(9)

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

rtable_walk(9)

Martin Pieuchot
Document this complex function.  Any wording suggestion?

Index: Makefile
===================================================================
RCS file: /cvs/src/share/man/man9/Makefile,v
retrieving revision 1.295
diff -u -p -r1.295 Makefile
--- Makefile 21 Jun 2019 09:39:48 -0000 1.295
+++ Makefile 11 Jul 2019 20:16:54 -0000
@@ -29,7 +29,8 @@ MAN= aml_evalnode.9 atomic_add_int.9 ato
  pmap.9 pool.9 pool_cache_init.9 ppsratecheck.9 printf.9 psignal.9 \
  RBT_INIT.9 \
  radio.9 arc4random.9 rasops.9 ratecheck.9 refcnt_init.9 resettodr.9 \
- rssadapt.9 route.9 rt_ifa_add.9 rt_timer_add.9 rtalloc.9 rtable_add.9 \
+ rssadapt.9 route.9 rt_ifa_add.9 rt_timer_add.9 \
+ rtalloc.9 rtable_add.9 rtable_walk.9 \
  rtlabel_id2name.9 rtrequest.9 rwlock.9 SRPL_EMPTY_LOCKED.9 SipHash24.9 \
  sensor_attach.9 sigio_init.9 \
  SMR_LIST_INIT.9 SMR_PTR_GET.9 smr_call.9 \
Index: rtable_walk.9
===================================================================
RCS file: rtable_walk.9
diff -N rtable_walk.9
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ rtable_walk.9 11 Jul 2019 20:16:23 -0000
@@ -0,0 +1,68 @@
+.\"     $OpenBSD$
+.\"
+.\" Copyright (c) 2019 Martin Pieuchot <[hidden email]>
+.\"
+.\" 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$
+.Dt RTABLE_WALK 9
+.Os
+.Sh NAME
+.Nm rtable_walk
+.Nd iterate over a routing table
+.Sh SYNOPSIS
+.In net/rtable.h
+.Ft int
+.Fn rtable_walk "unsigned int rtableid" "sa_family_t af" \
+"struct rtentry **prt" "int (*func)(struct rtentry *, void *, unsigned int)" \
+"void *arg"
+.Sh DESCRIPTION
+The
+.Fn rtable_walk
+function iterates over the routing table
+.Fa rtableid
+and applies
+.Fa func
+to all entries of address family
+.Fa af .
+.Pp
+The iteration is interrupted as soon as
+.Fa func
+returns a non-zero value.
+If
+.Fa prt
+is non-null when the iteration is interrupted, it is set to the current
+routing entry.
+In that case
+.Fn rtfree
+must be called on the routing entry pointed by
+.Fa prt .
+.Sh CONTEXT
+.Fn rtable_walk
+can be called during autoconf or from process context.
+.Sh RETURN VALUES
+.Fn rtable_walk
+returns any non-zero value returned by
+.Fa func .
+It may also fail with:
+.Pp
+.Bl -tag -width Er -compact
+.It Bq Er EAFNOSUPPORT
+A routing table with ID of
+.Fa rtableid
+and address family of
+.Fa af
+doesn't exist.
+.El
+.Sh SEE ALSO
+.Xr rtfree 9

Reply | Threaded
Open this post in threaded view
|

Re: rtable_walk(9)

Jason McIntyre-2
On Thu, Jul 11, 2019 at 05:18:41PM -0300, Martin Pieuchot wrote:
> Document this complex function.  Any wording suggestion?
>

hi.

the page reads fine. i have one tweak inline. oh, and you might want to
cross Xr back from rtfree.

> Index: Makefile
> ===================================================================
> RCS file: /cvs/src/share/man/man9/Makefile,v
> retrieving revision 1.295
> diff -u -p -r1.295 Makefile
> --- Makefile 21 Jun 2019 09:39:48 -0000 1.295
> +++ Makefile 11 Jul 2019 20:16:54 -0000
> @@ -29,7 +29,8 @@ MAN= aml_evalnode.9 atomic_add_int.9 ato
>   pmap.9 pool.9 pool_cache_init.9 ppsratecheck.9 printf.9 psignal.9 \
>   RBT_INIT.9 \
>   radio.9 arc4random.9 rasops.9 ratecheck.9 refcnt_init.9 resettodr.9 \
> - rssadapt.9 route.9 rt_ifa_add.9 rt_timer_add.9 rtalloc.9 rtable_add.9 \
> + rssadapt.9 route.9 rt_ifa_add.9 rt_timer_add.9 \
> + rtalloc.9 rtable_add.9 rtable_walk.9 \
>   rtlabel_id2name.9 rtrequest.9 rwlock.9 SRPL_EMPTY_LOCKED.9 SipHash24.9 \
>   sensor_attach.9 sigio_init.9 \
>   SMR_LIST_INIT.9 SMR_PTR_GET.9 smr_call.9 \
> Index: rtable_walk.9
> ===================================================================
> RCS file: rtable_walk.9
> diff -N rtable_walk.9
> --- /dev/null 1 Jan 1970 00:00:00 -0000
> +++ rtable_walk.9 11 Jul 2019 20:16:23 -0000
> @@ -0,0 +1,68 @@
> +.\"     $OpenBSD$
> +.\"
> +.\" Copyright (c) 2019 Martin Pieuchot <[hidden email]>
> +.\"
> +.\" 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$
> +.Dt RTABLE_WALK 9
> +.Os
> +.Sh NAME
> +.Nm rtable_walk
> +.Nd iterate over a routing table
> +.Sh SYNOPSIS
> +.In net/rtable.h
> +.Ft int
> +.Fn rtable_walk "unsigned int rtableid" "sa_family_t af" \
> +"struct rtentry **prt" "int (*func)(struct rtentry *, void *, unsigned int)" \
> +"void *arg"
> +.Sh DESCRIPTION
> +The
> +.Fn rtable_walk
> +function iterates over the routing table
> +.Fa rtableid
> +and applies
> +.Fa func
> +to all entries of address family
> +.Fa af .
> +.Pp
> +The iteration is interrupted as soon as
> +.Fa func
> +returns a non-zero value.
> +If
> +.Fa prt
> +is non-null when the iteration is interrupted, it is set to the current
> +routing entry.
> +In that case
> +.Fn rtfree
> +must be called on the routing entry pointed by

pointed *to* i guess.
jmc

> +.Fa prt .
> +.Sh CONTEXT
> +.Fn rtable_walk
> +can be called during autoconf or from process context.
> +.Sh RETURN VALUES
> +.Fn rtable_walk
> +returns any non-zero value returned by
> +.Fa func .
> +It may also fail with:
> +.Pp
> +.Bl -tag -width Er -compact
> +.It Bq Er EAFNOSUPPORT
> +A routing table with ID of
> +.Fa rtableid
> +and address family of
> +.Fa af
> +doesn't exist.
> +.El
> +.Sh SEE ALSO
> +.Xr rtfree 9
>

Reply | Threaded
Open this post in threaded view
|

Re: rtable_walk(9)

Ingo Schwarze
In reply to this post by Martin Pieuchot
Hi Martin,

Martin Pieuchot wrote on Thu, Jul 11, 2019 at 05:18:41PM -0300:

> Index: rtable_walk.9
> ===================================================================
> RCS file: rtable_walk.9
> diff -N rtable_walk.9
> --- /dev/null 1 Jan 1970 00:00:00 -0000
> +++ rtable_walk.9 11 Jul 2019 20:16:23 -0000
> @@ -0,0 +1,68 @@
> +.\"     $OpenBSD$
> +.\"
> +.\" Copyright (c) 2019 Martin Pieuchot <[hidden email]>
> +.\"
> +.\" 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$
> +.Dt RTABLE_WALK 9
> +.Os
> +.Sh NAME
> +.Nm rtable_walk
> +.Nd iterate over a routing table
> +.Sh SYNOPSIS
> +.In net/rtable.h
> +.Ft int
> +.Fn rtable_walk "unsigned int rtableid" "sa_family_t af" \
> +"struct rtentry **prt" "int (*func)(struct rtentry *, void *, unsigned int)" \
> +"void *arg"

While this isn't incorrect, i suggest the more readable

.Ft int
.Fo rtable_walk
.Fa "unsigned int rtableid"
.Fa "sa_family_t af"
.Fa "struct rtentry **prt"
.Fa "int (*func)(struct rtentry *, void *, unsigned int)"
.Fa "void *arg"
.Fc

for functions with long arguments or with more than one or two arguments.

> +.Sh DESCRIPTION
> +The
> +.Fn rtable_walk
> +function iterates over the routing table
> +.Fa rtableid
> +and applies
> +.Fa func
> +to all entries of address family
> +.Fa af .
> +.Pp
> +The iteration is interrupted as soon as
> +.Fa func
> +returns a non-zero value.
> +If
> +.Fa prt
> +is non-null

Please consider the more usual form:

is not
.Dv NULL

These are not objections but merely suggestions.

Yours,
  Ingo

> when the iteration is interrupted, it is set to the current
> +routing entry.
> +In that case
> +.Fn rtfree
> +must be called on the routing entry pointed by
> +.Fa prt .
> +.Sh CONTEXT
> +.Fn rtable_walk
> +can be called during autoconf or from process context.
> +.Sh RETURN VALUES
> +.Fn rtable_walk
> +returns any non-zero value returned by
> +.Fa func .
> +It may also fail with:
> +.Pp
> +.Bl -tag -width Er -compact
> +.It Bq Er EAFNOSUPPORT
> +A routing table with ID of
> +.Fa rtableid
> +and address family of
> +.Fa af
> +doesn't exist.
> +.El
> +.Sh SEE ALSO
> +.Xr rtfree 9