iPXE
Defines | Functions | Variables
errno.h File Reference

Error codes. More...

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

Go to the source code of this file.

Defines

#define PLATFORM_ERRNO(_platform)   <ipxe/errno/_platform.h>
#define __einfo(platform, posix, uniq, desc)   ( platform, posix, uniq, desc )
 Declare error information.
#define __einfo_platform(einfo)   __einfo_extract_platform einfo
 Get platform error code.
#define __einfo_extract_platform(platform, posix, uniq, desc)   platform
#define __einfo_posix(einfo)   __einfo_extract_posix einfo
 Get POSIX error code.
#define __einfo_extract_posix(platform, posix, uniq, desc)   posix
#define __einfo_uniq(einfo)   __einfo_extract_uniq einfo
 Get error disambiguator.
#define __einfo_extract_uniq(platform, posix, uniq, desc)   uniq
#define __einfo_desc(einfo)   __einfo_extract_desc einfo
 Get error description.
#define __einfo_extract_desc(platform, posix, uniq, desc)   desc
#define __einfo_uniqify(einfo_base, uniq, desc)
 Declare disambiguated error.
#define __einfo_platformify(einfo_base, platform, desc)
 Declare platform-generated error.
#define __einfo_errno(einfo)
 Get error code.
#define EUNIQ(einfo_base, uniq,...)
 Disambiguate a base error based on non-constant information.
#define EPLATFORM(einfo_base, platform,...)
 Generate an error based on an external platform error code.
#define __einfo_error(einfo)
 Declare error.
#define ENOERR   __einfo_error ( EINFO_ENOERR )
 Operation completed successfully.
#define EINFO_ENOERR
#define E2BIG   __einfo_error ( EINFO_E2BIG )
 Argument list too long.
#define EINFO_E2BIG
#define EACCES   __einfo_error ( EINFO_EACCES )
 Permission denied.
#define EINFO_EACCES
#define EADDRINUSE   __einfo_error ( EINFO_EADDRINUSE )
 Address already in use.
#define EINFO_EADDRINUSE
#define EADDRNOTAVAIL   __einfo_error ( EINFO_EADDRNOTAVAIL )
 Address not available.
#define EINFO_EADDRNOTAVAIL
#define EAFNOSUPPORT   __einfo_error ( EINFO_EAFNOSUPPORT )
 Address family not supported.
#define EINFO_EAFNOSUPPORT
#define EAGAIN   __einfo_error ( EINFO_EAGAIN )
 Resource temporarily unavailable.
#define EINFO_EAGAIN
#define EALREADY   __einfo_error ( EINFO_EALREADY )
 Connection already in progress.
#define EINFO_EALREADY
#define EBADF   __einfo_error ( EINFO_EBADF )
 Bad file descriptor.
#define EINFO_EBADF
#define EBADMSG   __einfo_error ( EINFO_EBADMSG )
 Bad message.
#define EINFO_EBADMSG
#define EBUSY   __einfo_error ( EINFO_EBUSY )
 Device or resource busy.
#define EINFO_EBUSY
#define ECANCELED   __einfo_error ( EINFO_ECANCELED )
 Operation canceled.
#define EINFO_ECANCELED
#define ECHILD   __einfo_error ( EINFO_ECHILD )
 No child processes.
#define EINFO_ECHILD
#define ECONNABORTED   __einfo_error ( EINFO_ECONNABORTED )
 Connection aborted.
#define EINFO_ECONNABORTED
#define ECONNREFUSED   __einfo_error ( EINFO_ECONNREFUSED )
 Connection refused.
#define EINFO_ECONNREFUSED
#define ECONNRESET   __einfo_error ( EINFO_ECONNRESET )
 Connection reset.
#define EINFO_ECONNRESET
#define EDEADLK   __einfo_error ( EINFO_EDEADLK )
 Resource deadlock avoided.
#define EINFO_EDEADLK
#define EDESTADDRREQ   __einfo_error ( EINFO_EDESTADDRREQ )
 Destination address required.
#define EINFO_EDESTADDRREQ
#define EDOM   __einfo_error ( EINFO_EDOM )
 Mathematics argument out of domain of function.
#define EINFO_EDOM
#define EDQUOT   __einfo_error ( EINFO_EDQUOT )
 Disk quota exceeded.
