Debian Bug report logs - #186307
manpages-dev: [WANTED] error(3) needs manpage

version graph

Package: manpages-dev; Maintainer for manpages-dev is Martin Schulze <joey@debian.org>; Source for manpages-dev is src:manpages.

Reported by: <herbert@gondor.apana.org.au>

Date: Wed, 26 Mar 2003 00:18:05 UTC

Severity: wishlist

Tags: fixed-upstream, help, patch, upstream

Found in version 1.48-2

Fixed in versions manpages/2.28-1, manpages/2.31-1

Done: Martin Schulze <joey@infodrom.org>

Bug is archived. No further changes may be made.

Toggle useless messages

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>, manpages@packages.qa.debian.org:
Bug#186307; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to <herbert@gondor.apana.org.au>:
New Bug report received and forwarded. Copy sent to Martin Schulze <joey@debian.org>, manpages@packages.qa.debian.org. Full text and rfc822 format available.

Message #5 received at submit@bugs.debian.org (full text, mbox):

From: <herbert@gondor.apana.org.au>
To: submit@bugs.debian.org
Subject: manpages-dev: error(3) and BSD err/warn need manpages
Date: Tue, 25 Mar 2003 22:43:10 +1100
Package: manpages-dev
Version: 1.48-2
Severity: wishlist

Please document the error(3) function and the other BSD err/warn
functions that are in the glibc info page.

-- System Information
Debian Release: testing/unstable
Kernel Version: Linux gondolin 2.4.20-1-686-smp #1 SMP Sat Mar 22 13:56:18 EST 2003 i686 Pentium III (Coppermine) GenuineIntel GNU/Linux

Versions of the packages manpages-dev depends on:
ii  manpages       1.48-2         Manual pages about using a GNU/Linux system



Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#186307; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Martin Schulze <joey@infodrom.org>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #10 received at 186307@bugs.debian.org (full text, mbox):

From: Martin Schulze <joey@infodrom.org>
To: Herbert Xu <herbert@gondor.apana.org.au>
Cc: 186307@bugs.debian.org
Subject: help
Date: Sun, 24 Aug 2003 11:14:44 +0200
tags 186307 + help
thanks

Added to the list of missing manpages.

Somebody needs to write those manpages...

       When writing manual pages please ensure that they are conforming with The Single
       UNIX Specification (see below).  Linux ought to be conforming to this specifica-
       tion.  Differences need to be documented, in additional sections, though.

[..]
       Single UNIXR Specification, Version 2, at <http://www.open-
       group.org/onlinepubs/7908799/>, the Single UNIX Specification, Version
       3, at <http://www.UNIX-systems.org/version3/>.

Regards,

	Joey

-- 
Those who don't understand Unix are condemned to reinvent it, poorly.

Please always Cc to me when replying to me on the lists.



Tags added: help Request was from Martin Schulze <joey@infodrom.org> to control@bugs.debian.org. Full text and rfc822 format available.

Message sent on to <herbert@gondor.apana.org.au>:
Bug#186307. Full text and rfc822 format available.

Message #15 received at 186307-submitter@bugs.debian.org (full text, mbox):

From: Justin Pryzby <justinpryzby@users.sourceforge.net>
To: 186307-submitter@bugs.debian.org
Subject: manpages-dev: error(3) and BSD err/warn need manpages
Date: Wed, 22 Jun 2005 10:05:51 -0400
Hi,

Some time ago, you requested manpages for "error(3) and err/warn".
err,errx,warn,warnx now have manpages.  But, what is error(3)?  Is it
a function?  Is it a manpage about error handling?  Is it supposed to
be "errno(3)"?

It might be the case that this report can be closed.  If so, you can
do so by responding to the message, and including
"186307-done@bugs.debian.org" as one of the recipients.

Thanks,
Justin



Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#186307; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Herbert Xu <herbert@gondor.apana.org.au>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #20 received at 186307@bugs.debian.org (full text, mbox):

From: Herbert Xu <herbert@gondor.apana.org.au>
To: Justin Pryzby <justinpryzby@users.sourceforge.net>, 186307@bugs.debian.org
Subject: Re: Bug#186307: manpages-dev: error(3) and BSD err/warn need manpages
Date: Thu, 23 Jun 2005 07:27:56 +1000
On Wed, Jun 22, 2005 at 10:05:51AM -0400, Justin Pryzby wrote:
> 
> Some time ago, you requested manpages for "error(3) and err/warn".
> err,errx,warn,warnx now have manpages.  But, what is error(3)?  Is it
> a function?  Is it a manpage about error handling?  Is it supposed to
> be "errno(3)"?

error(3) is a function declared in /usr/include/error.h.

