[PATCH] fgetc.3: Describe handling of ungetc(EOF, stream)

[PATCH] fgetc.3: Describe handling of ungetc(EOF, stream)

[Ian Abbott]

As per the C standard, calling ungetc() with the character parameter
equal to EOF causes it to fail, returning EOF.

Signed-off-by: Ian Abbott <abbotti@mev.co.uk>
---
 man3/fgetc.3 | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/man3/fgetc.3 b/man3/fgetc.3
index 75dcaeaf6..d6bf62327 100644
--- a/man3/fgetc.3
+++ b/man3/fgetc.3
@@ -62,7 +62,13 @@ A terminating null byte (\[aq]\e0\[aq])
 is stored after the last character in the buffer.
 .PP
 .BR ungetc ()
-pushes
+returns
+.B EOF
+if the value of
+.I c
+equals that of the macro
+.BR EOF ,
+otherwise it pushes
 .I c
 back to
 .IR stream ,
-- 
2.39.2

Re: [PATCH] fgetc.3: Describe handling of ungetc(EOF, stream)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1114 bytes --]

Hi Ian!

On 5/26/23 17:19, Ian Abbott wrote:
> As per the C standard, calling ungetc() with the character parameter
> equal to EOF causes it to fail, returning EOF.
> 
> Signed-off-by: Ian Abbott <abbotti@mev.co.uk>
> ---
>  man3/fgetc.3 | 8 +++++++-
>  1 file changed, 7 insertions(+), 1 deletion(-)
> 
> diff --git a/man3/fgetc.3 b/man3/fgetc.3
> index 75dcaeaf6..d6bf62327 100644
> --- a/man3/fgetc.3
> +++ b/man3/fgetc.3
> @@ -62,7 +62,13 @@ A terminating null byte (\[aq]\e0\[aq])
>  is stored after the last character in the buffer.
>  .PP
>  .BR ungetc ()
> -pushes
> +returns
> +.B EOF
> +if the value of
> +.I c
> +equals that of the macro
> +.BR EOF ,
> +otherwise it pushes

I would put that detail at the end of the description, rather than
the beginning.  In C code, that kind of short-cutting can help
reading, but in the manual, it's better left as a detail at the end
of it, to give it less importance.

Cheers,
Alex

>  .I c
>  back to
>  .IR stream ,

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

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

Re: [PATCH] fgetc.3: Describe handling of ungetc(EOF, stream)

[Ian Abbott]

On 26/05/2023 16:19, Ian Abbott wrote:
> As per the C standard, calling ungetc() with the character parameter
> equal to EOF causes it to fail, returning EOF.
> 
> Signed-off-by: Ian Abbott <abbotti@mev.co.uk>
> ---
>   man3/fgetc.3 | 8 +++++++-
>   1 file changed, 7 insertions(+), 1 deletion(-)
> 
> diff --git a/man3/fgetc.3 b/man3/fgetc.3
> index 75dcaeaf6..d6bf62327 100644
> --- a/man3/fgetc.3
> +++ b/man3/fgetc.3
> @@ -62,7 +62,13 @@ A terminating null byte (\[aq]\e0\[aq])
>   is stored after the last character in the buffer.
>   .PP
>   .BR ungetc ()
> -pushes
> +returns
> +.B EOF
> +if the value of
> +.I c
> +equals that of the macro
> +.BR EOF ,
> +otherwise it pushes
>   .I c
>   back to
>   .IR stream ,

Sorry, I've just realized my English grammar usage was a bit poor there. 
  I'll send a v2 patch.

-- 
-=( Ian Abbott <abbotti@mev.co.uk> || MEV Ltd. is a company  )=-
-=( registered in England & Wales.  Regd. number: 02862268.  )=-
-=( Regd. addr.: S11 & 12 Building 67, Europa Business Park, )=-
-=( Bird Hall Lane, STOCKPORT, SK3 0XA, UK. || www.mev.co.uk )=-

[PATCH v2] fgetc.3: Describe handling of ungetc(EOF, stream)

[Ian Abbott]

As per the C standard, calling ungetc() with the character parameter
equal to EOF causes it to fail, returning EOF.

Signed-off-by: Ian Abbott <abbotti@mev.co.uk>
---
v2: Correct English grammar usage for "otherwise".
---
 man3/fgetc.3 | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/man3/fgetc.3 b/man3/fgetc.3
index 75dcaeaf6..751a00407 100644
--- a/man3/fgetc.3
+++ b/man3/fgetc.3
@@ -62,7 +62,13 @@ A terminating null byte (\[aq]\e0\[aq])
 is stored after the last character in the buffer.
 .PP
 .BR ungetc ()
-pushes
+returns
+.B EOF
+if the value of
+.I c
+equals that of the macro
+.BR EOF .
+Otherwise, it pushes
 .I c
 back to
 .IR stream ,
-- 
2.39.2

Re: [PATCH] fgetc.3: Describe handling of ungetc(EOF, stream)

[Ian Abbott]