#define EINFO_EDQUOT
#define EEXIST   __einfo_error ( EINFO_EEXIST )
 File exists.
#define EINFO_EEXIST
#define EFAULT   __einfo_error ( EINFO_EFAULT )
 Bad address.
#define EINFO_EFAULT
#define EFBIG   __einfo_error ( EINFO_EFBIG )
 File too large.
#define EINFO_EFBIG
#define EHOSTUNREACH   __einfo_error ( EINFO_EHOSTUNREACH )
 Host is unreachable.
#define EINFO_EHOSTUNREACH
#define EIDRM   __einfo_error ( EINFO_EIDRM )
 Identifier removed.
#define EINFO_EIDRM
#define EILSEQ   __einfo_error ( EINFO_EILSEQ )
 Illegal byte sequence.
#define EINFO_EILSEQ
#define EINPROGRESS   __einfo_error ( EINFO_EINPROGRESS )
 Operation in progress.
#define EINFO_EINPROGRESS
#define EINTR   __einfo_error ( EINFO_EINTR )
 Interrupted function call.
#define EINFO_EINTR
#define EINVAL   __einfo_error ( EINFO_EINVAL )
 Invalid argument.
#define EINFO_EINVAL
#define EIO   __einfo_error ( EINFO_EIO )
 Input/output error.
#define EINFO_EIO
#define EISCONN   __einfo_error ( EINFO_EISCONN )
 Socket is connected.
#define EINFO_EISCONN
#define EISDIR   __einfo_error ( EINFO_EISDIR )
 Is a directory.
#define EINFO_EISDIR
#define ELOOP   __einfo_error ( EINFO_ELOOP )
 Too many levels of symbolic links.
#define EINFO_ELOOP
#define EMFILE   __einfo_error ( EINFO_EMFILE )
 Too many open files.
#define EINFO_EMFILE
#define EMLINK   __einfo_error ( EINFO_EMLINK )
 Too many links.
#define EINFO_EMLINK
#define EMSGSIZE   __einfo_error ( EINFO_EMSGSIZE )
 Message too long.
#define EINFO_EMSGSIZE
#define EMULTIHOP   __einfo_error ( EINFO_EMULTIHOP )
 Multihop attempted.
#define EINFO_EMULTIHOP
#define ENAMETOOLONG   __einfo_error ( EINFO_ENAMETOOLONG )
 Filename too long.
#define EINFO_ENAMETOOLONG
#define ENETDOWN   __einfo_error ( EINFO_ENETDOWN )
 Network is down.
#define EINFO_ENETDOWN
#define ENETRESET   __einfo_error ( EINFO_ENETRESET )
 Connection aborted by network.
#define EINFO_ENETRESET
#define ENETUNREACH   __einfo_error ( EINFO_ENETUNREACH )
 Network unreachable.
#define EINFO_ENETUNREACH
#define ENFILE   __einfo_error ( EINFO_ENFILE )
 Too many open files in system.
#define EINFO_ENFILE
#define ENOBUFS   __einfo_error ( EINFO_ENOBUFS )
 No buffer space available.
#define EINFO_ENOBUFS
#define ENODATA   __einfo_error ( EINFO_ENODATA )
 No message is available on the STREAM head read queue.
#define EINFO_ENODATA
#define ENODEV   __einfo_error ( EINFO_ENODEV )
 No such device.
#define EINFO_ENODEV
#define ENOENT   __einfo_error ( EINFO_ENOENT )
 No such file or directory.
#define EINFO_ENOENT
#define ENOEXEC   __einfo_error ( EINFO_ENOEXEC )
 Exec format error.
#define EINFO_ENOEXEC
#define ENOLCK   __einfo_error ( EINFO_ENOLCK )
 No locks available.
#define EINFO_ENOLCK
#define ENOLINK   __einfo_error ( EINFO_ENOLINK )
 Link has been severed.
#define EINFO_ENOLINK
#define ENOMEM   __einfo_error ( EINFO_ENOMEM )
 Not enough space.
#define EINFO_ENOMEM
#define ENOMSG   __einfo_error ( EINFO_ENOMSG )
 No message of the desired type.
