Re: CVS commit: src/lib/libutil

[Valery Ushakov]

On Mon, Apr 08, 2024 at 23:31:16 +0200, Roland Illig wrote:

> Am 08.04.2024 um 21:18 schrieb Valery Ushakov:
> >   "=\017FIFTEEN\0"
> >
> > with its result a few lines below that has:
> >
> >   BURST=0xf=FIFTEEN
> 
> Thank you for explaining this example. I had a gut feeling that there
> would be some hidden correlation between some octal/hexadecimal
> combinations, but I couldn't name it. Indeed, if the number base for
> output is hexadecimal, the field comparisons should be done in
> hexadecimal as well.
> 
> I adjusted the description and examples in the manual page accordingly.

Thanks!  My unscientific impression is that snprintb(3) was not very
popular and its uses sometimes are a bit of a cargo-cult, so existing
use cases have to be taken with a grain of salt and don't necessarily
represent good style.  This is why improving the docs with good
examples is important, imho.


-uwe

Re: CVS commit: src/lib/libutil

[Roland Illig]

Am 08.04.2024 um 21:18 schrieb Valery Ushakov:
>   "=\017FIFTEEN\0"
>
> with its result a few lines below that has:
>
>   BURST=0xf=FIFTEEN

Thank you for explaining this example. I had a gut feeling that there
would be some hidden correlation between some octal/hexadecimal
combinations, but I couldn't name it. Indeed, if the number base for
output is hexadecimal, the field comparisons should be done in
hexadecimal as well.

I adjusted the description and examples in the manual page accordingly.

Roland

Re: CVS commit: src/lib/libutil

[Valery Ushakov]

On Mon, Apr 08, 2024 at 20:21:07 +0200, Roland Illig wrote:

> I didn't eradicate _all_ hexadecimal examples, I just made each example
> use only one number base, not mix them both. There are both octal and
> hexadecimal examples in the manual page.

That's not what "prefer octal in examples" conveys.

I would also say that source code that says

  "=\x0f" "FIFTEEN\0"

aligns much better than

  "=\017FIFTEEN\0"

with its result a few lines below that has:

  BURST=0xf=FIFTEEN


-uwe

Re: CVS commit: src/lib/libutil

[Roland Illig]

Am 08.04.2024 um 03:24 schrieb Valery Ushakov:
> On Sun, Apr 07, 2024 at 14:28:27 +, Roland Illig wrote:
>
>> Log Message:
>> snprintb.3: clean up formatting and wording, prefer octal in examples
>>
>> Using hexadecimal character escapes requires separate string literals if
>> the description starts with one of the letters A-F; octal character
>> escapes have at most 3 digits, reducing ambiguity.
>
> 70s are over, very few people speak octal fluently.  If anything, the
> man page should highlight the potential snag.  Besides, separate
> literal for the name is good for readability anyway.

When I looked through the NetBSD tree exploring the current usage, I
found that a significant majority uses octal instead of hexadecimal. I
don't know the exact reasons for this, it might be due to existing
practice in the 1990s, to avoid splitting the bit position and the
description to separate string literals, to be able to easily split the
bit position into the byte and the bit portion mentally, or maybe
something entirely different.

While your claim that "very few people speak octal fluently" may be true
for programmers in general, I expect those using the snprintb function
to be more fluent than others. Of course, I saw cases where "\040" was
followed by "\039", just as I saw cases of "\x0fFIELD". Lint now warns
in both these cases.

Regarding the separate literals, I didn't see them in wide use up to
now. Existing code seems to focus more on compressing the source code
into as few lines as possible rather than making it easily readable. I
agree that separate string literals are more readable, and I converted
the example that uses hexadecimal escapes to this style.

I didn't eradicate _all_ hexadecimal examples, I just made each example
use only one number base, not mix them both. There are both octal and
hexadecimal examples in the manual page.

Roland

Re: CVS commit: src/lib/libutil

[Valery Ushakov]

On Sun, Apr 07, 2024 at 14:28:27 +, Roland Illig wrote:

> Log Message:
> snprintb.3: clean up formatting and wording, prefer octal in examples
> 
> Using hexadecimal character escapes requires separate string literals if
> the description starts with one of the letters A-F; octal character
> escapes have at most 3 digits, reducing ambiguity.

70s are over, very few people speak octal fluently.  If anything, the
man page should highlight the potential snag.  Besides, separate
literal for the name is good for readability anyway.

Please, revert.

-uwe

Re: CVS commit: src/lib/libutil

