status_code_macros(3K) DG/UX R4.11MU05 status_code_macros(3K)
NAME
status_code_macros: ENCODE_STATUS, STATUS_TO_SUBSYSTEM_ID,
STATUS_TO_SEQUENCE_NUMBER, STATUS_TO_ERRNO, STATUS_TO_EXTENDED_ERRNO,
STATUS_HAS_NO_ERRNO - create and manipulate status codes
SYNOPSIS
#include "ext/status_code.h"
ENCODE_STATUS (subsystem_id, errno, sequence)
STATUS_HAS_NO_ERRNO (status)
STATUS_TO_ERRNO (status)
STATUS_TO_EXTENDED_ERRNO (status)
STATUS_TO_SEQUENCE_NUMBER (status)
STATUS_TO_SUBSYSTEM_ID (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.
subsystem_id 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 io_err_log_error(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 io_err_log_error 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:
SS_EEEE_DDDDDD
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:
IO_EIO_DEVICE_TIMED_OUT
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
dev_status_codes.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 dev_status_codes.h. The DEV_ENCODE macro in
dev_status_codes.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 DEV_STATUS_FOO_DEVICE_IN_BAR_STATE DEV_ENCODE(NO_ERRNO,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.
NO_ERRNO
#define NO_ERRNO 0
Use this value to indicate that the status does not contain an errno
value.
ENCODE_STATUS
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.
STATUS_HAS_NO_ERRNO
This macro returns TRUE if the specified status has no errno value
associated with it.
STATUS_TO_ERRNO
This macro extracts the errno value from a status.
STATUS_TO_EXTENDED_ERRNO
This macro reformats the extended errno from a status. The high
order bit of the extended errno is always set.
STATUS_TO_SEQUENCE_NUMBER
This macro extracts the sequence number from a status.
STATUS_TO_SUBSYSTEM_ID
This macro extracts the subsystem ID value from a status.
DIAGNOSTICS
Return Value
For ENCODE_STATUS:
status The newly encoded status.
For STATUS_HAS_NO_ERRNO:
TRUE The status has no errno value associated with it.
FALSE The status has some errno value associated with it.
For STATUS_TO_ERRNO:
errno The errno value from the status.
For STATUS_TO_EXTENDED_ERRNO:
extended_errno
The extended errno value from the status.
For STATUS_TO_SEQUENCE_NUMBER:
sequence
The sequence number from the status.
For STATUS_TO_SUBSYSTEM_ID:
id The subsystem ID value from the status.
Errors
None.
SEE ALSO
server_messages(3K).
NOTE
NO_ERRNO and ENCODE_STATUS were formerly called SC_NO_ERRNO and
SC_ENCODE_STATUS.
Programming in the DG/UX Kernel Environment.
Licensed material--property of copyright holder(s)