status_code_macros(3K) SDK R4.11 status_code_macros(3K)
NAME
statuscodemacros: ENCODESTATUS, STATUSTOSUBSYSTEMID,
STATUSTOSEQUENCENUMBER, STATUSTOERRNO, STATUSTOEXTENDEDERRNO,
STATUSHASNOERRNO - create and manipulate status codes
SYNOPSIS
#include "ext/statuscode.h"
ENCODESTATUS (subsystemid, errno, sequence)
STATUSHASNOERRNO (status)
STATUSTOERRNO (status)
STATUSTOEXTENDEDERRNO (status)
STATUSTOSEQUENCENUMBER (status)
STATUSTOSUBSYSTEMID (status)
where:
errno The errno that is to be inserted into the status. The
value of errno must be less than or equal to 511.
sequence A sequence number to distinguish multiple statuses with
the same subsystem ID. The sequence number must have a
value between 1 and 511.
status The status from which the subsystem ID, sequence
number, errno, or extended errno is to be extracted, or
for which the errno value is to be tested.
subsystemid The subsystem ID for the subsystem.
DESCRIPTION
The following macros are described in this man page:
ENCODE_STATUS Construct status value from subsystem ID
STATUS_TO_SUBSYSTEM_ID Extract subsystem ID value from status
STATUS_TO_SEQUENCE_NUMBER Extract sequence number from status
STATUS_TO_ERRNO Extract errno value from status
STATUS_TO_EXTENDED_ERRNO Obtain extended errno from status
STATUS_HAS_NO_ERRNO Check whether status has no errno
Error Encoding and Logging Routines
This section describes a macro you can use to create system-
compatible error numbers for your device's errors and a routine you
can use to log errors to the system error facility.
NOTE: The recommended error reporting facility for STREAMS is
described in log(7). The error logging facility described
here is usable but not recommended because it is not as
portable.
You use the ioerrlogerror(3K) routine to queue your driver's error
messages on the pseudo-device err(7) until they can be retrieved by
the system error server and written to system error log. You pass
your message to ioerrlogerror in the form of a printf string with
a format parameter and accompanying variables.
The error encoding macro helps you integrate system-compatible errnos
into your status codes. A compatible errno can be passed all the way
back to the user level. In normal processing, once a status is sent
to the user-level, the errno is extracted from the status and
returned to the user.
To create a status containing an errno, use the following format:
SSEEEEDDDDDD
SS is a subsystem identifier. If your device driver is a standard
driver, use DEV; for a STREAMS driver, use SFM. EEEE is the full
name of the errno to be returned to the user; use standard names
found in errno.h. DDDDDD is a description of the state that caused
the status to be returned. An example of a status code is as
follows:
IOEIODEVICETIMEDOUT
If you do not want to use the status to return errno to the user,
pass NO_ERRNO to this macro. Higher levels of code will deal with
the status before it gets back to the user.
Whenever possible, use I/O statuses already defined in
devstatuscodes.h found in aviion/dev. For statuses that you will
handle within your driver, use DEV as the subsystem, NO_ERRNO as the
errno and simply choose a status number that is higher than the last
one used in devstatuscodes.h. The DEVENCODE macro in
devstatuscodes.h will set up the status for you correctly.
Note that the convention through the rest of the kernel is to use
STATUS instead of the EEEE errno when no errno is used. For example,
IO_STATUS_REQUEST_STILL_IN_PROGRESS will not return a status to the
user. An example of how to create a new status for your device is as
follows:
#define DEVSTATUSFOODEVICEINBARSTATE DEVENCODE(NOERRNO,0107)
Constants and Data Structures
This section defines the "no error" constant.
Try to avoid dependencies on the specifics of these structures, such
as size or location of fields, because these specifics may change in
later releases of the software. You can verify exact variable
definitions in the appropriate include file. The best way to avoid
such dependencies is to use kernel-supplied routines to manipulate
these structures.
NOERRNO
#define NOERRNO 0
Use this value to indicate that the status does not contain an errno
value.
ENCODESTATUS
This macro constructs a status value from the subsystem ID for a
subsystem, the errno to be inserted into the status, and a sequence
number to distinguish multiple statuses with the same subsystem ID.
STATUSHASNOERRNO
This macro returns TRUE if the specified status has no errno value
associated with it.
STATUSTOERRNO
This macro extracts the errno value from a status.
STATUSTOEXTENDEDERRNO
This macro reformats the extended errno from a status. The high
order bit of the extended errno is always set.
STATUSTOSEQUENCENUMBER
This macro extracts the sequence number from a status.
STATUSTOSUBSYSTEMID
This macro extracts the subsystem ID value from a status.
DIAGNOSTICS
Return Value
For ENCODESTATUS:
status The newly encoded status.
For STATUSHASNOERRNO:
TRUE The status has no errno value associated with it.
FALSE The status has some errno value associated with it.
For STATUSTOERRNO:
errno The errno value from the status.
For STATUSTOEXTENDEDERRNO:
extendederrno
The extended errno value from the status.
For STATUSTOSEQUENCENUMBER:
sequence
The sequence number from the status.
For STATUSTOSUBSYSTEMID:
id The subsystem ID value from the status.
Errors
None.
SEE ALSO
servermessages(3K).
NOTE
NOERRNO and ENCODESTATUS were formerly called SCNOERRNO and
SCENCODESTATUS.
Programming in the DG/UX Kernel Environment.
Licensed material--property of copyright holder(s)