Error codes. More...

#include <ipxe/errno/PLATFORM.h>
#include <ipxe/errfile.h>

Macros
#define	PLATFORM_ERRNO(_platform) <ipxe/errno/_platform.h>

#define	ERRFILE ( ( int ) ( 0 * ( ( intptr_t ) missing_errfile_declaration ) ) )

#define	__einfo(platform, posix, uniq, desc) ( platform, posix, uniq, desc )
	Declare error information. More...

#define	__einfo_platform(einfo) __einfo_extract_platform einfo
	Get platform error code. More...

#define	__einfo_extract_platform(platform, posix, uniq, desc) platform

#define	__einfo_posix(einfo) __einfo_extract_posix einfo
	Get POSIX error code. More...

#define	__einfo_extract_posix(platform, posix, uniq, desc) posix

#define	__einfo_uniq(einfo) __einfo_extract_uniq einfo
	Get error disambiguator. More...

#define	__einfo_extract_uniq(platform, posix, uniq, desc) uniq

#define	__einfo_desc(einfo) __einfo_extract_desc einfo
	Get error description. More...

#define	__einfo_extract_desc(platform, posix, uniq, desc) desc

#define	__einfo_uniqify(einfo_base, uniq, desc)
	Declare disambiguated error. More...

#define	__einfo_platformify(einfo_base, platform, desc)
	Declare platform-generated error. More...

#define	__einfo_errno(einfo)
	Get error code. More...

#define	EUNIQ(einfo_base, uniq, ...)
	Disambiguate a base error based on non-constant information. More...

#define	EPLATFORM(einfo_base, platform, ...)
	Generate an error based on an external platform error code. More...

#define	__einfo_error(einfo)
	Declare error. More...

#define	ENOERR __einfo_error ( EINFO_ENOERR )
	Operation completed successfully. More...

#define	EINFO_ENOERR

#define	E2BIG __einfo_error ( EINFO_E2BIG )
	Argument list too long. More...

#define	EINFO_E2BIG

#define	EACCES __einfo_error ( EINFO_EACCES )
	Permission denied. More...

#define	EINFO_EACCES

#define	EADDRINUSE __einfo_error ( EINFO_EADDRINUSE )
	Address already in use. More...

#define	EINFO_EADDRINUSE

#define	EADDRNOTAVAIL __einfo_error ( EINFO_EADDRNOTAVAIL )
	Address not available. More...

#define	EINFO_EADDRNOTAVAIL

#define	EAFNOSUPPORT __einfo_error ( EINFO_EAFNOSUPPORT )
	Address family not supported. More...

#define	EINFO_EAFNOSUPPORT

#define	EAGAIN __einfo_error ( EINFO_EAGAIN )
	Resource temporarily unavailable. More...

#define	EINFO_EAGAIN

#define	EALREADY __einfo_error ( EINFO_EALREADY )
	Connection already in progress. More...

#define	EINFO_EALREADY

#define	EBADF __einfo_error ( EINFO_EBADF )
	Bad file descriptor. More...

#define	EINFO_EBADF

#define	EBADMSG __einfo_error ( EINFO_EBADMSG )
	Bad message. More...

#define	EINFO_EBADMSG

#define	EBUSY __einfo_error ( EINFO_EBUSY )
	Device or resource busy. More...

#define	EINFO_EBUSY

#define	ECANCELED __einfo_error ( EINFO_ECANCELED )
	Operation canceled. More...

#define	EINFO_ECANCELED

#define	ECHILD __einfo_error ( EINFO_ECHILD )
	No child processes. More...

#define	EINFO_ECHILD

#define	ECONNABORTED __einfo_error ( EINFO_ECONNABORTED )
	Connection aborted. More...

#define	EINFO_ECONNABORTED

#define	ECONNREFUSED __einfo_error ( EINFO_ECONNREFUSED )
	Connection refused. More...

#define	EINFO_ECONNREFUSED

#define	ECONNRESET __einfo_error ( EINFO_ECONNRESET )
	Connection reset. More...

#define	EINFO_ECONNRESET

#define	EDEADLK __einfo_error ( EINFO_EDEADLK )
	Resource deadlock avoided. More...

