From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 19878 invoked by alias); 18 Jul 2014 09:06:37 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 19754 invoked by uid 89); 18 Jul 2014 09:06:36 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.0 required=5.0 tests=AWL,BAYES_00,RP_MATCHES_RCVD,SPF_HELO_PASS,SPF_PASS autolearn=ham version=3.3.2 X-HELO: mx1.redhat.com Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-GCM-SHA384 encrypted) ESMTPS; Fri, 18 Jul 2014 09:06:34 +0000 Received: from int-mx09.intmail.prod.int.phx2.redhat.com (int-mx09.intmail.prod.int.phx2.redhat.com [10.5.11.22]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id s6I96V4i019315 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 18 Jul 2014 05:06:32 -0400 Received: from blade.nx (ovpn-116-94.ams2.redhat.com [10.36.116.94]) by int-mx09.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id s6I96U5X005278; Fri, 18 Jul 2014 05:06:31 -0400 Received: by blade.nx (Postfix, from userid 1000) id 51A9C2640C7; Fri, 18 Jul 2014 10:06:30 +0100 (BST) Date: Fri, 18 Jul 2014 09:20:00 -0000 From: Gary Benson To: Pedro Alves Cc: Doug Evans , gdb-patches , Tom Tromey Subject: Re: [PATCH 01/15 v3] Introduce common/errors.h Message-ID: <20140718090630.GA17917@blade.nx> References: <1405520243-17282-1-git-send-email-gbenson@redhat.com> <1405520243-17282-2-git-send-email-gbenson@redhat.com> <20140717134728.GB31916@blade.nx> <53C7E6AB.4080703@redhat.com> <20140717153957.GA1921@blade.nx> <53C7F5D6.6060102@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <53C7F5D6.6060102@redhat.com> X-IsSubscribed: yes X-SW-Source: 2014-07/txt/msg00490.txt.bz2 Pedro Alves wrote: > On 07/17/2014 04:39 PM, Gary Benson wrote: > > Pedro Alves wrote: > > > On 07/17/2014 02:47 PM, Gary Benson wrote: > > > > +/* Throw an error. The current operation will be aborted. The > > > > + message will be issued to the user. The application will > > > > + return to a state where it is accepting commands from the user. */ > > > > > > These comments aren't really true, though. We have plenty of > > > places catching errors with TRY_CATCH and proceeding without > > > returning to a state where we're accepting commands from the > > > user. > > > > How about "Throw an error. The current operation will be aborted. > > The application may catch and process the error, or, if not, the > > message will be issued to the user and the application will return > > to a state where it is accepting commands from the user." > > Still infers what the application does with the error. IMO, it's > best to describe the interface. Like: > > Throw a generic error. This function not return, instead > it executes a long jump, aborting the current operation. > The function takes printf-style arguments, which are used to > construct the error message. Surely "it executes a long jump" is describing what the application does with the error? Besides, it's not true for IPA, where error just calls exit (1). In the context of this whole file, you have: - warning (one type) - errors (three types) - special cases (perror_with_name, malloc_failure) The only difference between the three types of error is what the application does with them: - error (may be handled, may return to command level, may exit) - fatal (will exit) - internal_error (may return to command level, may exit) I don't think you can properly document these functions without spelling this out. Also, the documentation in this file is not just for callers of the functions, it has to document them for implementors too. How about the following? Cheers, Gary -- /* Display a warning message to the user. The message is constructed using a printf-style format string and a printf- or vprintf-style argument list. */ extern void warning (const char *fmt, ...) ATTRIBUTE_PRINTF (1, 2); extern void vwarning (const char *fmt, va_list args) ATTRIBUTE_PRINTF (1, 0); /* Throw a non-fatal error, constructing the message using a printf- style format string and a printf- or vprintf-style argument list. This function does not return. The application may attempt to handle the error. */ extern void error (const char *fmt, ...) ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 2); extern void verror (const char *fmt, va_list args) ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 0); /* Throw a non-fatal error, constructing the message by combining STRING with the system error message for errno. This function does not return. The application may attempt to handle the error. */ extern void perror_with_name (const char *string) ATTRIBUTE_NORETURN; /* Throw a fatal error, constructing the message using a printf-style format string and a printf- or vprintf-style argument list. This function does not return. The application will exit. */ extern void fatal (const char *fmt, ...) ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 2); extern void vfatal (const char *fmt, va_list args) ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (1, 0); /* Throw an internal error, constructing the message using a printf- style format string and a printf- or vprintf-style argument list. This function does not return. Internal errors indicate programming errors such as assertion failures, as opposed to more general errors the user may encounter. Internal errors are treated as fatal errors, except that the application may offer the user the choice to return to the command level rather than exiting. */ extern void internal_error (const char *file, int line, const char *fmt, ...) ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (3, 4); extern void internal_verror (const char *file, int line, const char *fmt, va_list args) ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (3, 0); /* A special case of internal error used to handle memory allocation failures. */ extern void malloc_failure (long size) ATTRIBUTE_NORETURN;