Cheers,
-- 
Visit Openswan at http://www.openswan.org/
Email: Herbert Xu ~{PmV>HI~} <herbert@gondor.apana.org.au>
Home Page: http://gondor.apana.org.au/~herbert/
PGP Key: http://gondor.apana.org.au/~herbert/pubkey.txt



Changed Bug title. Request was from Justin Pryzby <justinpryzby@users.sourceforge.net> to control@bugs.debian.org. Full text and rfc822 format available.

Tags added: upstream Request was from Justin Pryzby <justinpryzby@users.sourceforge.net> to control@bugs.debian.org. Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#186307; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Justin Pryzby <justinpryzby@users.sourceforge.net>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #29 received at 186307@bugs.debian.org (full text, mbox):

From: Justin Pryzby <justinpryzby@users.sourceforge.net>
To: 186307@bugs.debian.org
Subject: Please also document error_at_line
Date: Sat, 21 Jan 2006 15:10:08 -0500
error.h:error_at_line



Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#186307; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Justin Pryzby <justinpryzby@users.sourceforge.net>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #34 received at 186307@bugs.debian.org (full text, mbox):

From: Justin Pryzby <justinpryzby@users.sourceforge.net>
To: 186307@bugs.debian.org
Cc: control@bugs.debian.org
Subject: manpage for error()
Date: Tue, 25 Apr 2006 13:47:30 -0400
tag 186307 patch
thanks

Included is a manpage for error().  Please consider including it.

.\" Copyright (C) 2006 Justin Pryzby <pryzbyj@justinpryzby.com>
.\" 
.\" Permission is hereby granted, free of charge, to any person obtaining
.\" a copy of this software and associated documentation files (the
.\" "Software"), to deal in the Software without restriction, including
.\" without limitation the rights to use, copy, modify, merge, publish,
.\" distribute, sublicense, and/or sell copies of the Software, and to
.\" permit persons to whom the Software is furnished to do so, subject to
.\" the following conditions:
.\" 
.\" The above copyright notice and this permission notice shall be
.\" included in all copies or substantial portions of the Software.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
.\"
.\" References:
.\"   glibc manual and source

.TH ERROR 3 "25 April 2006" GNU
.\" Please adjust this date whenever revising the manpage.

.SH NAME
error \- glibc error handling functions
.SH SYNOPSIS
\fBextern void error(int \fIstatus, \fBint\fI errnum, \fBconst char
*\fIformat, \fB ...);

\fBextern void error_at_line (int \fIstatus, \fBint \fIerrnum,
\fBconst char *\fIfname, \fBunsigned int \fIlineno, \fBconst char
*\fIformat, \fB...);

\fBextern unsigned int \fIerror_message_count\fP;

\fBextern void (* \fIerror_print_progname\fB) (void);

.SH DESCRIPTION
\fBerror\fP is a glibc\-specific error handling function.  It
outputs to stderr the program name, a colon, the message specified by
the printf format string \fIformat\fP, and, if \fIerrnum\fP is
nonzero, a second colon followed by the string given by
\fBperror(\fIerrnum\fB)\fR.  A newline is printed in all cases.

If \fIstatus\fP is set nonzero, then the program terminates with that
value as the exit status.

If \fBerror_one_per_line\fP is set nonzero, and the
\fBerror_at_line\fP variant is used, then a series of consecutive
errors with the same value of \fIfname\fP and \fIlineno\fP causes only
one message to be output.  The preprocessor values \fB__LINE__\fP and
\fB__FILE__\fP may be useful here, but other values can be used to
suppress other sets of messages.  For example, \fIfname\fP could be
the name of an input file being processed, rather than the name of the
source file.

\fIerror_message_count\fP is the count of times that
\fBerror\fP has been called.  This variable can be used to defer and
unify error handling for a large code block to a single common
handler.

If \fIerror_print_progname\fP is set nonnull, then it is called
instead of prefixing the message with the program name and colon.
Note that when \fIerror_print_progname\fP is unset, \fIstdout\fP is
cleared before printing to \fIstderr\fP.

.SH NOTES
If output from \fBerror\fP is supressed by \fBerror_one_per_line\fP, then
\fBerror_message_count\fP is not increased, but this seems to be
undocumented behaviour and could change in the future, so should not
be relied upon.

.SH "CONFORMING TO"
These functions and variables are GNU extensions, and should not be
used in programs intending to be portable.

.SH SEE ALSO
.BR errno (3),
.BR strerror (3),
.BR err (3),
.BR exit (3)
.br
The \fIGNU C Library Reference Manual\fP, available via the Info
system.

.SH AUTHOR
glibc is a product of the \fIFree Software Foundation\fP.
This manual page was written by Justin Pryzby
\fI<pryzbyj@justinpryzby.com>\fP.



