AW: [PATCH] fread.3: Add example

[Walter Harms <wharms@bfs.de>]

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