API design question

[andrew queisser]

Hi all,

I'm working on a small embedded system (think microcontroller with uC/OS-II)
and I'm considering which convention to use for error handling in our
internal "API". Since I'm using two existing APIs (a low-level HAL and the
OS API) I already have mixed conventions since some return 0 for failure,
some return 0 for "no-error", etc.

I'm leaning toward the following basic rules, please critique at will:

1) Functions return what's convenient instead of forcing into a common
return-code convention. I don't like to have to write two lines of code
instead of one when testing return codes.

a) Boolean functions return 1/0, therefore boolean functions are not allowed
to fail
b) I/O functions return number of bytes read/written. Return of zero
indicates end-of-file, negative return indicates error
c) Functions that can fail and return a value that can be positive, negative
or zero have to return the error via pointer-to-argument. That allows
putting the function call into an if-statement when looking for a specific
return value

2) Keep a global header file with a list of error codes (a la winerror.h).
OS and HAL error codes get mapped to our global error codes as needed.

a) all error codes are negative
b) error codes are scalar (no bitfields), multiple concurrent error codes
have to be resolved by a separate mechanism

3) Have a global error code that can be returned via global function (a la
GetLastError()).

a) successful completion of a function (generally) does not overwrite last
error
b) last error is kept per thread
Comments? Suggestions?

Thanks,
Andrew

[Malcolm]

"andrew queisser" <andrew.queisser at hp com> wrote

I'm working on a small embedded system (think microcontroller with
uC/OS-II) and I'm considering which convention to use for error handling
in our internal "API". Since I'm using two existing APIs (a low-level HAL
and the OS API) I already have mixed conventions since some return 0 for
failure, some return 0 for "no-error", etc.

Comments? Suggestions?

There is no easy solution tot he problem of errors.

You need one type when debugging, another type when distributing beta type
code to users, and a third type when you know the code itself is robust but
input may not be.

Sometimes you want code to be reusable, and sometimes you wnat a centralised
list of error codes. You can't have both.

One mistake the designer of the standard libary made was not to have any way
of querying the line number of an input file from its file pointer.
That would be one recommendation if you are doing IO from scratch,
preseuming your input is text which could potentially be corrupted.
--
Buy my book 12 Common Atheist Arguments (refuted)
$1.25 download or $6.90 paper, available www.lulu.com

[Walter Roberson]

In article <dt**********@nwrdmz03.dmz.ncs.ea.ibs-infra.bt.com>,
Malcolm <re*******@btinternet.com> wrote:

One mistake the designer of the standard libary made was not to have any way
of querying the line number of an input file from its file pointer.
That would be one recommendation if you are doing IO from scratch,
preseuming your input is text which could potentially be corrupted.

hmmm, the number of times I've needed the input line number in a C program
is... ummm, small enough that I'm having a hard time recalling any
instances.

I've needed the input line number a number of times in perl, awk, ed and
sed, but very rarely in C.

What kind of programs do you find that this feature would be
a noticable advantage in? Is it mostly a matter of wanting reusable
code that doesn't have to know how the rest of the program is
keeping track of the line numbers ?
--
Programming is what happens while you're busy making other plans.