| com_err.texinfo (5623) | com_err.texinfo (22176) |
|---|---|
| 1\input texinfo @c -*-texinfo-*- 2 | 1\input texinfo @c -*-texinfo-*- 2 |
| 3@c $Header$ 4@c $Source$ 5@c $Locker$ | 3@c $Header: /home/ncvs/src/lib/libcom_err/doc/com_err.texinfo,v 1.1.1.1 1995/01/14 22:23:41 wollman Exp $ 4@c $Source: /home/ncvs/src/lib/libcom_err/doc/com_err.texinfo,v $ |
| 6 7@c Note that although this source file is in texinfo format (more 8@c or less), it is not yet suitable for turning into an ``info'' 9@c file. Sorry, maybe next time. 10@c 11@c In order to produce hardcopy documentation from a texinfo file, 12@c run ``tex com_err.texinfo'' which will load in texinfo.tex, 13@c provided in this distribution. (texinfo.tex is from the Free --- 9 unchanged lines hidden (view full) --- 23 24@c Mutate section headers... 25@begingroup 26 @catcode#=6 27 @gdef@secheading#1#2#3{@secheadingi {#3@enspace #1}} 28@endgroup 29@end iftex 30 | 5 6@c Note that although this source file is in texinfo format (more 7@c or less), it is not yet suitable for turning into an ``info'' 8@c file. Sorry, maybe next time. 9@c 10@c In order to produce hardcopy documentation from a texinfo file, 11@c run ``tex com_err.texinfo'' which will load in texinfo.tex, 12@c provided in this distribution. (texinfo.tex is from the Free --- 9 unchanged lines hidden (view full) --- 22 23@c Mutate section headers... 24@begingroup 25 @catcode#=6 26 @gdef@secheading#1#2#3{@secheadingi {#3@enspace #1}} 27@endgroup 28@end iftex 29 |
| 30@c %**start of header (This is for running Texinfo on a region.) |
|
| 31@setfilename com_err 32@settitle A Common Error Description Library for UNIX | 31@setfilename com_err 32@settitle A Common Error Description Library for UNIX |
| 33@c %**end of header (This is for running Texinfo on a region.) |
|
| 33 34@ifinfo 35This file documents the use of the Common Error Description library. 36 37Copyright (C) 1987, 1988 Student Information Processing Board of the 38Massachusetts Institute of Technology. 39 40Permission to use, copy, modify, and distribute this software and its --- 68 unchanged lines hidden (view full) --- 109 110Note that the file texinfo.tex, provided with this distribution, is from 111the Free Software Foundation, and is under different copyright restrictions 112from the remainder of this package. 113 114@end titlepage 115 116@ifinfo | 34 35@ifinfo 36This file documents the use of the Common Error Description library. 37 38Copyright (C) 1987, 1988 Student Information Processing Board of the 39Massachusetts Institute of Technology. 40 41Permission to use, copy, modify, and distribute this software and its --- 68 unchanged lines hidden (view full) --- 110 111Note that the file texinfo.tex, provided with this distribution, is from 112the Free Software Foundation, and is under different copyright restrictions 113from the remainder of this package. 114 115@end titlepage 116 117@ifinfo |
| 117@c should put a menu here someday.... | 118@node Top, Why com_err?, (dir), (dir) 119@comment node-name, next, previous, up 120@top General Introduction 121 122@menu 123* Why com_err?:: What is all this for? 124* Error codes:: What's an error code, anyway? 125* Error table source file:: How to describe an error table. 126* The error-table compiler:: How to compile the table. 127* Run-time support routines:: How to use from within your program. 128* Coding Conventions:: Stylistic issues. 129* Building and Installation:: How to build and install. 130* Bug Reports:: You have found a bug? Report it. 131* Acknowledgements:: Whom to thank... 132 133@end menu 134 |
| 118@end ifinfo 119 120@page 121 | 135@end ifinfo 136 137@page 138 |
| 139@ifinfo 140@node Why com_err?, Error codes, Top, (dir) 141@comment node-name, next, previous, up 142@end ifinfo 143 |
|
| 122@section Why com_err? 123 124In building application software packages, a programmer often has to 125deal with a number of libraries, each of which can use a different 126error-reporting mechanism. Sometimes one of two values is returned, 127indicating simply SUCCESS or FAILURE, with no description of errors 128encountered. Sometimes it is an index into a table of text strings, 129where the name of the table used is dependent on the library being --- 19 unchanged lines hidden (view full) --- 149table. The library using this error table need only call a routine 150generated from this error-table source to make the table ``known'' to the 151com_err library, and any error code the library generates can be converted 152to the corresponding error message. There is also a default format for 153error codes accidentally returned before making the table known, which is 154of the form @samp{unknown code foo 32}, where @samp{foo} would be the name 155of the table. 156 | 144@section Why com_err? 145 146In building application software packages, a programmer often has to 147deal with a number of libraries, each of which can use a different 148error-reporting mechanism. Sometimes one of two values is returned, 149indicating simply SUCCESS or FAILURE, with no description of errors 150encountered. Sometimes it is an index into a table of text strings, 151where the name of the table used is dependent on the library being --- 19 unchanged lines hidden (view full) --- 171table. The library using this error table need only call a routine 172generated from this error-table source to make the table ``known'' to the 173com_err library, and any error code the library generates can be converted 174to the corresponding error message. There is also a default format for 175error codes accidentally returned before making the table known, which is 176of the form @samp{unknown code foo 32}, where @samp{foo} would be the name 177of the table. 178 |
| 179@ifinfo 180@node Error codes, Error table source file, Why com_err?, (dir) 181@comment node-name, next, previous, up 182@end ifinfo 183 |
|
| 157@section Error codes 158 159Error codes themselves are 32 bit (signed) integers, of which the high 160order 24 bits are an identifier of which error table the error code is 161from, and the low order 8 bits are a sequential error number within 162the table. An error code may thus be easily decomposed into its component 163parts. Only the lowest 32 bits of an error code are considered significant 164on systems which support wider values. --- 12 unchanged lines hidden (view full) --- 177 178Any variable which is to contain an error code should be declared @t{long}. 179The draft proposed American National Standard for C (as of May, 1988) 180requires that @t{long} variables be at least 32 bits; any system which does 181not support 32-bit @t{long} values cannot make use of this package (nor 182much other software that assumes an ANSI-C environment base) without 183significant effort. 184 | 184@section Error codes 185 186Error codes themselves are 32 bit (signed) integers, of which the high 187order 24 bits are an identifier of which error table the error code is 188from, and the low order 8 bits are a sequential error number within 189the table. An error code may thus be easily decomposed into its component 190parts. Only the lowest 32 bits of an error code are considered significant 191on systems which support wider values. --- 12 unchanged lines hidden (view full) --- 204 205Any variable which is to contain an error code should be declared @t{long}. 206The draft proposed American National Standard for C (as of May, 1988) 207requires that @t{long} variables be at least 32 bits; any system which does 208not support 32-bit @t{long} values cannot make use of this package (nor 209much other software that assumes an ANSI-C environment base) without 210significant effort. 211 |
| 212@ifinfo 213@node Error table source file, The error-table compiler, Error codes, (dir) 214@comment node-name, next, previous, up 215@end ifinfo 216 |
|
| 185@section Error table source file 186 187The error table source file begins with the declaration of the table name, 188as 189 190@example 191error_table @var{tablename} 192@end example --- 21 unchanged lines hidden (view full) --- 214 215 ec DSC_BAD_MODES, 216 "Invalid mode for this access control list" 217 218 end 219 220@end example 221 | 217@section Error table source file 218 219The error table source file begins with the declaration of the table name, 220as 221 222@example 223error_table @var{tablename} 224@end example --- 21 unchanged lines hidden (view full) --- 246 247 ec DSC_BAD_MODES, 248 "Invalid mode for this access control list" 249 250 end 251 252@end example 253 |
| 254@ifinfo 255@node The error-table compiler, Run-time support routines, Error table source file, (dir) 256@comment node-name, next, previous, up 257@end ifinfo 258 |
|
| 222@section The error-table compiler 223 224The error table compiler is named @code{compile_et}. It takes one 225argument, the pathname of a file (ending in @samp{.et}, e.g., 226@samp{dsc_err.et}) containing an error table source file. It parses the 227error table, and generates two output files -- a C header file 228(@samp{discuss_err.h}) which contains definitions of the numerical values 229of the error codes defined in the error table, and a C source file which --- 5 unchanged lines hidden (view full) --- 235This translator accepts a @kbd{-language @var{lang}} argument, which 236determines for which language (or language variant) the output should be 237written. At the moment, @var{lang} is currently limited to @kbd{ANSI-C} 238and @kbd{K&R-C}, and some abbreviated forms of each. Eventually, this will 239be extended to include some support for C++. The default is currently 240@kbd{K&R-C}, though the generated sources will have ANSI-C code 241conditionalized on the symbol @t{__STDC__}. 242 | 259@section The error-table compiler 260 261The error table compiler is named @code{compile_et}. It takes one 262argument, the pathname of a file (ending in @samp{.et}, e.g., 263@samp{dsc_err.et}) containing an error table source file. It parses the 264error table, and generates two output files -- a C header file 265(@samp{discuss_err.h}) which contains definitions of the numerical values 266of the error codes defined in the error table, and a C source file which --- 5 unchanged lines hidden (view full) --- 272This translator accepts a @kbd{-language @var{lang}} argument, which 273determines for which language (or language variant) the output should be 274written. At the moment, @var{lang} is currently limited to @kbd{ANSI-C} 275and @kbd{K&R-C}, and some abbreviated forms of each. Eventually, this will 276be extended to include some support for C++. The default is currently 277@kbd{K&R-C}, though the generated sources will have ANSI-C code 278conditionalized on the symbol @t{__STDC__}. 279 |
| 280@ifinfo 281@node Run-time support routines, Coding Conventions, The error-table compiler, (dir) 282@comment node-name, next, previous, up 283@end ifinfo 284 |
|
| 243@section Run-time support routines 244 245Any source file which uses the routines supplied with or produced by the 246com_err package should include the header file @file{<com_err.h>}. It 247contains declarations and definitions which may be needed on some systems. 248(Some functions cannot be referenced properly without the return type 249declarations in this file. Some functions may work properly on most 250architectures even without the header file, but relying on this is not --- 126 unchanged lines hidden (view full) --- 377 378Note that since the extra arguments to @code{com_err} are passed by 379reference via the @code{va_list} value @code{args}, the hook routine may 380place any form of interpretation on them, including ignoring them. For 381consistency, @code{printf}-style interpretation is suggested, via 382@code{vsprintf} (or @code{_doprnt} on BSD systems without full support for 383the ANSI C library). 384 | 285@section Run-time support routines 286 287Any source file which uses the routines supplied with or produced by the 288com_err package should include the header file @file{<com_err.h>}. It 289contains declarations and definitions which may be needed on some systems. 290(Some functions cannot be referenced properly without the return type 291declarations in this file. Some functions may work properly on most 292architectures even without the header file, but relying on this is not --- 126 unchanged lines hidden (view full) --- 419 420Note that since the extra arguments to @code{com_err} are passed by 421reference via the @code{va_list} value @code{args}, the hook routine may 422place any form of interpretation on them, including ignoring them. For 423consistency, @code{printf}-style interpretation is suggested, via 424@code{vsprintf} (or @code{_doprnt} on BSD systems without full support for 425the ANSI C library). 426 |
| 427@ifinfo 428@node Coding Conventions, Building and Installation, Run-time support routines, (dir) 429@comment node-name, next, previous, up 430@end ifinfo 431 |
|
| 385@section Coding Conventions 386 387The following conventions are just some general stylistic conventions 388to follow when writing robust libraries and programs. Conventions 389similar to this are generally followed inside the UNIX kernel and most 390routines in the Multics operating system. In general, a routine 391either succeeds (returning a zero error code, and doing some side 392effects in the process), or it fails, doing minimal side effects; in --- 94 unchanged lines hidden (view full) --- 487error: 488 if (f1) fclose(f1); 489 if (f2) fclose(f2); 490 if (f3) fclose(f3); 491 return status; 492@} 493@end example 494 | 432@section Coding Conventions 433 434The following conventions are just some general stylistic conventions 435to follow when writing robust libraries and programs. Conventions 436similar to this are generally followed inside the UNIX kernel and most 437routines in the Multics operating system. In general, a routine 438either succeeds (returning a zero error code, and doing some side 439effects in the process), or it fails, doing minimal side effects; in --- 94 unchanged lines hidden (view full) --- 534error: 535 if (f1) fclose(f1); 536 if (f2) fclose(f2); 537 if (f3) fclose(f3); 538 return status; 539@} 540@end example 541 |
| 542@ifinfo 543@node Building and Installation, Bug Reports, Coding Conventions, (dir) 544@comment node-name, next, previous, up 545@end ifinfo 546 |
|
| 495@section Building and Installation 496 497The distribution of this package will probably be done as a compressed 498``tar''-format file available via anonymous FTP from SIPB.MIT.EDU. 499Retrieve @samp{pub/com_err.tar.Z} and extract the contents. A subdirectory 500@t{profiled} should be created to hold objects compiled for profiling. 501Running ``make all'' should then be sufficient to build the library and 502error-table compiler. The files @samp{libcom_err.a}, --- 25 unchanged lines hidden (view full) --- 528 529@end itemize 530 531As I do not have access to non-BSD systems, there are probably 532bugs present that may interfere with building or using this package on 533other systems. If they are reported to me, they can probably be fixed for 534the next version. 535 | 547@section Building and Installation 548 549The distribution of this package will probably be done as a compressed 550``tar''-format file available via anonymous FTP from SIPB.MIT.EDU. 551Retrieve @samp{pub/com_err.tar.Z} and extract the contents. A subdirectory 552@t{profiled} should be created to hold objects compiled for profiling. 553Running ``make all'' should then be sufficient to build the library and 554error-table compiler. The files @samp{libcom_err.a}, --- 25 unchanged lines hidden (view full) --- 580 581@end itemize 582 583As I do not have access to non-BSD systems, there are probably 584bugs present that may interfere with building or using this package on 585other systems. If they are reported to me, they can probably be fixed for 586the next version. 587 |
| 588@ifinfo 589@node Bug Reports, Acknowledgements, Building and Installation, (dir) 590@comment node-name, next, previous, up 591@end ifinfo 592 |
|
| 536@section Bug Reports 537 538Please send any comments or bug reports to the principal author: Ken 539Raeburn, @t{Raeburn@@Athena.MIT.EDU}. 540 | 593@section Bug Reports 594 595Please send any comments or bug reports to the principal author: Ken 596Raeburn, @t{Raeburn@@Athena.MIT.EDU}. 597 |
| 598@ifinfo 599@node Acknowledgements, , Bug Reports, (dir) 600@comment node-name, next, previous, up 601@end ifinfo 602 |
|
| 541@section Acknowledgements 542 543I would like to thank: Bill Sommerfeld, for his help with some of this 544documentation, and catching some of the bugs the first time around; 545Honeywell Information Systems, for not killing off the @emph{Multics} 546operating system before I had an opportunity to use it; Honeywell's 547customers, who persuaded them not to do so, for a while; Ted Anderson of 548CMU, for catching some problems before version 1.2 left the nest; Stan 549Zanarotti and several others of MIT's Student Information Processing Board, 550for getting us started with ``discuss,'' for which this package was 551originally written; and everyone I've talked into --- I mean, asked to read 552this document and the ``man'' pages. 553 554@bye | 603@section Acknowledgements 604 605I would like to thank: Bill Sommerfeld, for his help with some of this 606documentation, and catching some of the bugs the first time around; 607Honeywell Information Systems, for not killing off the @emph{Multics} 608operating system before I had an opportunity to use it; Honeywell's 609customers, who persuaded them not to do so, for a while; Ted Anderson of 610CMU, for catching some problems before version 1.2 left the nest; Stan 611Zanarotti and several others of MIT's Student Information Processing Board, 612for getting us started with ``discuss,'' for which this package was 613originally written; and everyone I've talked into --- I mean, asked to read 614this document and the ``man'' pages. 615 616@bye |