[Valery Ushakov]

On Sun, Jan 21, 2024 at 21:31:23 +, Roland Illig wrote:

> and also didn't make it clear that a few bits were omitted from
> having descriptions.

I dislike this part.  It's internally inconsistent as it doesn't add
the placeholders for the low bits; and in many real-life scenarios
there will be *lots* of gaps in the defined bits, so implying in the
man page that the placeholders are good style just places the people
in a situation where they have to make the sensible thing, but go
against the style suggested in the man page.  I don't think that's
helpful.

Please, can we remove the placeholders from this example?

-uwe

Re: CVS commit: src/lib/libutil

[Robert Elz]

Date:Mon, 7 Dec 2015 15:55:49 -0500
From:"Christos Zoulas" 
Message-ID:  <20151207205549.4f6c...@cvs.netbsd.org>

  | Modified Files:
  | src/lib/libutil: parsedate.3 parsedate.y
  | 

The change below got missed from the parsedate.3 update.

I assume you decided to leave out the bit about difference
between midnight tues and tues midnight -- that's fine, most
of what the semantics of parsedate has are unspecified.

But this one is a real bug...

kre


--- parsedate.3 2015-12-08 18:43:53.0 +0700
+++ parsedate.3.keep2015-12-07 05:23:38.0 +0700
@@ -198,11 +198,11 @@
 .Dv zp5 (+0500) ,
 .Dv ist (+0550) ,
 .Dv zp6 (+0600) ,
-.Dv wast (+0700) ,
-.Dv wadt (+0800) ,
-.Dv awst (+0700) ,
-.Dv awdt (+0800) ,
 .Dv ict (+0700) ,
+.Dv wast (+0800) ,
+.Dv wadt (+0900) ,
+.Dv awst (+0800) ,
+.Dv awdt (+0900) ,
 .Dv cct (+0800) ,
 .Dv sgt (+0800) ,
 .Dv hkt (+0800) ,

Re: CVS commit: src/lib/libutil

[David Laight]

On Wed, Aug 07, 2013 at 10:51:59PM +, Paul Goyette wrote:
 Module Name:  src
 Committed By: pgoyette
 Date: Wed Aug  7 22:51:59 UTC 2013
 
 Modified Files:
   src/lib/libutil: snprintb.3
 
 Log Message:
 Add an example using snprintb_m()
 
 Replace \*[Gt] and \*[Lt] with the simple characters  and  (OK wiz)
 
 XXX Note that the examples currently do not compile with GCC!  The hex
 XXX character sequences such as \x10CACHE are being parsed as longer
 XXX than 2-hex-digit strings!

I would change all the examples to use concatenated strings.
As well as avoiding the above problem it makes them much, much, much
easier to read.

I remember changing some of the source files to split the strings.

David

-- 
David Laight: da...@l8s.co.uk

Re: CVS commit: src/lib/libutil

[Paul Goyette]

Module Name:src
Committed By:   pgoyette
Date:   Wed Aug  7 22:51:59 UTC 2013

Modified Files:
src/lib/libutil: snprintb.3

Log Message:
Add an example using snprintb_m()

Replace \*[Gt] and \*[Lt] with the simple characters  and  (OK wiz)

XXX Note that the examples currently do not compile with GCC!  The hex
XXX character sequences such as \x10CACHE are being parsed as longer
XXX than 2-hex-digit strings!


Ah, this is gcc bug # 33167

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=33167

I will update the example code shortly in the manner specified in the bug 
audit trail.




-
| Paul Goyette | PGP Key fingerprint: | E-mail addresses:   |
| Customer Service | FA29 0E3B 35AF E8AE 6651 | paul at whooppee.com|
| Network Engineer | 0786 F758 55DE 53BA 7731 | pgoyette at juniper.net |
| Kernel Developer |  | pgoyette at netbsd.org  |
-

Re: CVS commit: src/lib/libutil

[Valery Ushakov]

On Wed, Aug 07, 2013 at 16:17:01 -0700, Paul Goyette wrote:

 Module Name:src
 Committed By:   pgoyette
 Date:   Wed Aug  7 22:51:59 UTC 2013
 
 Modified Files:
 src/lib/libutil: snprintb.3
 
 Log Message:
 Add an example using snprintb_m()
 
 Replace \*[Gt] and \*[Lt] with the simple characters  and  (OK wiz)
 
 XXX Note that the examples currently do not compile with GCC!  The hex
 XXX character sequences such as \x10CACHE are being parsed as longer
 XXX than 2-hex-digit strings!
 
 Ah, this is gcc bug # 33167
 
 http://gcc.gnu.org/bugzilla/show_bug.cgi?id=33167
 
 I will update the example code shortly in the manner specified in the bug 
 audit trail.

