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

Alejandro Colomar
2022-11-16T22:06:50Z

[-- 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