#define	EINFO_EDEADLK

#define	EDESTADDRREQ __einfo_error ( EINFO_EDESTADDRREQ )
	Destination address required. More...

#define	EINFO_EDESTADDRREQ

#define	EDOM __einfo_error ( EINFO_EDOM )
	Mathematics argument out of domain of function. More...

#define	EINFO_EDOM

#define	EDQUOT __einfo_error ( EINFO_EDQUOT )
	Disk quota exceeded. More...

#define	EINFO_EDQUOT

#define	EEXIST __einfo_error ( EINFO_EEXIST )
	File exists. More...

#define	EINFO_EEXIST

#define	EFAULT __einfo_error ( EINFO_EFAULT )
	Bad address. More...

#define	EINFO_EFAULT

#define	EFBIG __einfo_error ( EINFO_EFBIG )
	File too large. More...

#define	EINFO_EFBIG

#define	EHOSTUNREACH __einfo_error ( EINFO_EHOSTUNREACH )
	Host is unreachable. More...

#define	EINFO_EHOSTUNREACH

#define	EIDRM __einfo_error ( EINFO_EIDRM )
	Identifier removed. More...

#define	EINFO_EIDRM

#define	EILSEQ __einfo_error ( EINFO_EILSEQ )
	Illegal byte sequence. More...

#define	EINFO_EILSEQ

#define	EINPROGRESS __einfo_error ( EINFO_EINPROGRESS )
	Operation in progress. More...

#define	EINFO_EINPROGRESS

#define	EINTR __einfo_error ( EINFO_EINTR )
	Interrupted function call. More...

#define	EINFO_EINTR

#define	EINVAL __einfo_error ( EINFO_EINVAL )
	Invalid argument. More...

#define	EINFO_EINVAL

#define	EIO __einfo_error ( EINFO_EIO )
	Input/output error. More...

#define	EINFO_EIO

#define	EISCONN __einfo_error ( EINFO_EISCONN )
	Socket is connected. More...

#define	EINFO_EISCONN

#define	EISDIR __einfo_error ( EINFO_EISDIR )
	Is a directory. More...

#define	EINFO_EISDIR

#define	ELOOP __einfo_error ( EINFO_ELOOP )
	Too many levels of symbolic links. More...

#define	EINFO_ELOOP

#define	EMFILE __einfo_error ( EINFO_EMFILE )
	Too many open files. More...

#define	EINFO_EMFILE

#define	EMLINK __einfo_error ( EINFO_EMLINK )
	Too many links. More...

#define	EINFO_EMLINK

#define	EMSGSIZE __einfo_error ( EINFO_EMSGSIZE )
	Message too long. More...

#define	EINFO_EMSGSIZE

#define	EMULTIHOP __einfo_error ( EINFO_EMULTIHOP )
	Multihop attempted. More...

#define	EINFO_EMULTIHOP

#define	ENAMETOOLONG __einfo_error ( EINFO_ENAMETOOLONG )
	Filename too long. More...

#define	EINFO_ENAMETOOLONG

#define	ENETDOWN __einfo_error ( EINFO_ENETDOWN )
	Network is down. More...

#define	EINFO_ENETDOWN

#define	ENETRESET __einfo_error ( EINFO_ENETRESET )
	Connection aborted by network. More...

#define	EINFO_ENETRESET

#define	ENETUNREACH __einfo_error ( EINFO_ENETUNREACH )
	Network unreachable. More...

#define	EINFO_ENETUNREACH

#define	ENFILE __einfo_error ( EINFO_ENFILE )
	Too many open files in system. More...

#define	EINFO_ENFILE

#define	ENOBUFS __einfo_error ( EINFO_ENOBUFS )
	No buffer space available. More...

#define	EINFO_ENOBUFS

#define	ENODATA __einfo_error ( EINFO_ENODATA )
	No message is available on the STREAM head read queue. More...

#define	EINFO_ENODATA

#define	ENODEV __einfo_error ( EINFO_ENODEV )
	No such device. More...

#define	EINFO_ENODEV

#define	ENOENT __einfo_error ( EINFO_ENOENT )
	No such file or directory. More...