#define EINFO_ENOMSG
#define ENOPROTOOPT   __einfo_error ( EINFO_ENOPROTOOPT )
 Protocol not available.
#define EINFO_ENOPROTOOPT
#define ENOSPC   __einfo_error ( EINFO_ENOSPC )
 No space left on device.
#define EINFO_ENOSPC
#define ENOSR   __einfo_error ( EINFO_ENOSR )
 No STREAM resources.
#define EINFO_ENOSR
#define ENOSTR   __einfo_error ( EINFO_ENOSTR )
 Not a STREAM.
#define EINFO_ENOSTR
#define ENOSYS   __einfo_error ( EINFO_ENOSYS )
 Function not implemented.
#define EINFO_ENOSYS
#define ENOTCONN   __einfo_error ( EINFO_ENOTCONN )
 The socket is not connected.
#define EINFO_ENOTCONN
#define ENOTDIR   __einfo_error ( EINFO_ENOTDIR )
 Not a directory.
#define EINFO_ENOTDIR
#define ENOTEMPTY   __einfo_error ( EINFO_ENOTEMPTY )
 Directory not empty.
#define EINFO_ENOTEMPTY
#define ENOTSOCK   __einfo_error ( EINFO_ENOTSOCK )
 Not a socket.
#define EINFO_ENOTSOCK
#define ENOTSUP   __einfo_error ( EINFO_ENOTSUP )
 Operation not supported.
#define EINFO_ENOTSUP
#define ENOTTY   __einfo_error ( EINFO_ENOTTY )
 Inappropriate I/O control operation.
#define EINFO_ENOTTY
#define ENXIO   __einfo_error ( EINFO_ENXIO )
 No such device or address.
#define EINFO_ENXIO
#define EOPNOTSUPP   __einfo_error ( EINFO_EOPNOTSUPP )
 Operation not supported on socket.
#define EINFO_EOPNOTSUPP
#define EOVERFLOW   __einfo_error ( EINFO_EOVERFLOW )
 Value too large to be stored in data type.
#define EINFO_EOVERFLOW
#define EPERM   __einfo_error ( EINFO_EPERM )
 Operation not permitted.
#define EINFO_EPERM
#define EPIPE   __einfo_error ( EINFO_EPIPE )
 Broken pipe.
#define EINFO_EPIPE
#define EPROTO   __einfo_error ( EINFO_EPROTO )
 Protocol error.
#define EINFO_EPROTO
#define EPROTONOSUPPORT   __einfo_error ( EINFO_EPROTONOSUPPORT )
 Protocol not supported.
#define EINFO_EPROTONOSUPPORT
#define EPROTOTYPE   __einfo_error ( EINFO_EPROTOTYPE )
 Protocol wrong type for socket.
#define EINFO_EPROTOTYPE
#define ERANGE   __einfo_error ( EINFO_ERANGE )
 Result too large.
#define EINFO_ERANGE
#define EROFS   __einfo_error ( EINFO_EROFS )
 Read-only file system.
#define EINFO_EROFS
#define ESPIPE   __einfo_error ( EINFO_ESPIPE )
 Invalid seek.
#define EINFO_ESPIPE
#define ESRCH   __einfo_error ( EINFO_ESRCH )
 No such process.
#define EINFO_ESRCH
#define ESTALE   __einfo_error ( EINFO_ESTALE )
 Stale file handle.
#define EINFO_ESTALE
#define ETIME   __einfo_error ( EINFO_ETIME )
 Timer expired.
#define EINFO_ETIME
#define ETIMEDOUT   __einfo_error ( EINFO_ETIMEDOUT )
 Connection timed out.
#define EINFO_ETIMEDOUT
#define ETXTBSY   __einfo_error ( EINFO_ETXTBSY )
 Text file busy.
#define EINFO_ETXTBSY
#define EWOULDBLOCK   __einfo_error ( EINFO_EWOULDBLOCK )
 Operation would block.
#define EINFO_EWOULDBLOCK
#define EXDEV   __einfo_error ( EINFO_EXDEV )
 Improper link.
#define EINFO_EXDEV
#define EINFO_EPLATFORM   __einfo ( 0, 0x7f, 0, "Platform-generated error" )
 Platform-generated base error.

Functions

 FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
