Re: [PATCH] EXIT_SUCCESS.3const EXIT_FAILURE.3const: Add pages

[Alejandro Colomar <alx.manpages@gmail.com>]

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

Hi Thomas,

On 11/16/22 22:50, Thomas Voss wrote:
> I see we have manuals for constants, types, and more now!  That sure brings a
> smile to my face :).

It's good to see that there's audience that likes these.  :)


>  I guess I might help out a bit will filling out some of
> the missing manuals.

Sure.

> 
> Signed-off-by: Thomas Voss <mail@thomasvoss.com>
> ---
>   man3const/EXIT_FAILURE.3const |  1 +
>   man3const/EXIT_SUCCESS.3const | 58 +++++++++++++++++++++++++++++++++++
>   2 files changed, 59 insertions(+)
>   create mode 100644 man3const/EXIT_FAILURE.3const
>   create mode 100644 man3const/EXIT_SUCCESS.3const
> 
> diff --git a/man3const/EXIT_FAILURE.3const b/man3const/EXIT_FAILURE.3const
> new file mode 100644
> index 000000000..ba0d62df9
> --- /dev/null
> +++ b/man3const/EXIT_FAILURE.3const
> @@ -0,0 +1 @@
> +.so man3const/EXIT_SUCCESS.3const
> diff --git a/man3const/EXIT_SUCCESS.3const b/man3const/EXIT_SUCCESS.3const
> new file mode 100644
> index 000000000..dd6f908e5
> --- /dev/null
> +++ b/man3const/EXIT_SUCCESS.3const
> @@ -0,0 +1,58 @@
> +.\" Copyright (c) 2022 by Thomas Voss <mail@thomasvoss.com>
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.\"
> +.TH EXIT_SUCCESS 3const (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +EXIT_SUCCESS, EXIT_FAILURE \- termination status constants
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc )
> +.SH SYNOPSIS
> +.nf
> +.B #include <stdlib.h>
> +.PP
> +.B "#define EXIT_SUCCESS  /* ... */"

Although ISO C leaves the value unspecified, POSIX guarantees it is 0, so I'd 
document it as such.

The exact definition in glibc is (in my system):

     $ grepc EXIT_SUCCESS /usr/include/stdlib.h
     /usr/include/stdlib.h:93:
     #define	EXIT_SUCCESS	0	/* Successful exit status.  */

So I'd document it as:

.B "#define EXIT_SUCCESS  0"

> +.B "#define EXIT_FAILURE  /* ... */"

The /* ... */ should not be in bold (which makes me realize I did it wrong in 
EOF.3const, sorry).  Also, POSIX specifies that it should be a non-zero value, 
so I'd document it as:

.BR "#define EXIT_FAILURE" "  /* non-zero */"

> +.fi
> +.SH DESCRIPTION
> +.BR EXIT_SUCCESS " and " EXIT_FAILURE

We use separate lines for separate identifiers:

.B EXIT_SUCCESS
and
.B EXIT_FAILURE

> +represent a successful and unsuccessful exit status respectively.
> +Both macros are constant expressions of type
> +.I int

Being "constant expressions of type int" is is true of most constants in C, so I 
think I'd skip it.

> +which can be used as arguments to the
> +.BR exit ()
> +function.
> +.SH CONFORMING TO
> +C99 and later;
> +POSIX.1-2001 and later.
> +.SH EXAMPLES
> +.\" SRC BEGIN (EXIT_SUCCESS.c)
> +.EX
> +#include <stdio.h>
> +#include <stdlib.h>
> +
> +int
> +main(int argc, char *argv[])
> +{
> +    FILE *fp;
> +
> +    if (argc != 2) {
> +        fprintf(stderr, "Usage: %s <file>\en", argv[0]);
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    if ((fp = fopen(argv[1], "r")) == NULL) {
> +        perror(argv[1]);
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    /* Other code omitted */

But please don't omit fclose(3).

> +
> +    exit(EXIT_SUCCESS);
> +}
> +.EE
> +.\" SRC END
> +.SH SEE ALSO
> +.BR exit (3)

Thanks!

Alex

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

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