#define	EINFO_ENOENT

#define	ENOEXEC __einfo_error ( EINFO_ENOEXEC )
	Exec format error. More...

#define	EINFO_ENOEXEC

#define	ENOLCK __einfo_error ( EINFO_ENOLCK )
	No locks available. More...

#define	EINFO_ENOLCK

#define	ENOLINK __einfo_error ( EINFO_ENOLINK )
	Link has been severed. More...

#define	EINFO_ENOLINK

#define	ENOMEM __einfo_error ( EINFO_ENOMEM )
	Not enough space. More...

#define	EINFO_ENOMEM

#define	ENOMSG __einfo_error ( EINFO_ENOMSG )
	No message of the desired type. More...

#define	EINFO_ENOMSG

#define	ENOPROTOOPT __einfo_error ( EINFO_ENOPROTOOPT )
	Protocol not available. More...

#define	EINFO_ENOPROTOOPT

#define	ENOSPC __einfo_error ( EINFO_ENOSPC )
	No space left on device. More...

#define	EINFO_ENOSPC

#define	ENOSR __einfo_error ( EINFO_ENOSR )
	No STREAM resources. More...

#define	EINFO_ENOSR

#define	ENOSTR __einfo_error ( EINFO_ENOSTR )
	Not a STREAM. More...

#define	EINFO_ENOSTR

#define	ENOSYS __einfo_error ( EINFO_ENOSYS )
	Function not implemented. More...

#define	EINFO_ENOSYS

#define	ENOTCONN __einfo_error ( EINFO_ENOTCONN )
	The socket is not connected. More...

#define	EINFO_ENOTCONN

#define	ENOTDIR __einfo_error ( EINFO_ENOTDIR )
	Not a directory. More...

#define	EINFO_ENOTDIR

#define	ENOTEMPTY __einfo_error ( EINFO_ENOTEMPTY )
	Directory not empty. More...

#define	EINFO_ENOTEMPTY

#define	ENOTSOCK __einfo_error ( EINFO_ENOTSOCK )
	Not a socket. More...

#define	EINFO_ENOTSOCK

#define	ENOTSUP __einfo_error ( EINFO_ENOTSUP )
	Operation not supported. More...

#define	EINFO_ENOTSUP

#define	ENOTTY __einfo_error ( EINFO_ENOTTY )
	Inappropriate I/O control operation. More...

#define	EINFO_ENOTTY

#define	ENXIO __einfo_error ( EINFO_ENXIO )
	No such device or address. More...

#define	EINFO_ENXIO

#define	EOPNOTSUPP __einfo_error ( EINFO_EOPNOTSUPP )
	Operation not supported on socket. More...

#define	EINFO_EOPNOTSUPP

#define	EOVERFLOW __einfo_error ( EINFO_EOVERFLOW )
	Value too large to be stored in data type. More...

#define	EINFO_EOVERFLOW

#define	EPERM __einfo_error ( EINFO_EPERM )
	Operation not permitted. More...

#define	EINFO_EPERM

#define	EPIPE __einfo_error ( EINFO_EPIPE )
	Broken pipe. More...

#define	EINFO_EPIPE

#define	EPROTO __einfo_error ( EINFO_EPROTO )
	Protocol error. More...

#define	EINFO_EPROTO

#define	EPROTONOSUPPORT __einfo_error ( EINFO_EPROTONOSUPPORT )
	Protocol not supported. More...

#define	EINFO_EPROTONOSUPPORT

#define	EPROTOTYPE __einfo_error ( EINFO_EPROTOTYPE )
	Protocol wrong type for socket. More...

#define	EINFO_EPROTOTYPE

#define	ERANGE __einfo_error ( EINFO_ERANGE )
	Result too large. More...

#define	EINFO_ERANGE

#define	EROFS __einfo_error ( EINFO_EROFS )
	Read-only file system. More...

#define	EINFO_EROFS

#define	ESPIPE __einfo_error ( EINFO_ESPIPE )
	Invalid seek. More...

#define	EINFO_ESPIPE

#define	ESRCH __einfo_error ( EINFO_ESRCH )
	No such process. More...

#define	EINFO_ESRCH