Tags added: patch Request was from Justin Pryzby <justinpryzby@users.sourceforge.net> to control@bugs.debian.org. Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#186307; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Justin Pryzby <justinpryzby@users.sourceforge.net>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #41 received at 186307@bugs.debian.org (full text, mbox):

From: Justin Pryzby <justinpryzby@users.sourceforge.net>
To: 186307@bugs.debian.org
Subject: Re: manpage for error()
Date: Tue, 25 Apr 2006 14:47:50 -0400
On Tue, Apr 25, 2006 at 01:47:29PM -0400, pryzbyj wrote:
> tag 186307 patch
> thanks
> 
> Included is a manpage for error().  Please consider including it.
I forgot to #include <error.h>.  Please also add SEE ALSO back to
error in some relevant places: perhaps strerror, perror, err and
errno.

.SH SYNOPSIS
\fB#include <error.h>

Justin



Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#186307; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to "Michael Kerrisk" <mtk-manpages@gmx.net>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #46 received at 186307@bugs.debian.org (full text, mbox):

From: "Michael Kerrisk" <mtk-manpages@gmx.net>
To: Justin Pryzby <justinpryzby@users.sourceforge.net>,186307@bugs.debian.org
Cc: 186307@bugs.debian.org,control@bugs.debian.org
Subject: Re: Bug#186307: manpage for error()
Date: Fri, 28 Apr 2006 03:27:39 +0200 (MEST)
Justin,

Comments below:

> Included is a manpage for error().  Please consider including it.

I am considering it.

> .TH ERROR 3 "25 April 2006" GNU
> .\" Please adjust this date whenever revising the manpage.

No need for that last line.

> .SH NAME
> error \- glibc error handling functions
> .SH SYNOPSIS
> \fBextern void error(int \fIstatus, \fBint\fI errnum, \fBconst char
> *\fIformat, \fB ...);
> 
> \fBextern void error_at_line (int \fIstatus, \fBint \fIerrnum,
> \fBconst char *\fIfname, \fBunsigned int \fIlineno, \fBconst char
> *\fIformat, \fB...);
> 
> \fBextern unsigned int \fIerror_message_count\fP;
> 
> \fBextern void (* \fIerror_print_progname\fB) (void);
> 
> .SH DESCRIPTION
> \fBerror\fP 

For functions, write with "()", thus "error()".
Please read my HOWTOHELP doc, which points you at 
fcntl.2 as an example of how things should be done.

> is a glibc\-specific error handling function.  

You already say that it is glibc specific elsewhere.  I will cut that.

> It
> outputs to stderr the program name, a colon, the message specified by
> the printf format string \fIformat\fP, and, if \fIerrnum\fP is
> nonzero, a second colon followed by the string given by
> \fBperror(\fIerrnum\fB)\fR.  A newline is printed in all cases.
> 
> If \fIstatus\fP is set nonzero, then the program terminates with that
> value as the exit status.
> 
> If \fBerror_one_per_line\fP is set nonzero, and the
> \fBerror_at_line\fP variant is used, then a series of consecutive
> errors with the same value of \fIfname\fP and \fIlineno\fP causes only
> one message to be output.  The preprocessor values \fB__LINE__\fP and
> \fB__FILE__\fP may be useful here, but other values can be used to
> suppress other sets of messages.  For example, \fIfname\fP could be
> the name of an input file being processed, rather than the name of the
> source file.
> 
> \fIerror_message_count\fP is the count of times that
> \fBerror\fP has been called.  

Actually counts number of messages printed.

> This variable can be used to defer and
> unify error handling for a large code block to a single common
> handler.

I'm not sure what you are meaning with the above.  Please explain.

> If \fIerror_print_progname\fP is set nonnull, then it is called
> instead of prefixing the message with the program name and colon.

> Note that when \fIerror_print_progname\fP is unset, \fIstdout\fP is
> cleared before printing to \fIstderr\fP.

Where so you glean this piece of information from?

> .SH NOTES
> If output from \fBerror\fP is supressed by \fBerror_one_per_line\fP, then
> \fBerror_message_count\fP is not increased, but this seems to be
> undocumented behaviour and could change in the future, so should not
> be relied upon.

I would probably write this differently.  I think the glibc
page is simply unclear.  i think it means just to say that this
variable counts the number of messages.

> .SH "CONFORMING TO"
> These functions and variables are GNU extensions, and should not be
> used in programs intending to be portable.

Cheers,

Michael

-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 

Want to help with man page maintenance?  
Grab the latest tarball at
ftp://ftp.win.tue.nl/pub/linux-local/manpages/, 
read the HOWTOHELP file and grep the source 
files for 'FIXME'.



Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#186307; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to "Michael Kerrisk" <mtk-manpages@gmx.net>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#186307; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Justin Pryzby <justinpryzby@users.sourceforge.net>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #56 received at 186307@bugs.debian.org (full text, mbox):

