[PATCH] fread.3: Add example

[PATCH] fread.3: Add example

[Arkadiusz Drabczyk]

Signed-off-by: Arkadiusz Drabczyk <arkadiusz@drabczyk.org>
---
 man3/fread.3 | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/man3/fread.3 b/man3/fread.3
index 2dd7be9..c19a59c 100644
--- a/man3/fread.3
+++ b/man3/fread.3
@@ -113,6 +113,59 @@ T}	Thread safety	MT-Safe
 .TE
 .SH CONFORMING TO
 POSIX.1-2001, POSIX.1-2008, C89.
+.SH EXAMPLES
+The program below demonstrates the use of
+.BR fread ()
+by parsing /bin/sh ELF executable in binary mode and printing its
+magic and class:
+.PP
+.in +4n
+.EX
+$ \fB./a.out\fP
+./a.out
+ELF magic: 0x7f454c46
+Class: 0x2
+.EE
+.in
+.SS Program source
+\&
+.EX
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+    FILE *fp = fopen("/bin/sh", "rb");
+    if (!fp) {
+        perror("fopen");
+        return EXIT_FAILURE;
+    }
+
+    unsigned char buffer[4];
+
+    size_t ret = fread(buffer, 4, 1, fp);
+    if (ret != 1) {
+        fprintf(stderr, "fread() failed: %zu\en", ret);
+        exit(EXIT_FAILURE);
+    }
+
+    printf("ELF magic: %#x%x%x%x\en", buffer[0], buffer[1], buffer[2],
+           buffer[3]);
+
+    ret = fread(buffer, 1, 1, fp);
+    if (ret != 1) {
+        fprintf(stderr, "fread() failed: %zu\en", ret);
+        exit(EXIT_FAILURE);
+    }
+
+    printf("Class: %#x\en", buffer[0]);
+
+    fclose(fp);
+
+    exit(EXIT_SUCCESS);
+}
+.EE
 .SH SEE ALSO
 .BR read (2),
 .BR write (2),
-- 
2.9.0

AW: [PATCH] fread.3: Add example

[Walter Harms]

few comments below,
hope that helps

re,
 wh
________________________________________
Von: linux-man-owner@vger.kernel.org [linux-man-owner@vger.kernel.org] im Auftrag von Arkadiusz Drabczyk [arkadiusz@drabczyk.org]
Gesendet: Mittwoch, 17. Juni 2020 20:45
An: mtk.manpages@gmail.com
Cc: linux-man@vger.kernel.org
Betreff: [PATCH] fread.3: Add example

Signed-off-by: Arkadiusz Drabczyk <arkadiusz@drabczyk.org>
---
 man3/fread.3 | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/man3/fread.3 b/man3/fread.3
index 2dd7be9..c19a59c 100644
--- a/man3/fread.3
+++ b/man3/fread.3
@@ -113,6 +113,59 @@ T} Thread safety   MT-Safe
 .TE
 .SH CONFORMING TO
 POSIX.1-2001, POSIX.1-2008, C89.
+.SH EXAMPLES
+The program below demonstrates the use of
+.BR fread ()
+by parsing /bin/sh ELF executable in binary mode and printing its
+magic and class:
+.PP
+.in +4n
+.EX
+$ \fB./a.out\fP
+./a.out
+ELF magic: 0x7f454c46
+Class: 0x2
+.EE
+.in
+.SS Program source
+\&
+.EX
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+    FILE *fp = fopen("/bin/sh", "rb");
+    if (!fp) {
+        perror("fopen");
+        return EXIT_FAILURE;
+    }
+
+    unsigned char buffer[4];
+
+    size_t ret = fread(buffer, 4, 1, fp);
this is the core of the example and should be a bit more verbose:
maybe this is a bit to cryptic
   ret = fread(buffer,sizeof (buffer)/sizeof (*buffer), sizeof (*buffer), fp);

alt:
size_of_buf= sizeof (buffer)/sizeof (*buffer); 

 ret = fread(buffer,                                              // start of buffer
                    sizeof (buffer)/sizeof (*buffer),    // size of buffer in bytes
                    sizeof (*buffer),                              // size of element
                    fp);                                                   // file pointer

+    if (ret != 1) {
+        fprintf(stderr, "fread() failed: %zu\en", ret);
+        exit(EXIT_FAILURE);
+    }
+
+    printf("ELF magic: %#x%x%x%x\en", buffer[0], buffer[1], buffer[2],
+           buffer[3]);
+
this works for /bin/sh but if the user plays round this may show confusing results
so you could simply do:
    printf("ELF magic: %#02x%02x%02x%02x\en", 
so you are consistent in all cased. (until some will test this on a big endian, no idea
what will happen then). 

+    ret = fread(buffer, 1, 1, fp);
+    if (ret != 1) {
+        fprintf(stderr, "fread() failed: %zu\en", ret);
+        exit(EXIT_FAILURE);
+    }
+
please drop a line what case you want to explain here, looks like the same as above.

+    printf("Class: %#x\en", buffer[0]);
+
+    fclose(fp);
+
+    exit(EXIT_SUCCESS);
+}
+.EE
 .SH SEE ALSO
 .BR read (2),
 .BR write (2),