#define	ESTALE __einfo_error ( EINFO_ESTALE )
	Stale file handle. More...

#define	EINFO_ESTALE

#define	ETIME __einfo_error ( EINFO_ETIME )
	Timer expired. More...

#define	EINFO_ETIME

#define	ETIMEDOUT __einfo_error ( EINFO_ETIMEDOUT )
	Connection timed out. More...

#define	EINFO_ETIMEDOUT

#define	ETXTBSY __einfo_error ( EINFO_ETXTBSY )
	Text file busy. More...

#define	EINFO_ETXTBSY

#define	EWOULDBLOCK __einfo_error ( EINFO_EWOULDBLOCK )
	Operation would block. More...

#define	EINFO_EWOULDBLOCK

#define	EXDEV __einfo_error ( EINFO_EXDEV )
	Improper link. More...

#define	EINFO_EXDEV

#define	EINFO_EPLATFORM __einfo ( 0, 0x7f, 0, "Platform-generated error" )
	Platform-generated base error. More...

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)

char missing_errfile_declaration []	__attribute__ ((deprecated))

static void	euniq_discard (int dummy __unused,...)

static void	eplatform_discard (int dummy __unused,...)

Variables
int	errno
	Global "last error" number. More...

Detailed Description

Error codes.

Return status codes as used within iPXE are designed to allow for maximum visibility into the source of an error even in an end-user build with no debugging. They are constructed as follows:

Bits 7-0 : Platform-specific error code

This is a losslessly compressed representation of the closest equivalent error code defined by the platform (e.g. BIOS/PXE or EFI). It is used to generate errors to be returned to external code.

Bits 12-8 : Per-file disambiguator

When the same error code can be generated from multiple points within a file, this field can be used to identify the unique instance.

Bits 23-13 : File identifier

This is a unique identifier for the file generating the error (e.g. ERRFILE_tcp for tcp.c).

Bits 30-24 : POSIX error code

This is the closest equivalent POSIX error code (e.g. ENOMEM).

Bit 31 : Reserved

Errors are usually return as negative error codes (e.g. -EINVAL); bit 31 is therefore unusable.

The convention within the code is that errors are negative and expressed using the POSIX error, e.g.

return -EINVAL;

By various bits of preprocessor magic, the platform-specific error code and file identifier are already incorporated into the definition of the POSIX error macro, which keeps the code relatively clean.

Functions that wish to return failures should be declared as returning an integer rc "Return status code". A return value of zero indicates success, a non-zero value indicates failure. The return value can be passed directly to strerror() in order to generate a human-readable error message, e.g.

if ( ( rc = some_function ( ... ) ) != 0 ) {
    DBG ( "Whatever I was trying to do failed: %s\n", strerror ( rc ) );
    return rc;
}

As illustrated in the above example, error returns should generally be directly propagated upward to the calling function.

Individual files may declare localised errors using __einfo_uniqify(). For example, iscsi.c declares a localised version of EACCES for the error of "access denied due to incorrect target username":

#define EACCES_INCORRECT_TARGET_USERNAME    \
    __einfo_error ( EINFO_EACCES_INCORRECT_TARGET_USERNAME )
#define EINFO_EACCES_INCORRECT_TARGET_USERNAME \
    __einfo_uniqify ( EINFO_EACCESS, 0x01, "Incorrect target username" )

which can then be used as:

return -EACCES_INCORRECT_TARGET_USERNAME;

Definition in file errno.h.

Macro Definition Documentation

◆ PLATFORM_ERRNO

#define PLATFORM_ERRNO ( _platform ) <ipxe/errno/_platform.h>

Definition at line 108 of file errno.h.

◆ ERRFILE

#define ERRFILE ( ( int ) ( 0 * ( ( intptr_t ) missing_errfile_declaration ) ) )

Definition at line 122 of file errno.h.

◆ __einfo

#define __einfo	(	platform,
		posix,
		uniq,
		desc
	)	( platform, posix, uniq, desc )

Declare error information.

Parameters

platform	Platform error code (uncompressed)
posix	POSIX error code (0x00-0x7f)
uniq	Error disambiguator (0x00-0x1f)
desc	Error description