From: Justin Pryzby <justinpryzby@users.sourceforge.net>
To: Michael Kerrisk <mtk-manpages@gmx.net>
Cc: 186307@bugs.debian.org
Subject: Re: Bug#186307: manpage for error()
Date: Thu, 27 Apr 2006 21:55:34 -0400
On Fri, Apr 28, 2006 at 03:27:39AM +0200, Michael Kerrisk wrote:
> Justin,
> 
> Comments below:
> 
> > Included is a manpage for error().  Please consider including it.
> 
> I am considering it.
> 
> > .TH ERROR 3 "25 April 2006" GNU
> > .\" Please adjust this date whenever revising the manpage.
> 
> No need for that last line.
It was in the Debian manpage template :)

> > .SH DESCRIPTION
> > \fBerror\fP 
> 
> For functions, write with "()", thus "error()".
> Please read my HOWTOHELP doc, which points you at 
> fcntl.2 as an example of how things should be done.
Ah, I've read it before but am rereading it now.

> > \fIerror_message_count\fP is the count of times that
> > \fBerror\fP has been called.  
> 
> Actually counts number of messages printed.
This probably is more clear, though the ambiguity in documentation
should be noted.

> > This variable can be used to defer and
> > unify error handling for a large code block to a single common
> > handler.
> 
> I'm not sure what you are meaning with the above.  Please explain.
I think I got this idea from the glibc example program.  Consider
ferror(), which allows you to do a whole bunch of stuff on a FILE*
without checking individual function calls for error, and then test
whether they all succeeded with ferror(), and handle it at once.
error() can do the same thing, kind of.  You still have to do some
kind of conditionals around the function calls, but you can do the
more elaborate error message in one place.  I guess you can do this
anyway with a custom any_err=0, but I was trying to preserve the
interesting usage example.  It could be omitted.

> > If \fIerror_print_progname\fP is set nonnull, then it is called
> > instead of prefixing the message with the program name and colon.
> 
> > Note that when \fIerror_print_progname\fP is unset, \fIstdout\fP is
> > cleared before printing to \fIstderr\fP.
> 
> Where so you glean this piece of information from?
The header file, /usr/include/error.h.

Should I send a tweaked manpage?

Justin



Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#186307; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to "Michael Kerrisk" <mtk-manpages@gmx.net>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #61 received at 186307@bugs.debian.org (full text, mbox):

From: "Michael Kerrisk" <mtk-manpages@gmx.net>
To: Justin Pryzby <justinpryzby@users.sourceforge.net>
Cc: 186307@bugs.debian.org
Subject: Re: Bug#186307: manpage for error()
Date: Fri, 28 Apr 2006 06:42:51 +0200 (MEST)
Justin,

> > Comments below:
> > 
> > > Included is a manpage for error().  Please consider including it.
> > 
> > I am considering it.
> > 
> > > .TH ERROR 3 "25 April 2006" GNU
> > > .\" Please adjust this date whenever revising the manpage.
> > 
> > No need for that last line.
> It was in the Debian manpage template :)

Oh.  Kind of redundant really.

> > > This variable can be used to defer and
> > > unify error handling for a large code block to a single common
> > > handler.
> > 
> > I'm not sure what you are meaning with the above.  Please explain.
> I think I got this idea from the glibc example program.  Consider
> ferror(), which allows you to do a whole bunch of stuff on a FILE*
> without checking individual function calls for error, and then test
> whether they all succeeded with ferror(), and handle it at once.
> error() can do the same thing, kind of.  You still have to do some
> kind of conditionals around the function calls, but you can do the
> more elaborate error message in one place.  I guess you can do this
> anyway with a custom any_err=0, but I was trying to preserve the
> interesting usage example.  It could be omitted.

Yes -- I think I will cut it.

> > > If \fIerror_print_progname\fP is set nonnull, then it is called
> > > instead of prefixing the message with the program name and colon.
> > 
> > > Note that when \fIerror_print_progname\fP is unset, \fIstdout\fP is
> > > cleared before printing to \fIstderr\fP.
> > 
> > Where so you glean this piece of information from?
> The header file, /usr/include/error.h.

Ahh -- I see it now.  But the header file comment isn't right: the 
code always flushes stdout, regardless of the setting of 
error_print_progname.

> Should I send a tweaked manpage?

Not at this stage.  I'm editing.

Cheers,

Michael

-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 

Want to help with man page maintenance?  
Grab the latest tarball at
ftp://ftp.win.tue.nl/pub/linux-local/manpages/, 
read the HOWTOHELP file and grep the source 
files for 'FIXME'.



Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#186307; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to "Michael Kerrisk" <mtk-manpages@gmx.net>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #66 received at 186307@bugs.debian.org (full text, mbox):