On 26/05/2023 16:28, Alejandro Colomar wrote:
> Hi Ian!
> 
> On 5/26/23 17:19, Ian Abbott wrote:
>> As per the C standard, calling ungetc() with the character parameter
>> equal to EOF causes it to fail, returning EOF.
>>
>> Signed-off-by: Ian Abbott <abbotti@mev.co.uk>
>> ---
>>   man3/fgetc.3 | 8 +++++++-
>>   1 file changed, 7 insertions(+), 1 deletion(-)
>>
>> diff --git a/man3/fgetc.3 b/man3/fgetc.3
>> index 75dcaeaf6..d6bf62327 100644
>> --- a/man3/fgetc.3
>> +++ b/man3/fgetc.3
>> @@ -62,7 +62,13 @@ A terminating null byte (\[aq]\e0\[aq])
>>   is stored after the last character in the buffer.
>>   .PP
>>   .BR ungetc ()
>> -pushes
>> +returns
>> +.B EOF
>> +if the value of
>> +.I c
>> +equals that of the macro
>> +.BR EOF ,
>> +otherwise it pushes
> 
> I would put that detail at the end of the description, rather than
> the beginning.  In C code, that kind of short-cutting can help
> reading, but in the manual, it's better left as a detail at the end
> of it, to give it less importance.

OK, but I think it would still need some sort of remark in the first 
sentence to indicate that it does not always apply.  Maybe something 
along the lines of:

   normally pushes c back to stream,  ...

Then add the c==EOF exception as a new paragraph along the lines of:

   If the value of c equals that of the macro EOF, nothing is
   pushed back to the stream and an error is returned.

-- 
-=( Ian Abbott <abbotti@mev.co.uk> || MEV Ltd. is a company  )=-
-=( registered in England & Wales.  Regd. number: 02862268.  )=-
-=( Regd. addr.: S11 & 12 Building 67, Europa Business Park, )=-
-=( Bird Hall Lane, STOCKPORT, SK3 0XA, UK. || www.mev.co.uk )=-

[PATCH v3] fgetc.3: Describe handling of ungetc(EOF, stream)

[Ian Abbott]

As per the C standard, calling ungetc() with the character parameter
equal to EOF causes it to fail, returning EOF.

Signed-off-by: Ian Abbott <abbotti@mev.co.uk>
---
v2: Correct English grammar usage for "otherwise".
v3: Move detail of EOF special case to the end of the paragraph to give
    it less prominence, as suggested by Alex.
---
 man3/fgetc.3 | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/man3/fgetc.3 b/man3/fgetc.3
index 75dcaeaf6..a15d73b15 100644
--- a/man3/fgetc.3
+++ b/man3/fgetc.3
@@ -62,7 +62,7 @@ A terminating null byte (\[aq]\e0\[aq])
 is stored after the last character in the buffer.
 .PP
 .BR ungetc ()
-pushes
+normally pushes
 .I c
 back to
 .IR stream ,
@@ -71,6 +71,13 @@ cast to
 where it is available for subsequent read operations.
 Pushed-back characters
 will be returned in reverse order; only one pushback is guaranteed.
+If the value of
+.I c
+equals that of the macro
+.BR EOF ,
+nothing is pushed back to
+.I stream
+and an error is returned.
 .PP
 Calls to the functions described here can be mixed with each other and with
 calls to other input functions from the
-- 
2.39.2

Re: [PATCH v3] fgetc.3: Describe handling of ungetc(EOF, stream)

[Oskari Pirhonen]

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

Hi,

On Fri, May 26, 2023 at 17:09:44 +0100, Ian Abbott wrote:
> As per the C standard, calling ungetc() with the character parameter
> equal to EOF causes it to fail, returning EOF.
> 
> Signed-off-by: Ian Abbott <abbotti@mev.co.uk>
> ---
> v2: Correct English grammar usage for "otherwise".
> v3: Move detail of EOF special case to the end of the paragraph to give
>     it less prominence, as suggested by Alex.
> ---
>  man3/fgetc.3 | 9 ++++++++-
>  1 file changed, 8 insertions(+), 1 deletion(-)
> 
> diff --git a/man3/fgetc.3 b/man3/fgetc.3
> index 75dcaeaf6..a15d73b15 100644
> --- a/man3/fgetc.3
> +++ b/man3/fgetc.3
> @@ -62,7 +62,7 @@ A terminating null byte (\[aq]\e0\[aq])
>  is stored after the last character in the buffer.
>  .PP
>  .BR ungetc ()
> -pushes
> +normally pushes
>  .I c
>  back to
>  .IR stream ,

IMO, saying "ungetc() normally pushes c back to stream" is a bit
redundant. After all, pretty much every function "normally does [thing]"
unless an error/exception case is hit.

It also breaks the flow of the previous text where you have, for
example:

    fgetc() reads the next character from stream and returns it as an
    unsigned char cast to an int, or EOF on end of file or error.

> @@ -71,6 +71,13 @@ cast to
>  where it is available for subsequent read operations.
>  Pushed-back characters
>  will be returned in reverse order; only one pushback is guaranteed.
> +If the value of
> +.I c
> +equals that of the macro
> +.BR EOF ,
> +nothing is pushed back to
> +.I stream
> +and an error is returned.

Similarly, I think you can drop the "that of the macro EOF" and just say
"equals EOF".

- Oskari

>  .PP
>  Calls to the functions described here can be mixed with each other and with
>  calls to other input functions from the
> -- 
> 2.39.2
> 

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