Re: Document errno for ober_read_elements

2020-09-03 Thread Jason McIntyre
On Thu, Sep 03, 2020 at 09:25:11PM +0200, Theo Buehler wrote:
> On Thu, Sep 03, 2020 at 08:50:39PM +0200, Martijn van Duren wrote:
> > So here's my attempt at documenting errno for ober_read_elements.
> > 
> 
> Two small things below, otherwise this looks correct to me.
> 
> > martijn@
> > 
> > Index: ober_read_elements.3
> > ===
> > RCS file: /cvs/src/lib/libutil/ober_read_elements.3,v
> > retrieving revision 1.1
> > diff -u -p -r1.1 ober_read_elements.3
> > --- ober_read_elements.324 Oct 2019 12:39:26 -  1.1
> > +++ ober_read_elements.33 Sep 2020 18:48:56 -
> > @@ -142,9 +142,10 @@ frees any dynamically allocated storage 
> >  .Fn ober_read_elements
> >  returns a pointer to a fully populated list of one or more
> >  .Vt ber_element
> > -structures or
> > -.Dv NULL
> > -on a type mismatch or read error.
> > +structures.
> > +Otherwise \-1 is returned and the global variable
> > +.Va errno
> > +is set to indicate the error.
> >  .Pp
> >  .Fn ober_get_writebuf
> >  returns the number of bytes contained within the buffer
> > @@ -155,7 +156,30 @@ or \-1 on failure.
> >  returns the number of bytes written.
> >  Otherwise \-1 is returned and the global variable
> >  .Va errno
> > -is set to indicate the error.
> > +is set to
> > +.Er ENOMEM
> 
> .Er ENOMEM .
> 
> 
> > +to indicate the error.
> 
> drop this (cf malloc(3)).
> 
> > +.Sh ERRORS
> > +.Fn ober_read_elements
> > +will fail if:
> > +.Bl -tag -width Er
> > +.It Bq Er ENOMEM
> > +No memory was available to create the full
> > +.Vt ber_element
> > +structure list.
> > +.It Bq Er ENOBUFS
> > +.Fn ober_read_elements
> > +was called before calling
> > +.Fn ober_set_readbuf .
> > +.It Bq Er ECANCELED
> > +.Fa buf
> > +does not contain enough data to complete the unpacking.
> > +.It Bq Er EINVAL
> > +.Fa buf
> > +does not contain a valid BER data structure.
> > +.It Bq Er ERANGE
> > +One of the values in the structure is larger then the library can unpack.
> 
> then -> than
> 
> I am unsure wether this is correct/idiomatic English. I don't have a
> better suggestion. I would wait for jmc :)
> 

well, i just sent an ok and failed even to spot this typo, so maybe
don;t wait for me ;)

the typo fix is correct of course, and it reads ok to me.
jmc

> > +.El
> >  .Sh SEE ALSO
> >  .Xr read 2 ,
> >  .Xr recv 2 ,
> > 
> 



Re: Document errno for ober_read_elements

2020-09-03 Thread Theo Buehler
On Thu, Sep 03, 2020 at 08:50:39PM +0200, Martijn van Duren wrote:
> So here's my attempt at documenting errno for ober_read_elements.
> 

Two small things below, otherwise this looks correct to me.

> martijn@
> 
> Index: ober_read_elements.3
> ===
> RCS file: /cvs/src/lib/libutil/ober_read_elements.3,v
> retrieving revision 1.1
> diff -u -p -r1.1 ober_read_elements.3
> --- ober_read_elements.3  24 Oct 2019 12:39:26 -  1.1
> +++ ober_read_elements.3  3 Sep 2020 18:48:56 -
> @@ -142,9 +142,10 @@ frees any dynamically allocated storage 
>  .Fn ober_read_elements
>  returns a pointer to a fully populated list of one or more
>  .Vt ber_element
> -structures or
> -.Dv NULL
> -on a type mismatch or read error.
> +structures.
> +Otherwise \-1 is returned and the global variable
> +.Va errno
> +is set to indicate the error.
>  .Pp
>  .Fn ober_get_writebuf
>  returns the number of bytes contained within the buffer
> @@ -155,7 +156,30 @@ or \-1 on failure.
>  returns the number of bytes written.
>  Otherwise \-1 is returned and the global variable
>  .Va errno
> -is set to indicate the error.
> +is set to
> +.Er ENOMEM

.Er ENOMEM .


> +to indicate the error.

drop this (cf malloc(3)).

> +.Sh ERRORS
> +.Fn ober_read_elements
> +will fail if:
> +.Bl -tag -width Er
> +.It Bq Er ENOMEM
> +No memory was available to create the full
> +.Vt ber_element
> +structure list.
> +.It Bq Er ENOBUFS
> +.Fn ober_read_elements
> +was called before calling
> +.Fn ober_set_readbuf .
> +.It Bq Er ECANCELED
> +.Fa buf
> +does not contain enough data to complete the unpacking.
> +.It Bq Er EINVAL
> +.Fa buf
> +does not contain a valid BER data structure.
> +.It Bq Er ERANGE
> +One of the values in the structure is larger then the library can unpack.

then -> than

I am unsure wether this is correct/idiomatic English. I don't have a
better suggestion. I would wait for jmc :)

> +.El
>  .Sh SEE ALSO
>  .Xr read 2 ,
>  .Xr recv 2 ,
> 



Document errno for ober_read_elements

2020-09-03 Thread Martijn van Duren
So here's my attempt at documenting errno for ober_read_elements.

martijn@

Index: ober_read_elements.3
===
RCS file: /cvs/src/lib/libutil/ober_read_elements.3,v
retrieving revision 1.1
diff -u -p -r1.1 ober_read_elements.3
--- ober_read_elements.324 Oct 2019 12:39:26 -  1.1
+++ ober_read_elements.33 Sep 2020 18:48:56 -
@@ -142,9 +142,10 @@ frees any dynamically allocated storage 
 .Fn ober_read_elements
 returns a pointer to a fully populated list of one or more
 .Vt ber_element
-structures or
-.Dv NULL
-on a type mismatch or read error.
+structures.
+Otherwise \-1 is returned and the global variable
+.Va errno
+is set to indicate the error.
 .Pp
 .Fn ober_get_writebuf
 returns the number of bytes contained within the buffer
@@ -155,7 +156,30 @@ or \-1 on failure.
 returns the number of bytes written.
 Otherwise \-1 is returned and the global variable
 .Va errno
-is set to indicate the error.
+is set to
+.Er ENOMEM
+to indicate the error.
+.Sh ERRORS
+.Fn ober_read_elements
+will fail if:
+.Bl -tag -width Er
+.It Bq Er ENOMEM
+No memory was available to create the full
+.Vt ber_element
+structure list.
+.It Bq Er ENOBUFS
+.Fn ober_read_elements
+was called before calling
+.Fn ober_set_readbuf .
+.It Bq Er ECANCELED
+.Fa buf
+does not contain enough data to complete the unpacking.
+.It Bq Er EINVAL
+.Fa buf
+does not contain a valid BER data structure.
+.It Bq Er ERANGE
+One of the values in the structure is larger then the library can unpack.
+.El
 .Sh SEE ALSO
 .Xr read 2 ,
 .Xr recv 2 ,