static void euniq_discard (int dummy __unused,...)
static void eplatform_discard (int dummy __unused,...)

Variables

int errno
 Global "last error" number.

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.


Define Documentation

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

Definition at line 108 of file errno.h.

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

Declare error information.

Parameters:
platformPlatform error code (uncompressed)
posixPOSIX error code (0x00-0x7f)
uniqError disambiguator (0x00-0x1f)
descError description
Return values:
einfoError information

Definition at line 134 of file errno.h.

#define __einfo_platform (   einfo)    __einfo_extract_platform einfo

Get platform error code.

Parameters:
einfoError information
Return values:
platformPlatform error code (uncompressed)

Definition at line 142 of file errno.h.

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

Definition at line 143 of file errno.h.

#define __einfo_posix (   einfo)    __einfo_extract_posix einfo

Get POSIX error code.

Parameters:
einfoError information
Return values:
posixPOSIX error code

Definition at line 151 of file errno.h.

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

Definition at line 152 of file errno.h.

#define __einfo_uniq (   einfo)    __einfo_extract_uniq einfo

Get error disambiguator.

Parameters:
einfoError information
Return values:
uniqError disambiguator

Definition at line 160 of file errno.h.

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

Definition at line 161 of file errno.h.

#define __einfo_desc (   einfo)    __einfo_extract_desc einfo

Get error description.

Parameters:
einfoError information
Return values:
descError description

Definition at line 169 of file errno.h.

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

Definition at line 170 of file errno.h.

#define __einfo_uniqify (   einfo_base,
  uniq,
  desc 
)
Value:
__einfo ( __einfo_platform ( einfo_base ),                      \
                  __einfo_posix ( einfo_base ),                         \
                  uniq, desc )

Declare disambiguated error.

Parameters:
einfo_baseBase error information
uniqError disambiguator (0x00-0x1f)
descError description
Return values:
einfoError information

Definition at line 180 of file errno.h.

#define __einfo_platformify (   einfo_base,
  platform,
  desc 
)
Value:
__einfo ( platform, __einfo_posix ( einfo_base ),               \
                  __einfo_uniq ( einfo_base ), desc )

Declare platform-generated error.

Parameters:
einfo_baseBase error information
platformPlatform error code (uncompressed)
descError description
Return values:
einfoError information

Definition at line 193 of file errno.h.

#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:
einfoError information
Return values:
errnoError code

Definition at line 203 of file errno.h.

#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_baseBase error information
uniqError disambiguator (0x00-0x1f)
...List of expected possible disambiguated errors
Return values:
errorError

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.

#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_baseBase error information
platformPlatform error code (uncompressed)
...List of expected possible platform-generated errors
Return values:
errorError

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.

#define __einfo_error (   einfo)
Value:
( {                                     \
        __asm__ ( ".section \".einfo\", \"\", " PROGBITS_OPS "\n\t"     \
                  ".align 8\n\t"                                        \
                  "\n1:\n\t"                                            \
                  ".long ( 4f - 1b )\n\t"                               \
                  ".long %a0\n\t"                                       \
                  ".long ( 2f - 1b )\n\t"                               \
                  ".long ( 3f - 1b )\n\t"                               \
                  ".long %a1\n\t"                                       \
                  "\n2:\t.asciz \"" __einfo_desc ( einfo ) "\"\n\t"     \
                  "\n3:\t.asciz \"" __FILE__ "\"\n\t"                   \
                  ".align 8\n\t"                                        \
                  "\n4:\n\t"                                            \
                  ".previous\n\t" : :                                   \
                  "i" ( __einfo_errno ( einfo ) ),                      \
                  "i" ( __LINE__ ) );                                   \
        __einfo_errno ( einfo ); } )

Declare error.

Parameters:
einfoError information
Return values:
errorError

Definition at line 260 of file errno.h.

#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 ( GPL2_OR_LATER_OR_UBDL  )
static void euniq_discard ( int dummy  __unused,
  ... 
) [inline, static]

Definition at line 229 of file errno.h.

{}
static void eplatform_discard ( int dummy  __unused,
  ... 
) [inline, static]

Definition at line 252 of file errno.h.

{}

Variable Documentation

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(), strerror(), and tg3_init_one().