Return values

einfo Error information

Definition at line 134 of file errno.h.

◆ __einfo_platform

#define __einfo_platform ( einfo ) __einfo_extract_platform einfo

Get platform error code.

Parameters

einfo Error information

Return values

platform Platform error code (uncompressed)

Definition at line 142 of file errno.h.

◆ __einfo_extract_platform

#define __einfo_extract_platform	(	platform,
		posix,
		uniq,
		desc
	)	platform

Definition at line 143 of file errno.h.

◆ __einfo_posix

#define __einfo_posix ( einfo ) __einfo_extract_posix einfo

Get POSIX error code.

Parameters

einfo Error information

Return values

posix POSIX error code

Definition at line 151 of file errno.h.

◆ __einfo_extract_posix

#define __einfo_extract_posix	(	platform,
		posix,
		uniq,
		desc
	)	posix

Definition at line 152 of file errno.h.

◆ __einfo_uniq

#define __einfo_uniq ( einfo ) __einfo_extract_uniq einfo

Get error disambiguator.

Parameters

einfo Error information

Return values

uniq	Error disambiguator

Definition at line 160 of file errno.h.

◆ __einfo_extract_uniq

#define __einfo_extract_uniq	(	platform,
		posix,
		uniq,
		desc
	)	uniq

Definition at line 161 of file errno.h.

◆ __einfo_desc

#define __einfo_desc ( einfo ) __einfo_extract_desc einfo

Get error description.

Parameters

einfo Error information

Return values

desc	Error description

Definition at line 169 of file errno.h.

◆ __einfo_extract_desc

#define __einfo_extract_desc	(	platform,
		posix,
		uniq,
		desc
	)	desc

Definition at line 170 of file errno.h.

◆ __einfo_uniqify

#define __einfo_uniqify	(	einfo_base,
		uniq,
		desc
	)

Value:

__einfo ( __einfo_platform ( einfo_base ),                      \
                  __einfo_posix ( einfo_base ),                         \
                  uniq, desc )

Declare disambiguated error.

Parameters

einfo_base	Base error information
uniq	Error disambiguator (0x00-0x1f)
desc	Error description

Return values

einfo Error information

Definition at line 180 of file errno.h.

◆ __einfo_platformify

#define __einfo_platformify	(	einfo_base,
		platform,
		desc
	)

Value:

__einfo ( platform, __einfo_posix ( einfo_base ), \

__einfo_uniq ( einfo_base ), desc )

__einfo

#define __einfo(platform, posix, uniq, desc)

Declare error information.

Definition: errno.h:134

desc

uint64_t desc

Microcode descriptor list physical address.

Definition: ucode.h:12

__einfo_posix

#define __einfo_posix(einfo)

Get POSIX error code.

Definition: errno.h:151

__einfo_uniq

#define __einfo_uniq(einfo)

Get error disambiguator.

Definition: errno.h:160

Declare platform-generated error.

Parameters

einfo_base	Base error information
platform	Platform error code (uncompressed)
desc	Error description

Return values

einfo Error information

Definition at line 193 of file errno.h.

◆ __einfo_errno

#define __einfo_errno ( einfo )

Value:

( ( int )                                                       \
          ( ( __einfo_posix ( einfo ) << 24 ) | ( ERRFILE ) |           \
            ( __einfo_uniq ( einfo ) << 8 ) |                           \
            ( PLATFORM_TO_ERRNO ( __einfo_platform ( einfo ) ) << 0 ) ) )

Get error code.

Parameters

einfo Error information

Return values

errno Error code

Definition at line 203 of file errno.h.

◆ EUNIQ

#define EUNIQ	(	einfo_base,
		uniq,
		...
	)

Value:

( {                             \
        euniq_discard ( 0, ##__VA_ARGS__ );                             \
        ( ( int ) ( __einfo_error ( einfo_base ) |                      \
                    ( (uniq) << 8 ) ) ); } )

Disambiguate a base error based on non-constant information.

Parameters

einfo_base	Base error information
uniq	Error disambiguator (0x00-0x1f)
...	List of expected possible disambiguated errors

Return values

error Error

EUNIQ() should be used when information from an external source is being incorporated into an error. For example, the 802.11 stack uses EUNIQ() to incorporate 802.11 status codes returned by an access point into an error.

EUNIQ() should not be used for constant error disambiguators; use __einfo_uniqify() instead.

Definition at line 225 of file errno.h.

◆ EPLATFORM

#define EPLATFORM	(	einfo_base,
		platform,
		...
	)