This is not a bug, as the audit trail mentions.  Relevant passages
from the standard follow:

   6.4.4.4  Character constants

   [#14] EXAMPLE 3 Even if eight bits are used for objects that
   have  type  char,  the  construction  '\x123'  specifies  an
   integer  character  constant  containing only one character,
   since a hexadecimal escape sequence is terminated only by  a
   non-hexadecimal  character. ...

   6.4.5  String literals

   [#3]  The  same  considerations apply to each element of the
   sequence in a character string  literal  or  a  wide  string
   literal  as if it were in an integer character constant or a
   wide character constant, ...

   [#7]   EXAMPLE  This   pair  of  adjacent  character  string
   literals

   \x12 3

   produces a single character string  literal  containing  the
   two  characters  whose  values  are  '\x12' and '3', because
   escape sequences are converted into single  members  of  the
   execution  character  set  just  prior  to  adjacent  string
   literal concatenation.

Adding a caveat to the man page about being careful with \x might be a
good idea.

-uwe

Re: CVS commit: src/lib/libutil

[Christos Zoulas]

In article 20130621081825.11fd...@cvs.netbsd.org,
Thomas Klausner source-changes-d@NetBSD.org wrote:
-=-=-=-=-=-

Module Name:   src
Committed By:  wiz
Date:  Fri Jun 21 08:18:25 UTC 2013

Modified Files:
   src/lib/libutil: login_cap.3

Log Message:
Punctuation nit.
(Shouldn't the whole line be .Dl or .Bl -literal instead?)

Yes, that would be better.

christos

Re: CVS commit: src/lib/libutil

[David Laight]

On Mon, Dec 31, 2012 at 02:59:13AM +0100, Joerg Sonnenberger wrote:
 On Sun, Dec 30, 2012 at 05:36:00PM +, David A. Holland wrote:
  Module Name:src
  Committed By:   dholland
  Date:   Sun Dec 30 17:36:00 UTC 2012
  
  Modified Files:
  src/lib/libutil: efun.c
  
  Log Message:
  If malloc, calloc, or realloc returns NULL when a size of 0 was
  requested, which is allowed by pertinent standards, honor it instead
  of bombing.
  
  Do not do this for calloc(x, y) where x != 0  y != 0 but x*y == 0;
  in that case bomb.
 
 The commit message is misleading. We expect calloc(x,y) to return NULL
 if x!=0  y!=0  x*y==0.

I've never quite understood why calloc() was ever defined with 2
parameters.
The only time it can be different (and valid) from a naiive multiply
is when the multiply is done as 'int' on a system where size_t  int.

I'd have thought calloc() should be required to check that the
multiply doesn't overflow - but that ought (probably) require a different
errno than ENOMEM.

Certainly checking for multiply overflow would seem better than
checking for the product being zero.
Unfortunately that check tends to need a divide - although some
simple range checks will avoid that in most cases.

David

-- 
David Laight: da...@l8s.co.uk

Re: CVS commit: src/lib/libutil

[David Holland]

On Mon, Dec 31, 2012 at 10:21:09AM +, David Laight wrote:
Modified Files:
 src/lib/libutil: efun.c

Log Message:
If malloc, calloc, or realloc returns NULL when a size of 0 was
requested, which is allowed by pertinent standards, honor it instead
of bombing.

Do not do this for calloc(x, y) where x != 0  y != 0 but x*y == 0;
in that case bomb.
   
   The commit message is misleading. We expect calloc(x,y) to return NULL
   if x!=0  y!=0  x*y==0.
  
  I've never quite understood why calloc() was ever defined with 2
  parameters.

Me either.

  The only time it can be different (and valid) from a naiive multiply
  is when the multiply is done as 'int' on a system where size_t  int.

It does mean that the overflow test is centralized instead of being
replicated at every allocation site, which has its virtues.

  I'd have thought calloc() should be required to check that the
  multiply doesn't overflow - but that ought (probably) require a different
  errno than ENOMEM.

This is not explicitly stated in C99, but from the wording it is
certainly *allowed* to check, and one could construct a reasonable
argument that it's required to.

  Certainly checking for multiply overflow would seem better than
  checking for the product being zero.

Yes. But, you know, I didn't change calloc, I changed ecalloc. The
question is when a NULL return is an error. It is not an error if a
size of zero is requested, but it is on overflow. A size of zero is
requested only if one or both of the arguments is zero, *not* if the
product is zero. Hence the logic I described.

TBH, I don't understand why this is apparently confusing.

-- 
David A. Holland
dholl...@netbsd.org

Re: CVS commit: src/lib/libutil

[Joerg Sonnenberger]

On Sun, Dec 30, 2012 at 05:36:00PM +, David A. Holland wrote:
 Module Name:  src
 Committed By: dholland
 Date: Sun Dec 30 17:36:00 UTC 2012
 
 Modified Files:
   src/lib/libutil: efun.c
 
 Log Message:
 If malloc, calloc, or realloc returns NULL when a size of 0 was
 requested, which is allowed by pertinent standards, honor it instead
 of bombing.
 
 Do not do this for calloc(x, y) where x != 0  y != 0 but x*y == 0;
 in that case bomb.

The commit message is misleading. We expect calloc(x,y) to return NULL
if x!=0  y!=0  x*y==0.

Joerg

Re: CVS commit: src/lib/libutil

[David Holland]

On Mon, Dec 31, 2012 at 02:59:13AM +0100, Joerg Sonnenberger wrote:
   Modified Files:
  src/lib/libutil: efun.c
   
   Log Message:
   If malloc, calloc, or realloc returns NULL when a size of 0 was
   requested, which is allowed by pertinent standards, honor it instead
   of bombing.
   
   Do not do this for calloc(x, y) where x != 0  y != 0 but x*y == 0;
   in that case bomb.
  
  The commit message is misleading. We expect calloc(x,y) to return NULL
  if x!=0  y!=0  x*y==0.

I don't understand. The logic I added is exactly what I described.

-- 
David A. Holland
dholl...@netbsd.org

Re: CVS commit: src/lib/libutil

[Alan Barrett]

On Mon, 31 Dec 2012, Joerg Sonnenberger wrote:

Log Message:
If malloc, calloc, or realloc returns NULL when a size of 0 was
requested, which is allowed by pertinent standards, honor it instead
of bombing.

Do not do this for calloc(x, y) where x != 0  y != 0 but x*y == 0;
in that case bomb.


The commit message is misleading. We expect calloc(x,y) to return NULL
if x!=0  y!=0  x*y==0.


(x!=0  y!=0  x*y==0) can be true only if calculating x*y results
in what would loosely be called integer overflow; since the types are
unsigned, it's a well-defined kind of wraparound, not the undefined kind
of overflow.  I'd expect an error like EINVAL rather than an error like
ENOMEM for this case.

--apb (Alan Barrett)

Re: CVS commit: src/lib/libutil

[Joerg Sonnenberger]

On Sun, Jul 22, 2012 at 10:21:14PM -0400, Christos Zoulas wrote:
 Module Name:  src
 Committed By: christos
 Date: Mon Jul 23 02:21:14 UTC 2012
 
 Modified Files:
   src/lib/libutil: openpty.3
 
 Log Message:
 Mention how big the name can be.

I don't think we should leak internals like that. It's a path name, the
only limit guaranteed by the system should PATH_MAX as such.

Joerg

Re: CVS commit: src/lib/libutil

[Jean-Yves Migeon]

On 13.11.2011 23:03, Christos Zoulas wrote:

Module Name:src
Committed By:   christos
Date:   Sun Nov 13 22:03:34 UTC 2011

Modified Files:
src/lib/libutil: Makefile
Added Files:
src/lib/libutil: getfstypename.3

Log Message:
add manual page


Just wondering: is there a different rule applicable to man pages for 
4-clause vs 2-clause BSD? I occasionally see new man pages written with 
a 4-clause BSD, however, most newly written code is 2-clause.


--
Jean-Yves Migeon
jeanyves.mig...@free.fr

Re: CVS commit: src/lib/libutil

[Christos Zoulas]

In article 4ec5a97e.2070...@free.fr,
Jean-Yves Migeon  jeanyves.mig...@free.fr wrote:
On 13.11.2011 23:03, Christos Zoulas wrote:
 Module Name: src
 Committed By:christos
 Date:Sun Nov 13 22:03:34 UTC 2011

 Modified Files:
  src/lib/libutil: Makefile
 Added Files:
  src/lib/libutil: getfstypename.3

 Log Message:
 add manual page

Just wondering: is there a different rule applicable to man pages for 
4-clause vs 2-clause BSD? I occasionally see new man pages written with 
a 4-clause BSD, however, most newly written code is 2-clause.

fixed.

christos

Re: CVS commit: src/lib/libutil

[Bernd Ernesti]

Hi,

On Thu, Oct 20, 2011 at 09:37:59PM -0400, Christos Zoulas wrote:
 Module Name:  src
 Committed By: christos
 Date: Fri Oct 21 01:37:59 UTC 2011
 
 Modified Files:
   src/lib/libutil: Makefile
 
 Log Message:
 Don't use = to assing SRCS, but += so that we can remove snprintb.c,
 which was added elsewhere.

I find that a little dangerous.

Now SRCS could be defined in the environment which may cause
different behaviour like including different not wanted source
file, build errors ...

I do not know if it would work to move the include of the common
Makefile.inc at the end, propably not. And yes the common Makefile.inc
already used SRCS+= before. That alone should require to move
that include after a normal SRCS=

Bernd

Re: CVS commit: src/lib/libutil

[YAMAMOTO Takashi]

hi,

 Module Name:  src
 Committed By: christos
 Date: Fri Oct 21 02:05:36 UTC 2011
 
 Modified Files:
   src/lib/libutil: Makefile
 
 Log Message:
 Add proc_compare

you forgot to commit proc_compare.3?

YAMAMOTO Takashi

 
 
 To generate a diff of this commit:
 cvs rdiff -u -r1.67 -r1.68 src/lib/libutil/Makefile
 
 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

Re: CVS commit: src/lib/libutil

[Christos Zoulas]

On Oct 21,  9:33am, y...@mwd.biglobe.ne.jp (YAMAMOTO Takashi) wrote:
-- Subject: Re: CVS commit: src/lib/libutil

| hi,
| 
|  Module Name:src
|  Committed By:   christos
|  Date:   Fri Oct 21 02:05:36 UTC 2011
|  
|  Modified Files:
|  src/lib/libutil: Makefile
|  
|  Log Message:
|  Add proc_compare
| 
| you forgot to commit proc_compare.3?
| 
| YAMAMOTO Takashi

Yup, thanks!

christos

re: CVS commit: src/lib/libutil

[matthew green]

   
   Modified Files:
src/lib/libutil: util.3
   
   Log Message:
   Upon lukem@'s request, put the list of functions back.

thank you.

Re: CVS commit: src/lib/libutil

[Luke Mewburn]

On Tue, May 04, 2010 at 07:07:12AM +, Jukka Ruohonen wrote:
  | Module Name:src
  | Committed By:   jruoho
  | Date:   Tue May  4 07:07:12 UTC 2010
  | 
  | Modified Files:
  | src/lib/libutil: util.3
  | 
  | Log Message:
  | Remove the list of functions in the libutil library.
  | 
  | While such lists are nice, they are doomed to be repeatedly out of date due
  | maintenance costs related to manual updates. Ideally there should be a
  | common routine to auto-generate these, but in the meantime, just point to
  | the directory where libutil is implemented.

Please revert this; manual pages and application development
tools are often installed on systems where the full source is not.
As I mentioned in my reply to the similar change in stdio(3),
these lists are useful.

cheers,
Luke.


pgpCGMz7b2c4i.pgp
Description: PGP signature

Re: CVS commit: src/lib/libutil

[Jukka Ruohonen]

On Wed, May 05, 2010 at 01:05:02PM +1000, Luke Mewburn wrote:
 Please revert this; manual pages and application development
 tools are often installed on systems where the full source is not.

But you always have the header file. Shouldn't that be enough?

 As I mentioned in my reply to the similar change in stdio(3),
 these lists are useful.

And as I noted, incomplete and inaccurate documentation is often worse than
no documentation at all.

- Jukka.

Re: CVS commit: src/lib/libutil

[Luke Mewburn]

On Wed, May 05, 2010 at 07:35:41AM +0300, Jukka Ruohonen wrote:
  | On Wed, May 05, 2010 at 01:05:02PM +1000, Luke Mewburn wrote:
  |  Please revert this; manual pages and application development
  |  tools are often installed on systems where the full source is not.
  | 
  | But you always have the header file. Shouldn't that be enough?

In general, I don't find it sufficient to just rely upon reading
header files, especially when the APIs are spread across multiple
recursive #includes and/or may be a macro on some implementations
and a function on others.

This is also true on other UNIX-like platforms such as Darwin  Linux,
and in C++ (STL headers, anyone?)


pgpsZAH8uBSXl.pgp
Description: PGP signature