From: "Michael Kerrisk" <mtk-manpages@gmx.net>
To: Justin Pryzby <justinpryzby@users.sourceforge.net>
Cc: 186307@bugs.debian.org,control@bugs.debian.org
Subject: Re: Bug#186307: manpage for error()
Date: Fri, 28 Apr 2006 07:55:44 +0200 (MEST)
tags 186307 fixed-upstream
thanks

Justin,

Below is the draft that I have added to 2.31.  I added and changed
quite a few thinbgs.  If you see anything to fix, let me know.

Thanks for the page.

Cheers,

Michael


.\" Copyright (C) 2006 Justin Pryzby <pryzbyj@justinpryzby.com>
.\" and Copyright (C) 2006 Michael Kerrisk <mtk-manpages@gmx.net>
.\"
.\" Permission is hereby granted, free of charge, to any person obtaining
.\" a copy of this software and associated documentation files (the
.\" "Software"), to deal in the Software without restriction, including
.\" without limitation the rights to use, copy, modify, merge, publish,
.\" distribute, sublicense, and/or sell copies of the Software, and to
.\" permit persons to whom the Software is furnished to do so, subject to
.\" the following conditions:
.\"
.\" The above copyright notice and this permission notice shall be
.\" included in all copies or substantial portions of the Software.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
.\"
.\" References:
.\"   glibc manual and source
.TH ERROR 3 "2006-04-25" GNU
.SH NAME
error, error_at_line, error_message_count, error_on_per_line, \
error_print_progname \- glibc error reporting functions
.SH SYNOPSIS
.nf
.. #include <error.h>

\fBvoid error(int \fIstatus, \fBint\fI errnum, \
\fBconst char *\fIformat, \fB...);

\fBvoid error_at_line(int \fIstatus, \fBint \fIerrnum, \
\fBconst char *\fIfilename,
                   \fBunsigned int \fIlinenum, \
\fBconst char *\fIformat, \fB...);

\fBextern unsigned int \fIerror_message_count\fP;

\fBextern int \fIerror_one_per_line\fP;

\fBextern void (* \fIerror_print_progname\fB) (void);
.fi
.SH DESCRIPTION
\fBerror\fP() is a general error reporting function.
It flushes
.IR stdout ,
and then outputs to
.I stderr
the program name, a colon and a space, the message specified by the
.BR printf(3) -style
format string \fIformat\fP, and, if \fIerrnum\fP is
non-zero, a second colon and a space followed by the string given by
\fBperror(\fIerrnum\fB)\fR.
Any arguments required for
.I format
should follow
.I format
in the argument list.
The output is terminated by a newline character.

The program name printed by
.BR error ()
is the value of the global variable
.IR program_invocation_name
(which initially has the same value as
.IR main ()'s
.IR argv[0] ),
declared as
.IR "extern char *program_invocation_name"
in
.IR <errno.h>
if the feature test macro _GNU_SOURCE is defined.
The value of this variable can be modified to change the output of
.BR error ().

If \fIstatus\fP has a non-zero value, then
.BR error ()
calls
.BR exit (3)
to terminate the program using the given value as the exit status.

The \fBerror_at_line\fP() function is exactly the same as \fBerror\fP(),
except for the addition of the arguments
.I filename
and
.IR linenum .
The output produced is as for
.BR error (),
except that after the program name are written: a colon, the value of
.IR filename ,
a colon, and the value of
.IR linenum .
The preprocessor values \fB__LINE__\fP and
\fB__FILE__\fP may be useful when calling \fBerror_at_line\fP(),
but other values can also be used.
For example, these arguments could refer to a location in an input file.

If global variable \fIerror_one_per_line\fP is set non-zero,
a sequence of
\fBerror_at_line\fP() calls with the
the same value of \fIfilename\fP and \fIlinenum\fP will result in only
one message (the first) being output.

The global variable \fIerror_message_count\fP counts the number of
messages that have been output by
\fBerror\fP() and \fBerror_at_line\fP().

If the global variable \fIerror_print_progname\fP
is assigned the address of a function
(i.e., is not NULL), then that function is called
instead of prefixing the message with the program name and colon.
The function should print a suitable string to
.IR stderr .
.SH "CONFORMING TO"
These functions and variables are GNU extensions, and should not be
used in programs intended to be portable.
.SH SEE ALSO
.BR errno (3),
.BR perror (3),
.BR strerror (3),
.BR err (3),
.BR exit (3)



-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 

Want to help with man page maintenance?  
Grab the latest tarball at
ftp://ftp.win.tue.nl/pub/linux-local/manpages/, 
read the HOWTOHELP file and grep the source 
files for 'FIXME'.