Value:

( {                     \
        eplatform_discard ( 0, ##__VA_ARGS__ );                         \
        ( ( int ) ( __einfo_error ( einfo_base ) |                      \
                    PLATFORM_TO_ERRNO ( platform ) ) ); } )

Generate an error based on an external platform error code.

Parameters

einfo_base	Base error information
platform	Platform error code (uncompressed)
...	List of expected possible platform-generated errors

Return values

error Error

EPLATFORM() should be used when a platform error code resulting from an external platform API call is being incorporated into an error. For example, EFI code uses EPLATFORM() to generate errors resulting from calls to EFI APIs such as InstallMultipleProtocolInterfaces().

EPLATFORM() should not be used for constant platform-generated errors; use __einfo_platformify() instead.

Definition at line 248 of file errno.h.

◆ __einfo_error

#define __einfo_error ( einfo )

Value:

( {                                     \
        __asm__ ( ".section \".einfo\", \"\", " PROGBITS_OPS "\n\t"     \
                  ".balign 8\n\t"                                       \
                  "\n1:\n\t"                                            \
                  ".long ( 4f - 1b )\n\t"                               \
                  ".long %" ASM_NO_PREFIX "0\n\t"                       \
                  ".long ( 2f - 1b )\n\t"                               \
                  ".long ( 3f - 1b )\n\t"                               \
                  ".long %" ASM_NO_PREFIX "1\n\t"                       \
                  "\n2:\t.asciz \"" __einfo_desc ( einfo ) "\"\n\t"     \
                  "\n3:\t.asciz \"" __FILE__ "\"\n\t"                   \
                  ".balign 8\n\t"                                       \
                  "\n4:\n\t"                                            \
                  ".previous\n\t" : :                                   \
                  "i" ( __einfo_errno ( einfo ) ),                      \
                  "i" ( __LINE__ ) );                                   \
        __einfo_errno ( einfo ); } )

Declare error.

Parameters

einfo Error information

Return values

error Error

Definition at line 260 of file errno.h.

◆ EINFO_EPLATFORM

#define EINFO_EPLATFORM __einfo ( 0, 0x7f, 0, "Platform-generated error" )

Platform-generated base error.

Definition at line 691 of file errno.h.

Function Documentation

◆ FILE_LICENCE()

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL )

◆ attribute()

char missing_errfile_declaration [] __attribute__ ( (deprecated) )

◆ euniq_discard()

static void euniq_discard	(	int dummy	__unused,
			...
	)

inlinestatic

Definition at line 229 of file errno.h.

229 {}

◆ eplatform_discard()

static void eplatform_discard	(	int dummy	__unused,
			...
	)

inlinestatic

Definition at line 252 of file errno.h.

252 {}

Variable Documentation

◆ errno

int errno

Global "last error" number.

This is valid only when a function has just returned indicating a failure.

Definition at line 20 of file errno.c.

Referenced by errno_fetch(), execv(), find_closest_error(), find_error(), gdbstub_send_errno(), strerror(), and tg3_init_one().

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ PLATFORM_ERRNO

◆ ERRFILE

◆ __einfo

◆ __einfo_platform

◆ __einfo_extract_platform

◆ __einfo_posix

◆ __einfo_extract_posix

◆ __einfo_uniq

◆ __einfo_extract_uniq

◆ __einfo_desc

◆ __einfo_extract_desc

◆ __einfo_uniqify

◆ __einfo_platformify

◆ __einfo_errno

◆ EUNIQ

◆ EPLATFORM

◆ __einfo_error

◆ EINFO_EPLATFORM

Function Documentation

◆ FILE_LICENCE()

◆ __attribute__()

◆ euniq_discard()

◆ eplatform_discard()

Variable Documentation

◆ errno

◆ attribute()