[PATCH v2 1/2] system_data_types.7: Add 'error_t'

[PATCH v2 1/2] system_data_types.7: Add 'error_t'

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 49ca2d8e1..4930aac8b 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -199,6 +199,45 @@ See also the
 .I float_t
 type in this page.
 .RE
+.\"------------------------------------- error_t ----------------------/
+.TP
+.I error_t
+.RS
+Include:
+.IR <argz.h> ,
+or
+.IR <envz.h> .
+Alternatively,
+.IR <errno.h> .
+.PP
+An integer type
+used for error reporting.
+A value of 0 means success, and nonzero means failure.
+Portable programs should use
+.I int
+instead.
+.PP
+Conforming to:
+Present in glibc.
+It is not standardized by the C language standard nor POSIX.
+.PP
+Notes:
+C11 standardized a similar type as an optional extension:
+.IR errno_t .
+However,
+.I errno_t
+is not present in POSIX.
+.PP
+.I <errno.h>
+defines this type if the macro
+.B _GNU_SOURCE
+is defined before including the header.
+.PP
+See also:
+.BR argz_add (3),
+.BR envz_add (3),
+.BR feature_test_macros (7)
+.RE
 .\"------------------------------------- fd_set -----------------------/
 .TP
 .I fd_set
-- 
2.28.0

[PATCH v2 2/2] error_t: New link to system_data_types(7)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/error_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/error_t.3

diff --git a/man3/error_t.3 b/man3/error_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/error_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

Re: [PATCH v2 2/2] error_t: New link to system_data_types(7)

[Alejandro Colomar]

Hi Michael,

I forgot '.3' in the page name in the commit message. Please add it.

Thanks,

Alex

On 2020-10-26 23:16, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>   man3/error_t.3 | 1 +
>   1 file changed, 1 insertion(+)
>   create mode 100644 man3/error_t.3
> 
> diff --git a/man3/error_t.3 b/man3/error_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/error_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> 

Re: [PATCH v2 1/2] system_data_types.7: Add 'error_t'

[Michael Kerrisk (man-pages)]

Hi Alex,

On 10/26/20 11:16 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>  man7/system_data_types.7 | 39 +++++++++++++++++++++++++++++++++++++++
>  1 file changed, 39 insertions(+)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 49ca2d8e1..4930aac8b 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -199,6 +199,45 @@ See also the
>  .I float_t
>  type in this page.
>  .RE
> +.\"------------------------------------- error_t ----------------------/
> +.TP
> +.I error_t
> +.RS
> +Include:
> +.IR <argz.h> ,
> +or
> +.IR <envz.h> .
> +Alternatively,
> +.IR <errno.h> .
> +.PP
> +An integer type
> +used for error reporting.
> +A value of 0 means success, and nonzero means failure.
> +Portable programs should use
> +.I int
> +instead.
> +.PP
> +Conforming to:
> +Present in glibc.
> +It is not standardized by the C language standard nor POSIX.
> +.PP
> +Notes:
> +C11 standardized a similar type as an optional extension:
> +.IR errno_t .
> +However,
> +.I errno_t
> +is not present in POSIX.
> +.PP
> +.I <errno.h>
> +defines this type if the macro
> +.B _GNU_SOURCE
> +is defined before including the header.
> +.PP
> +See also:
> +.BR argz_add (3),
> +.BR envz_add (3),
> +.BR feature_test_macros (7)
> +.RE
>  .\"------------------------------------- fd_set -----------------------/
>  .TP
>  .I fd_set


So, I must say that I am skeptical about adding this type to the page.
There is a trade-off between having useful info and creating a page
that becomes so large that it becomes unwieldy.

error_t is an obscure [1], nonstandard type used by two API sets
(one of which is roughly a special case of the other). I'm so far
unconvinced of the value of adding this typr to the page.

Cheers,

Michael

[1] Before Jonny Grant's mail yesterday, which I presume was 
the inspiration for this patch, I had either neither heard of
the type or at least long ago forgotten about it.

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH v2 1/2] system_data_types.7: Add 'error_t'

[Alejandro Colomar]

On 2020-10-27 06:49, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> On 10/26/20 11:16 PM, Alejandro Colomar wrote:
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>> ---
>>   man7/system_data_types.7 | 39 +++++++++++++++++++++++++++++++++++++++
>>   1 file changed, 39 insertions(+)
>>
>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
>> index 49ca2d8e1..4930aac8b 100644
>> --- a/man7/system_data_types.7
>> +++ b/man7/system_data_types.7
>> @@ -199,6 +199,45 @@ See also the
>>   .I float_t
>>   type in this page.
>>   .RE
>> +.\"------------------------------------- error_t ----------------------/
>> +.TP
>> +.I error_t
>> +.RS
>> +Include:
>> +.IR <argz.h> ,
>> +or
>> +.IR <envz.h> .
>> +Alternatively,
>> +.IR <errno.h> .
>> +.PP
>> +An integer type
>> +used for error reporting.
>> +A value of 0 means success, and nonzero means failure.
>> +Portable programs should use
>> +.I int
>> +instead.
>> +.PP
>> +Conforming to:
>> +Present in glibc.
>> +It is not standardized by the C language standard nor POSIX.
>> +.PP
>> +Notes:
>> +C11 standardized a similar type as an optional extension:
>> +.IR errno_t .
>> +However,
>> +.I errno_t
>> +is not present in POSIX.
>> +.PP
>> +.I <errno.h>
>> +defines this type if the macro
>> +.B _GNU_SOURCE
>> +is defined before including the header.
>> +.PP
>> +See also:
>> +.BR argz_add (3),
>> +.BR envz_add (3),
>> +.BR feature_test_macros (7)
>> +.RE
>>   .\"------------------------------------- fd_set -----------------------/
>>   .TP
>>   .I fd_set
> 
> 
> So, I must say that I am skeptical about adding this type to the page.
> There is a trade-off between having useful info and creating a page
> that becomes so large that it becomes unwieldy.
> 
> error_t is an obscure [1], nonstandard type used by two API sets
> (one of which is roughly a special case of the other). I'm so far
> unconvinced of the value of adding this typr to the page.

Hi Michael,

Agreed.

That type should never be used IMO,
so I guess the line you added should be enough.

Cheers,

Alex

> 
> Cheers,
> 
> Michael
> 
> [1] Before Jonny Grant's mail yesterday, which I presume was
> the inspiration for this patch, I had either neither heard of
> the type or at least long ago forgotten about it.
>