VxWorks Reference Manual : Libraries
errnoLib - error status library
errnoGet( ) - get the error status value of the calling task
errnoOfTaskGet( ) - get the error status value of a specified task
errnoSet( ) - set the error status value of the calling task
errnoOfTaskSet( ) - set the error status value of a specified task
This library contains routines for setting and examining the error status values of tasks and interrupts. Most VxWorks functions return ERROR when they detect an error, or NULL in the case of functions returning pointers. In addition, they set an error status that elaborates the nature of the error.
This facility is compatible with the UNIX error status mechanism in which error status values are set in the global variable errno. However, in VxWorks there are many task and interrupt contexts that share common memory space and therefore conflict in their use of this global variable. VxWorks resolves this in two ways:
- (1)
- For tasks, VxWorks maintains the errno value for each context separately, and saves and restores the value of errno with every context switch. The value of errno for a non-executing task is stored in the task's TCB. Thus, regardless of task context, code can always reference or modify errno directly.
- (2)
- For interrupt service routines, VxWorks saves and restores errno on the interrupt stack as part of the interrupt enter and exit code provided automatically with the intConnect( ) facility. Thus, interrupt service routines can also reference or modify errno directly.
The errno facility is used throughout VxWorks for error reporting. In situations where a lower-level routine has generated an error, by convention, higher-level routines propagate the same error status, leaving errno with the value set at the deepest level. Developers are encouraged to use the same mechanism for application modules where appropriate.
An error status is a 4-byte integer. By convention, the most significant two bytes are the module number, which indicates the module in which the error occurred. The lower two bytes indicate the specific error within that module. Module number 0 is reserved for UNIX error numbers so that values from the UNIX errno.h header file can be set and tested without modification. Module numbers 1-500 decimal are reserved for VxWorks modules. These are defined in vwModNum.h. All other module numbers are available to applications.
VxWorks can include a special symbol table called statSymTbl which printErrno( ) uses to print human-readable error messages.
This table is created with the tool makeStatTbl, found in host/hostOs/bin. This tool reads all the .h files in a specified directory and generates a C-language file, which generates a symbol table when compiled. Each symbol consists of an error status value and its definition, which was obtained from the header file.
For example, suppose the header file target/h/myFile.h contains the line:
#define S_myFile_ERROR_TOO_MANY_COOKS 0x230003The table statSymTbl is created by first running:On Unix:
makeStatTbl target/h > statTbl.cOn Windows:makeStatTbl target/hThis creates a file statTbl.c in the current directory, which, when compiled, generates statSymTbl. The table is then linked in with VxWorks. Normally, these steps are performed automatically by the makefile in target/src/usr.If the user now types from the VxWorks shell:
-> printErrno 0x230003The printErrno( ) routine would respond:S_myFile_ERROR_TOO_MANY_COOKSThe makeStatTbl tool looks for error status lines of the form:#define S_xxx <n>where xxx is any string, and n is any number. All VxWorks status lines are of the form:#define S_thisFile_MEANINGFUL_ERROR_MESSAGE 0xnnnnwhere thisFile is the name of the module.This facility is available to the user by adding header files with status lines of the appropriate forms and remaking VxWorks.
The file vwModNum.h contains the module numbers for every VxWorks module. The include file for each module contains the error numbers which that module can generate.
errnoLib, printErrno( ), makeStatTbl, VxWorks Programmer's Guide: Basic OS
errnoGet( ) - get the error status value of the calling task
int errnoGet (void)
This routine gets the error status stored in errno. It is provided for compatibility with previous versions of VxWorks and simply accesses errno directly.
The error status value contained in errno.
errnoLib, errnoSet( ), errnoOfTaskGet( )
errnoOfTaskGet( ) - get the error status value of a specified task
int errnoOfTaskGet ( int taskId /* task ID, 0 means current task */ )
This routine gets the error status most recently set for a specified task. If taskId is zero, the calling task is assumed, and the value currently in errno is returned.
This routine is provided primarily for debugging purposes. Normally, tasks access errno directly to set and get their own error status values.
The error status of the specified task, or ERROR if the task does not exist.
errnoLib, errnoSet( ), errnoGet( )
errnoSet( ) - set the error status value of the calling task
STATUS errnoSet ( int errorValue /* error status value to set */ )
This routine sets the errno variable with a specified error status. It is provided for compatibility with previous versions of VxWorks and simply accesses errno directly.
OK, or ERROR if the interrupt nest level is too deep.
errnoLib, errnoGet( ), errnoOfTaskSet( )
errnoOfTaskSet( ) - set the error status value of a specified task
STATUS errnoOfTaskSet ( int taskId, /* task ID, 0 means current task */ int errorValue /* error status value */ )
This routine sets the error status for a specified task. If taskId is zero, the calling task is assumed, and errno is set with the specified error status.
This routine is provided primarily for debugging purposes. Normally, tasks access errno directly to set and get their own error status values.
OK, or ERROR if the task does not exist.
errnoLib, errnoSet( ), errnoOfTaskGet( )