string_copying.7: Clarifying ustr and zustr

string_copying.7: Clarifying ustr and zustr

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2778 bytes --]

Hi Serge,

I'm clarifying zustr after your suggestion.  Please check this text.

DESCRIPTION
   Terms (and abbreviations)
       string (str)
              is  a  sequence of zero or more non‐null characters fol‐
              lowed by a null byte.

       character sequence
              is a sequence of zero or more  non‐null  characters.   A
              program  should  never  use a character sequence where a
              string is required.  However, with appropriate  care,  a
              string can be used in the place of a character sequence.

              null‐padded character sequence (zustr)
                     Character  sequences  can  be contained in fixed‐
                     width buffers, which contain padding  null  bytes
                     after the character sequence, to fill the rest of
                     the  buffer  without  affecting the character se‐
                     quence; however, those padding null bytes are not
                     part of the character sequence.  zustr stands for
                     Zero‐padded Unterminated STRing.   Don’t  confuse
                     zero‐padded   with  null‐terminated:  zero‐padded
                     means 0 or more padding zeros (null  characters),
                     while null‐terminated means exactly 1 terminating
                     null character.

              measured character sequence (ustr)
                     Character  sequence  delimited by its length.  It
                     may be a slice of a larger character sequence, or
                     even of a string.  ustr stands  for  Unterminated
                     STRing.

The patch is:

diff --git a/man7/string_copying.7 b/man7/string_copying.7
index e03c2dda6..c5f374025 100644
--- a/man7/string_copying.7
+++ b/man7/string_copying.7
@@ -102,12 +102,19 @@ .SS Terms (and abbreviations)
 to fill the rest of the buffer
 without affecting the character sequence;
 however, those padding null bytes are not part of the character sequence.
+.I zustr
+stands for Zero-padded Unterminated STRing.
+Don't confuse zero-padded with null-terminated:
+zero-padded means 0 or more padding zeros (null characters),
+while null-terminated means exactly 1 terminating null character.
 .\" ----- DESCRIPTION :: Terms (and abbreviations) :: measured character sequence
 .TP
 .IR "measured character sequence " ( ustr )
 Character sequence delimited by its length.
 It may be a slice of a larger character sequence,
 or even of a string.
+.I ustr
+stands for Unterminated STRing.
 .RE
 .\" ----- DESCRIPTION :: Terms (and abbreviations) :: length (len) ----/
 .TP


Thanks,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: string_copying.7: Clarifying ustr and zustr

[Serge E. Hallyn]

On Tue, Oct 10, 2023 at 04:09:05PM +0200, Alejandro Colomar wrote:
> Hi Serge,
> 
> I'm clarifying zustr after your suggestion.  Please check this text.

Thanks, this looks good.

> DESCRIPTION
>    Terms (and abbreviations)
>        string (str)
>               is  a  sequence of zero or more non‐null characters fol‐
>               lowed by a null byte.
> 
>        character sequence
>               is a sequence of zero or more  non‐null  characters.   A
>               program  should  never  use a character sequence where a
>               string is required.  However, with appropriate  care,  a
>               string can be used in the place of a character sequence.
> 
>               null‐padded character sequence (zustr)
>                      Character  sequences  can  be contained in fixed‐
>                      width buffers, which contain padding  null  bytes
>                      after the character sequence, to fill the rest of
>                      the  buffer  without  affecting the character se‐
>                      quence; however, those padding null bytes are not
>                      part of the character sequence.  zustr stands for
>                      Zero‐padded Unterminated STRing.   Don’t  confuse
>                      zero‐padded   with  null‐terminated:  zero‐padded
>                      means 0 or more padding zeros (null  characters),
>                      while null‐terminated means exactly 1 terminating
>                      null character.
> 
>               measured character sequence (ustr)
>                      Character  sequence  delimited by its length.  It
>                      may be a slice of a larger character sequence, or
>                      even of a string.  ustr stands  for  Unterminated
>                      STRing.
> 
> The patch is:
> 
> diff --git a/man7/string_copying.7 b/man7/string_copying.7
> index e03c2dda6..c5f374025 100644
> --- a/man7/string_copying.7
> +++ b/man7/string_copying.7
> @@ -102,12 +102,19 @@ .SS Terms (and abbreviations)
>  to fill the rest of the buffer
>  without affecting the character sequence;
>  however, those padding null bytes are not part of the character sequence.
> +.I zustr
> +stands for Zero-padded Unterminated STRing.
> +Don't confuse zero-padded with null-terminated:
> +zero-padded means 0 or more padding zeros (null characters),
> +while null-terminated means exactly 1 terminating null character.
>  .\" ----- DESCRIPTION :: Terms (and abbreviations) :: measured character sequence
>  .TP
>  .IR "measured character sequence " ( ustr )
>  Character sequence delimited by its length.
>  It may be a slice of a larger character sequence,
>  or even of a string.
> +.I ustr
> +stands for Unterminated STRing.
>  .RE
>  .\" ----- DESCRIPTION :: Terms (and abbreviations) :: length (len) ----/
>  .TP
> 
> 
> Thanks,
> Alex
> 
> -- 
> <https://www.alejandro-colomar.es/>

Re: string_copying.7: Clarifying ustr and zustr

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 490 bytes --]

On Wed, Oct 11, 2023 at 03:39:19PM -0500, Serge E. Hallyn wrote:
> On Tue, Oct 10, 2023 at 04:09:05PM +0200, Alejandro Colomar wrote:
> > Hi Serge,
> > 
> > I'm clarifying zustr after your suggestion.  Please check this text.
> 
> Thanks, this looks good.

Thank you.  Patch applied:
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=b31fe84c31989bc6d3a2884bec5c538e06498423>

Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]