* [PATCH] fgetc.3: Describe handling of ungetc(EOF, stream)
@ 2023-05-26 15:19 Ian Abbott
2023-05-26 15:28 ` Alejandro Colomar
` (2 more replies)
0 siblings, 3 replies; 7+ messages in thread
From: Ian Abbott @ 2023-05-26 15:19 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: linux-man, 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
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH] fgetc.3: Describe handling of ungetc(EOF, stream)
2023-05-26 15:19 [PATCH] fgetc.3: Describe handling of ungetc(EOF, stream) Ian Abbott
@ 2023-05-26 15:28 ` Alejandro Colomar
2023-05-26 15:57 ` Ian Abbott
2023-05-26 15:34 ` Ian Abbott
2023-05-26 15:41 ` [PATCH v2] " Ian Abbott
2 siblings, 1 reply; 7+ messages in thread
From: Alejandro Colomar @ 2023-05-26 15:28 UTC (permalink / raw)
To: Ian Abbott, Alejandro Colomar; +Cc: linux-man
[-- 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 --]
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] fgetc.3: Describe handling of ungetc(EOF, stream)
2023-05-26 15:19 [PATCH] fgetc.3: Describe handling of ungetc(EOF, stream) Ian Abbott
2023-05-26 15:28 ` Alejandro Colomar
@ 2023-05-26 15:34 ` Ian Abbott
2023-05-26 15:41 ` [PATCH v2] " Ian Abbott
2 siblings, 0 replies; 7+ messages in thread
From: Ian Abbott @ 2023-05-26 15:34 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: linux-man
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 )=-
^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH v2] fgetc.3: Describe handling of ungetc(EOF, stream)
2023-05-26 15:19 [PATCH] fgetc.3: Describe handling of ungetc(EOF, stream) Ian Abbott
2023-05-26 15:28 ` Alejandro Colomar
2023-05-26 15:34 ` Ian Abbott
@ 2023-05-26 15:41 ` Ian Abbott
2023-05-26 16:09 ` [PATCH v3] " Ian Abbott
2 siblings, 1 reply; 7+ messages in thread
From: Ian Abbott @ 2023-05-26 15:41 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: linux-man, 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
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH] fgetc.3: Describe handling of ungetc(EOF, stream)
2023-05-26 15:28 ` Alejandro Colomar
@ 2023-05-26 15:57 ` Ian Abbott
0 siblings, 0 replies; 7+ messages in thread
From: Ian Abbott @ 2023-05-26 15:57 UTC (permalink / raw)
To: Alejandro Colomar, Alejandro Colomar; +Cc: linux-man
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 )=-
^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH v3] fgetc.3: Describe handling of ungetc(EOF, stream)
2023-05-26 15:41 ` [PATCH v2] " Ian Abbott
@ 2023-05-26 16:09 ` Ian Abbott
2023-05-29 3:03 ` Oskari Pirhonen
0 siblings, 1 reply; 7+ messages in thread
From: Ian Abbott @ 2023-05-26 16:09 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: linux-man, 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
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH v3] fgetc.3: Describe handling of ungetc(EOF, stream)
2023-05-26 16:09 ` [PATCH v3] " Ian Abbott
@ 2023-05-29 3:03 ` Oskari Pirhonen
0 siblings, 0 replies; 7+ messages in thread
From: Oskari Pirhonen @ 2023-05-29 3:03 UTC (permalink / raw)
To: Ian Abbott; +Cc: Alejandro Colomar, linux-man
[-- 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 --]
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2023-05-29 3:03 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-05-26 15:19 [PATCH] fgetc.3: Describe handling of ungetc(EOF, stream) Ian Abbott
2023-05-26 15:28 ` Alejandro Colomar
2023-05-26 15:57 ` Ian Abbott
2023-05-26 15:34 ` Ian Abbott
2023-05-26 15:41 ` [PATCH v2] " Ian Abbott
2023-05-26 16:09 ` [PATCH v3] " Ian Abbott
2023-05-29 3:03 ` Oskari Pirhonen
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.