Tags added: fixed-upstream Request was from "Michael Kerrisk" <mtk-manpages@gmx.net> to control@bugs.debian.org. Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#186307; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to Justin Pryzby <justinpryzby@users.sourceforge.net>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #73 received at 186307@bugs.debian.org (full text, mbox):

From: Justin Pryzby <justinpryzby@users.sourceforge.net>
To: Michael Kerrisk <mtk-manpages@gmx.net>, 186307@bugs.debian.org
Subject: Re: Bug#186307: manpage for error()
Date: Fri, 28 Apr 2006 12:17:11 -0400
On Fri, Apr 28, 2006 at 07:55:44AM +0200, Michael Kerrisk wrote:
> tags 186307 fixed-upstream
> thanks
> 
> Justin,
> 
> Below is the draft that I have added to 2.31.  I added and changed
> quite a few thinbgs.  If you see anything to fix, let me know.

Your #include is missing in the formatted output.

> .SH NAME
> error, error_at_line, error_message_count, error_on_per_line, \
> error_print_progname \- glibc error reporting functions
Thanks, mentioning multiple things was the next bit to add; you might
consider also adding program_invocation_name, but perhaps not..

> \fBconst char *\fIfilename,
Did you intend to add a trailing backslash to this line too?

> The program name printed by
> .BR error ()
> is the value of the global variable
> .IR program_invocation_name
> (which initially has the same value as
> .IR main ()'s
> .IR argv[0] ),
> declared as
> .IR "extern char *program_invocation_name"
> in
> .IR <errno.h>
> if the feature test macro _GNU_SOURCE is defined.
This is a "run on" sentence, and should be somehow split up.  This
could perhaps be done at the same time as making a separate sentence
for p-i-n, justifying this as its manpage (although it is declared in
a different header file, so I don't know if I like it..).

{ The program name printed by
{ .BR error ()
{ is the value of the global variable
{ .IR program_invocation_name.

{ .IR program_invocation_name has the the same initial value as
{ .IR main ()'s
{ .IR argv[0] ), and is
{ declared as
{ .IR "extern char *program_invocation_name"
{ in
{ .IR <errno.h>
{ if the feature test macro _GNU_SOURCE is defined.

If you like, I'll patch errno.3 for this, or write a new manpage
(ugh).

> .I filename
> and
> .IR linenum .
> The output produced is as for
> .BR error (),
> except that after the program name are written: a colon, the value of
A better english phrase would be:
  except that the output is: the program name, a colon, the value of

> The global variable \fIerror_message_count\fP counts the number of
> messages that have been output by
> \fBerror\fP() and \fBerror_at_line\fP().
Could you document that the glibc manual is, at best, unclear about
the value of that variable?  (Lines printed, not times called)

> .SH SEE ALSO
> .BR errno (3),
> .BR perror (3),
> .BR strerror (3),
> .BR err (3),
> .BR exit (3)
Could we keep the reference to the glibc manual?  Could you also add
some SEE ALSOs back to error()?

Thanks
Justin



Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#186307; Package manpages-dev. Full text and rfc822 format available.

Acknowledgement sent to "Michael Kerrisk" <mtk-manpages@gmx.net>:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. Full text and rfc822 format available.

Message #78 received at 186307@bugs.debian.org (full text, mbox):

From: "Michael Kerrisk" <mtk-manpages@gmx.net>
To: Justin Pryzby <justinpryzby@users.sourceforge.net>
Cc: 186307@bugs.debian.org
Subject: Re: Bug#186307: manpage for error()
Date: Fri, 28 Apr 2006 21:03:21 +0200 (MEST)
Justin,

> > Below is the draft that I have added to 2.31.  I added and changed
> > quite a few thinbgs.  If you see anything to fix, let me know.
> 
> Your #include is missing in the formatted output.

Thanks.  Fixed now.

> > .SH NAME
> > error, error_at_line, error_message_count, error_on_per_line, \
> > error_print_progname \- glibc error reporting functions
> Thanks, mentioning multiple things was the next bit to add; 

Best to send me a first draft that is as complete as you 
can reasonably make it...

Also, the other thing to add was new link files.

> you might
> consider also adding program_invocation_name, but perhaps not..

Doesn't really belong on this page...

> > \fBconst char *\fIfilename,
> Did you intend to add a trailing backslash to this line too?

No.  (Try adding one and see how the output looks...)

> > The program name printed by
> > .BR error ()
> > is the value of the global variable
> > .IR program_invocation_name
> > (which initially has the same value as
> > .IR main ()'s
> > .IR argv[0] ),
> > declared as
> > .IR "extern char *program_invocation_name"
> > in
> > .IR <errno.h>
> > if the feature test macro _GNU_SOURCE is defined.
> This is a "run on" sentence, and should be somehow split up.  This
> could perhaps be done at the same time as making a separate sentence
> for p-i-n, justifying this as its manpage 

Agreed; it is overly complex.  I've broken it up.

> (although it is declared in
> a different header file, so I don't know if I like it..).

I don't like it.

> { The program name printed by
> { .BR error ()
> { is the value of the global variable
> { .IR program_invocation_name.
> 
> { .IR program_invocation_name has the the same initial value as
> { .IR main ()'s
> { .IR argv[0] ), and is
> { declared as
> { .IR "extern char *program_invocation_name"
> { in
> { .IR <errno.h>
> { if the feature test macro _GNU_SOURCE is defined.

Thanks.

> If you like, I'll patch errno.3 for this, or write a new manpage
> (ugh).

Patching errno would not be the place for this.  I have written a new
page.

> > .I filename
> > and
> > .IR linenum .
> > The output produced is as for
> > .BR error (),
> > except that after the program name are written: a colon, the value of
> A better english phrase would be:
>   except that the output is: the program name, a colon, the value of

Why better?  My phrase there seems perfectly grammatical.  So
is yours, but it drops some information aboyut the location of 
the output.

> > The global variable \fIerror_message_count\fP counts the number of
> > messages that have been output by
> > \fBerror\fP() and \fBerror_at_line\fP().
> Could you document that the glibc manual is, at best, unclear about
> the value of that variable?  (Lines printed, not times called)

No.  File a bug report to the glibc folks.

> > .SH SEE ALSO
> > .BR errno (3),
> > .BR perror (3),
> > .BR strerror (3),
> > .BR err (3),
> > .BR exit (3)
> Could we keep the reference to the glibc manual?  

No -- it is generally assumed.  I don't write that on 
every .3 man page.

> Could you also add some SEE ALSOs back to error()?

Already done.

Thanks for your comments.

Cheers,

Michael

-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 

Want to help with man page maintenance?  
Grab the latest tarball at
ftp://ftp.win.tue.nl/pub/linux-local/manpages/, 
read the HOWTOHELP file and grep the source 
files for 'FIXME'.



Reply sent to Martin Schulze <joey@infodrom.org>:
You have taken responsibility. Full text and rfc822 format available.

Notification sent to <herbert@gondor.apana.org.au>:
Bug acknowledged by developer. Full text and rfc822 format available.

Message #83 received at 186307-close@bugs.debian.org (full text, mbox):

From: Martin Schulze <joey@infodrom.org>
To: 186307-close@bugs.debian.org
Subject: Bug#186307: fixed in manpages 2.28-1
Date: Sun, 30 Apr 2006 03:02:14 -0700
Source: manpages
Source-Version: 2.28-1

We believe that the bug you reported is fixed in the latest version of
manpages, which is due to be installed in the Debian FTP archive:

manpages-dev_2.28-1_all.deb
  to pool/main/m/manpages/manpages-dev_2.28-1_all.deb
manpages_2.28-1.diff.gz
  to pool/main/m/manpages/manpages_2.28-1.diff.gz
manpages_2.28-1.dsc
  to pool/main/m/manpages/manpages_2.28-1.dsc
manpages_2.28-1_all.deb
  to pool/main/m/manpages/manpages_2.28-1_all.deb
manpages_2.28.orig.tar.gz
  to pool/main/m/manpages/manpages_2.28.orig.tar.gz



A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 186307@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Martin Schulze <joey@infodrom.org> (supplier of updated manpages package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@debian.org)


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Format: 1.7
Date: Sun, 30 Apr 2006 11:55:26 +0200
Source: manpages
Binary: manpages manpages-dev
Architecture: source all
Version: 2.28-1
Distribution: unstable
Urgency: low
Maintainer: Martin Schulze <joey@debian.org>
Changed-By: Martin Schulze <joey@infodrom.org>
Description: 
 manpages   - Manual pages about using a GNU/Linux system
 manpages-dev - Manual pages about using GNU/Linux for development
Closes: 186307 205238 306121 326564 348038 348930 351834 360166 360625 363518 365112 365338
Changes: 
 manpages (2.28-1) unstable; urgency=low
 .
   * New upstream source
     - Removed reference to core(5) (closes: Bug#360166)
     - Corrected the reference from ppoll(2) to poll(2) (closes: Bug#365338)
   * Document EBUSY better in rmdir(2) to reflect the situation on Linux
     (closes: Bug#205238)
   * Removed readv(3) and writev(3) since they were moved into section 2 a
     while ago (closes: Bug#326564)
   * Use upstream version of clog10(3)
   * Untypo fenv(3)
   * Added a note to nl_langinfo(3) that setlocale(3) needs to be called
     first (closes: Bug#351834)
   * Deactivated set_mempolicy(2) since the interface is provided and
     documented in numactl (closes: Bug#360625)
   * Removed superflous line in ld.so(8) (closes: Bug#365112)
   * Added information about BROWSER to environ(5) (closes: Bug#348930)
   * Improved the description of tmpfile(3) (closes: Bug#363518)
   * Added error(3) by Justin Pryzby (closes: Bug#186307)
   * Added the MIT license for the new error(3) manpage
   * Install upstream Changes files (closes: Bug#306121, Bug#348038)
   * Added argp_parse to missing(7) (Bug#349388)
Files: 
 7a9bcbb2ef6a7199f7ab70d7300059b9 586 doc - manpages_2.28-1.dsc
 997fcdb108d776c8c80664321d191e51 1141760 doc - manpages_2.28.orig.tar.gz
 22840abb92e0ab1fabe5d8e9e86ec5b5 49127 doc - manpages_2.28-1.diff.gz
 8bb7708ed7f2824ce38422df14766555 461352 doc important manpages_2.28-1_all.deb
 dc2085ce707cd12b19fe8ad92c3a1da9 1173348 doc standard manpages-dev_2.28-1_all.deb

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.2 (GNU/Linux)

iD8DBQFEVIpjW5ql+IAeqTIRAv0/AKCPKCiCHX+c2W3R4yqG9xjgWAkLKACghYoT
yYUWar29TcdPRDdOJc+hrQ0=
=3nJs
-----END PGP SIGNATURE-----




Reply sent to Martin Schulze <joey@infodrom.org>:
You have taken responsibility. Full text and rfc822 format available.

Notification sent to <herbert@gondor.apana.org.au>:
Bug acknowledged by developer. Full text and rfc822 format available.

Message #88 received at 186307-close@bugs.debian.org (full text, mbox):

From: Martin Schulze <joey@infodrom.org>
To: 186307-close@bugs.debian.org
Subject: Bug#186307: fixed in manpages 2.31-1
Date: Tue, 30 May 2006 00:47:13 -0700
Source: manpages
Source-Version: 2.31-1

We believe that the bug you reported is fixed in the latest version of
manpages, which is due to be installed in the Debian FTP archive:

manpages-dev_2.31-1_all.deb
  to pool/main/m/manpages/manpages-dev_2.31-1_all.deb
manpages_2.31-1.diff.gz
  to pool/main/m/manpages/manpages_2.31-1.diff.gz
manpages_2.31-1.dsc
  to pool/main/m/manpages/manpages_2.31-1.dsc
manpages_2.31-1_all.deb
  to pool/main/m/manpages/manpages_2.31-1_all.deb
manpages_2.31.orig.tar.gz
  to pool/main/m/manpages/manpages_2.31.orig.tar.gz



A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 186307@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Martin Schulze <joey@infodrom.org> (supplier of updated manpages package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@debian.org)


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Format: 1.7
Date: Tue, 30 May 2006 09:10:05 +0200
Source: manpages
Binary: manpages manpages-dev
Architecture: source all
Version: 2.31-1
Distribution: unstable
Urgency: low
Maintainer: Martin Schulze <joey@debian.org>
Changed-By: Martin Schulze <joey@infodrom.org>
Description: 
 manpages   - Manual pages about using a GNU/Linux system
 manpages-dev - Manual pages about using GNU/Linux for development
Closes: 186307 363518
Changes: 
 manpages (2.31-1) unstable; urgency=low
 .
   * New upstream source
     . New page describing error() and error_at_line (closes: Bug#186307)
     . Fixed DESCRIPTION of tmpfile(3) (closes: Bug#363518)
Files: 
 69312c1f0218818b34e567c12c60e800 584 doc - manpages_2.31-1.dsc
 c524a2729cd2e5d60172007f377925f4 1164421 doc - manpages_2.31.orig.tar.gz
 aa08dc399601b9388710ba8dd38bdd98 48268 doc - manpages_2.31-1.diff.gz
 3e1976d2712dafcaa08ee940f740c9f8 472478 doc important manpages_2.31-1_all.deb
 a5822577ee1cbe1ed375d994e7509bbd 1194956 doc standard manpages-dev_2.31-1_all.deb

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (GNU/Linux)

iD8DBQFEe/TOW5ql+IAeqTIRAvVXAJ96iBRfY4OUqgZqeKFHJZ1vbLE8KgCcC3Yo
u/peV0WfwbVZpgu8K8UcPx8=
=EmYc
-----END PGP SIGNATURE-----




Bug archived. Request was from Debbugs Internal Request <owner@bugs.debian.org> to internal_control@bugs.debian.org. (Sun, 24 Jun 2007 11:52:26 GMT) Full text and rfc822 format available.

Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Mon Apr 21 09:48:34 2014; Machine Name: beach.debian.org

Debian Bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.