--
2.9.0

Re: [PATCH] fread.3: Add example

[Arkadiusz Drabczyk]

On Thu, Jun 18, 2020 at 08:49:53AM +0000, Walter Harms wrote:
> +    size_t ret = fread(buffer, 4, 1, fp);
> this is the core of the example and should be a bit more verbose:
> maybe this is a bit to cryptic
>    ret = fread(buffer,sizeof (buffer)/sizeof (*buffer), sizeof (*buffer), fp);

ok, I'll use this version in v2.

> +    printf("ELF magic: %#x%x%x%x\en", buffer[0], buffer[1], buffer[2],
> +           buffer[3]);
> +
> this works for /bin/sh but if the user plays round this may show confusing results
> so you could simply do:
>     printf("ELF magic: %#02x%02x%02x%02x\en",
> so you are consistent in all cased. 

ok, I'll do it in v2.

> (until some will test this on a big endian, no idea
> what will happen then).

Nothing, in ELF spec it says that "the initial bytes of the file
specify how to interpret the file, independent of the processor on
which the inquiry is made and independent of the file's remaining
contents.". And of course I tested this example on my router which has
MIPS CPU which is big-endian and runs big-edian ELFs:

$ file sh
sh: ELF 32-bit MSB executable, MIPS, MIPS32 rel2 version 1, dynamically linked, interpreter /lib/ld-uClibc.so.0, corrupted section header size

and output of the example program is the same as on x86.

> 
> +    ret = fread(buffer, 1, 1, fp);
> +    if (ret != 1) {
> +        fprintf(stderr, "fread() failed: %zu\en", ret);
> +        exit(EXIT_FAILURE);
> +    }
> +
> please drop a line what case you want to explain here, looks like the same as above.

As said a few lines above, this retrieves ELF class. I wanted to show
that file pointer moves automatically after fread() finishes.

-- 
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>

AW: [PATCH] fread.3: Add example

[Walter Harms]

________________________________________
Von: Arkadiusz Drabczyk [arkadiusz@drabczyk.org]
Gesendet: Donnerstag, 18. Juni 2020 15:36

>>
>> +    ret = fread(buffer, 1, 1, fp);
>> +    if (ret != 1) {
>> +        fprintf(stderr, "fread() failed: %zu\en", ret);
>> +        exit(EXIT_FAILURE);
>> +    }
>> +
>> please drop a line what case you want to explain here, looks like the same as above.

>As said a few lines above, this retrieves ELF class. I wanted to show
>that file pointer moves automatically after fread() finishes.

ok i get the point(s).
1. you show you can read an "item" a bunch of bytes

the second read() should demonstrate that consecutive reads return
 consecutive blocks of data (here the magic and class id of an ELF).

perhaps you can support what want to show with a
printf("pos=%ld\n",ftell(fp));
before and after read.

hope that helps,
re,
 wh

--
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>

Re: [PATCH] fread.3: Add example

[Arkadiusz Drabczyk]

On Thu, Jun 18, 2020 at 02:47:54PM +0000, Walter Harms wrote:
> 
> ________________________________________
> Von: Arkadiusz Drabczyk [arkadiusz@drabczyk.org]
> Gesendet: Donnerstag, 18. Juni 2020 15:36
> 
> >>
> >> +    ret = fread(buffer, 1, 1, fp);
> >> +    if (ret != 1) {
> >> +        fprintf(stderr, "fread() failed: %zu\en", ret);
> >> +        exit(EXIT_FAILURE);
> >> +    }
> >> +
> >> please drop a line what case you want to explain here, looks like the same as above.
> 
> >As said a few lines above, this retrieves ELF class. I wanted to show
> >that file pointer moves automatically after fread() finishes.
> 
> ok i get the point(s).
> 1. you show you can read an "item" a bunch of bytes
> 
> the second read() should demonstrate that consecutive reads return
>  consecutive blocks of data (here the magic and class id of an ELF).

Exactly.

> perhaps you can support what want to show with a
> printf("pos=%ld\n",ftell(fp));
> before and after read.

Let's what Michael says. If he thinks this suggestion and the entire
example in the first place is a good idea I will add it.

-- 
Arkadiusz Drabczyk <arkadiusz@drabczyk.org>