.. _c_imp: C Implementation-Defined Behavior ================================= A conforming C99 implementation is required to document its choice of behavior for all parts of the language specification that are designated *implementation-defined*. The tools implementation-defined behavior matches that of `GCC 4.2.1 `_ except for the choices listed below. The following section headings refer to sections in the :ref:`C99 specification ` and all choices that depend on an externally determined application binary interface are listed as "determined by ABI," and are documented in the :ref:`Application Binary Interface Specification `. Only the supported C99 features are documented. .. _c_imp_environment: Environment ----------- * The name and type of the function called at program startup in a freestanding environment (5.1.2.1). A hosted environment is provided. * An alternative manner in which the ``main`` function may be defined (5.1.2.2.1). There is no alternative manner in which ``main`` may be defined. * The values given to the strings pointed to by ``argv`` argument to ``main`` (5.1.2.2.1). The value of ``argc`` is equal to zero. ``argv[0]`` is a null pointer. There are no other array members. * What constitutes an interactive device (5.1.2.3). All streams are refer to interactive devices. * Signal values other than ``SIGFPE``, ``SIGILL``, and ``SIGSEGV`` that correspond to a computational exception (7.14.1.1). No other signal values correspond to a computational exception. * Signal values for which is equivalent of ``signal(sig, SIG_IGN);`` is executed at program startup (7.14.1.1). At program startup the equivalent of ``signal(sig, SIG_DFL);`` is executed for all signals. * The set of environment names and the method for altering the environment list used by the ``getenv`` function (7.20.4.5). The set of environment names is empty. There is no method for altering the environment list used by the ``getenv`` function. * The manner of execution of the string by the ``system`` function used by the ``getenv`` function (7.20.4.6). This is determined by the execution environment. .. _c_imp_identifiers: Identifiers ----------- * The number of significant initial characters in an identifier (5.2.4.1, 6.4.1). All characters in identifiers (with or without external linkage) are significant. .. _c_imp_characters: Characters ---------- * The value of the members of the execution character set (5.2.1). This is determined by the ASCII character set. * The unique value of the member of the execution character set produced for each of the standard alphabetic escape sequences (5.2.2). This is determined by the ASCII character set. * The value of a ``char`` object into which has been stored any character other than a member of the basic execution set (6.2.5). The value of any character other than a member of the basic execution set is determined by the ASCII character set. * The mapping of members of the source character set (in character constants and string literals) to members of the execution character set (6.4.4.4, 5.1.1.2). The source character set is required to be the ASCII character set. Each character in the source character set is mapped to the same character in the execution character set. * The value of an integer character constant containing more than one character or containing a character or escape sequence that does not map to a single-byte execution character (6.4.4.4). The value of an integer character constant containing more than one character is equal to the value of the last character in the character constant. The value of an integer character constant containing a character or escape sequence that does not map to a single-byte execution character is equal to the value reduced modulo 2 :sup:`*n*` to be within range of the ``char`` type, where *n* is the number of bits in a ``char``. * The value of a wide character constant containing more than one multibyte character, or containing a multibyte character or escape multibyte character, or containing a multibyte character or escape sequence not represented in the extended execution character set (6.4.4.4). Wide character constants must not contain multibyte characters. * The current locale used to convert a wide character constant consisting of a single multibyte character that maps to a member of the extended execution character set into a corresponding wide character code (6.4.4.4). Wide character constants must not contain multibyte characters. * The value of a string literal containing a multibyte character or escape sequence not represented in the execution character set (6.4.5). String literals must not contain multibyte characters. If an escape sequence not represented in the execution character set is used in a string literal, the value of the corresponding character in the string is the same as the value that would be given to an integer character constant consisting of that escape sequence. .. _c_imp_floating_point: Floating point -------------- * The accuracy of the floating-point operations and of the library functions in ```` and ```` that return floating-point results (5.2.4.2.2). This is intentionally left undocumented. * Additional floating-point exceptions, rounding modes, environments, and classifications, and their macros names (7.6, 7.12). No additional floating-point exceptions, rounding modes, environments or classifications are defined. .. _c_imp_hints: Hints ----- * The extent to which suggestions made by using the ``register`` storage-class specifier are effective (6.7.1). The ``register`` specifier is ignored except when used as part of the register variable extension. .. _c_imp_preprocessing_directives: Preprocessing directives ------------------------ * The behavior on each recognized non-STDC ``#pragma`` directive (6.10.6). This is documented in :ref:`xcc_pragma_directives`. .. _c_imp_library_functions: Library functions ----------------- * Any library facilities available to a freestanding program, other than the minimal set required by clause 4 (5.1.2.1). A hosted environment is provided. * The format of the diagnostic printed by the ``assert`` macro (7.2.1.1). The ``assert`` macro uses the format "Assertion failed: *expression*, file *filename*, line *line number*, function: *function*." where *expression* is the text of the argument, *filename* is the value of ``__FILE__``, *line number* is the value of ``__LINE__`` and *function* is the name of the current function. If the name of the current function cannot be determined, this part of the message is omitted. * The representation of the floating-point status flags stored by the ``fegetexceptflag`` function (7.6.2.2). The function ``fegetexceptflag`` is not supported. * Whether the ``feraiseexcept`` function raises the "inexact" floating-point exception in addition to the "overflow" and "underflow" floating-point exception (7.6.2.3). The function ``feraiseexcept`` is not supported. * Strings other than ``"C"`` and ``""`` that may be passed as the second argument to the ``setlocale`` function (7.11.1.1). No other strings may be passed as the second argument to the ``setlocale`` function. * The types defined for ``float_t`` and ``double_t`` when the value of the ``FLT_EVAL_METHOD`` macro is less than 0 or greater than 2 (7.12). No other values of the ``FLT_EVAL_METHOD`` macro are supported. * Domain errors for the mathematics functions, other than those required by this International Standard (7.12.1). This is intentionally left undocumented. * The values returned by the mathematics functions on domain errors (7.12.1). This is intentionally left undocumented. * The values returned by the mathematics functions on underflow range errors, whether ``errno`` is set to the value of the macro ``ERANGE`` when the integer expression ``math_errhandling & MATH_ERRNO`` is nonzero, and whether the "underflow" floating-point exception is raised when the integer expression ``math_errhandling & MATH_ERREXCEPT`` is nonzero (7.12.1). This is intentionally left undocumented. * Whether a domain error occurs or zero is returned when an ``fmod`` function has a second argument of zero (7.12.10.1). A domain error occurs when an ``fmod`` function has a second argument of zero. * The base-2 logarithm of the modulus used by the ``remquo`` functions in reducing the quotient (7.12.10.3). The quotient is reduced modulo 2 :sup:`7`. * Whether the equivalent of ``signal(sig, SIG_DFL);`` is executed prior to the call of a signal handler, and, if not, the blocking of signals that is performed (7.14.1.1). The equivalent of ``signal(sig, SIG_DFL);`` is executed prior to the call of a signal handler. * The null pointer constant to which the macro ``NULL`` expands (7.17). ``NULL`` is defined as ``((void *)0)``. * Whether the last line of a text stream requires a terminating new-line character (7.19.2). This is determined by the execution environment. * Whether space characters that are written out to a text stream immediately before a newline character appear when read in (7.19.2). This is determined by the execution environment. * The number of null characters that may be appended to data written to a binary stream (7.19.2). This is determined by the execution environment. * Whether the file position indicator of an append-mode stream is initially positioned at the beginning or end of a file (7.19.3). This is determined by the execution environment. * Whether a write on a text stream causes the associated file to be truncated beyond that point (7.19.3). This is determined by the execution environment. * The characteristics of file buffering (7.19.3). A buffered output stream saves characters until the buffer is full and then writes the characters as a block. A line buffered output stream saves characters until the line is complete or the buffer is full and then writes the characters as a block. An unbuffered output stream writes characters to the destination file immediately. * Whether a zero-length file actually exists (7.19.3). This is determined by the execution environment. * The rules for composing valid file names (7.19.3). This is determined by the execution environment. * Whether the same file can be simultaneously opened multiple times (7.19.3). This is determined by the execution environment. * The nature and choice of encodings used for multibyte characters in files (7.19.3). The execution character set must not contain multibyte characters. * The effect of the ``remove`` function on an open file (7.19.4.1). This is determined by the execution environment. * The effect if a file with the new name exists prior to a call to the ``rename`` function (7.19.4.1). This is determined by the execution environment. * Whether an open temporary file is removed upon abnormal program termination (7.19.4.3). Temporary files are not removed on abnormal program termination. * Which changes of mode are permitted (if any), and under what circumstances (7.19.5.4). The file cannot be given a more permissive access mode (for example, a mode of "w" will fail on a read-only file descriptor), but can change status such as append or binary mode. If modification is not possible, failure occurs. * The style used to print an infinity or *NaN*, and the meaning of any n-char or n-wchar sequence printed for a *NaN* (7.19.6.1, 7.24.2.1). A ``double`` argument representing infinity is converted in the style ``[-]inf``. A ``double`` argument representing a *NaN* is converted in the style as ``nan``. * The output for ``%p`` conversion in the ``fprintf`` or ``fwprintf`` function (7.19.6.1, 7.24.2.1). The value of the pointer is converted to unsigned hexadecimal notation in the style *dddd*; the letters ``abcdef`` are used for the conversion. The precision specifies the minimum number of digits to appear; if the value being converted can be represented in fewer digits, it is expanded with leading zeros. The default precision is 1. The characters ``0x`` are prepended to the output. The ``fwprintf`` function is unsupported. * The interpretation of a ``-`` character that is neither the first nor the last character, nor the second where a ``^`` character is the first, in the scanlist for ``%[`` conversion in the ``fscanf`` or ``fwscanf`` function (7.19.6.2, 7.24.2.1). The ``-`` character is considered to define a range if the character following it is numerically greater than the character before it. Otherwise the ``-`` character itself is added to the scanset. The ``fwscanf`` function is unsupported. * The set of sequences matched by a ``%p`` conversion and the interpretation of the corresponding input item in the ``fscanf`` or ``fwscanf`` function (7.19.6.2, 7.24.2.2). ``%p`` matches the same format as ``%x``. The corresponding input item is converted to a pointer. The ``fwscanf`` function is unsupported. * The meaning of any n-char or n-wchar sequence in a string representing *NaN* that is converted by the ``strtod``, ``strtof``, ``strtold``, ``wcstod``, ``wcstof`` or ``wcstold`` function (7.20.1.3, 7.24.4.1.1). The functions ``wcstod``, ``wcstof`` and ``wcstold`` are not supported. A n-char sequence in a string representing *NaN* is scanned in hexadecimal form. Any characters which are not hexadecimal digits are ignored. * Whether or not the ``strtod``, ``strtof``, ``strtold``, ``wcstod``, ``wcstof`` or ``wcstold`` function sets ``errno`` to ``ERANGE`` when underflow occurs (7.20.1.3, 7.24.4.1.1). The functions ``wcstod``, ``wcstof`` and ``wcstold`` are not supported. The functions ``strtod``, ``strtof`` and ``strtold`` do not set ``errno`` to ``ERANGE`` when and return 0 when underflow occurs. * Whether the ``calloc``, ``malloc``, and ``realloc`` functions return a null pointer or a pointer to an allocated object when the size requested is zero (7.20.3). The functions ``calloc``, ``malloc`` and ``realloc`` functions all return a pointer to an allocated object when the size requested is zero. * Whether open streams with unwritten buffered data are flushed, open streams are closed, or temporary files are removed when the ``abort`` or ``_Exit`` function is called (7.20.4.1, 7.20.4.3, 7.20.4.4). When the ``abort`` function or ``_Exit`` function is called, temporary files are not removed, buffered files are not flushed and open streams are left open. * The termination status returned to the host environment by the ``abort``, ``exit`` or ``_Exit`` function (7.20.3). The function ``abort`` causes a software exception to be raised. The termination status returned to the host environment by the functions ``exit`` and ``_Exit`` is determined by the execution environment. * The value returned by the ``system`` function when its argument is not a null pointer (7.20.4.6). This is determined by the execution environment. * The range and precision of times representable in ``clock_t`` and ``time_t`` (7.23.1). The precision of times representable in ``time_t`` is defined by the execution environment. ``time_t`` designates an ``unsigned long``. The actual range of times representable by ``time_t`` is defined by the execution environment. The macro ``CLOCKS_PER_SEC`` is defined as ``1000``. ``clock_t`` designates an unsigned long. * The era for the ``clock`` function (7.23.2.1). The ``clock`` function always returns the value ``(clock_t)(-1)`` to indicate that the processor time used is not available. * The replacement string for the ``%Z`` specifier to the ``strftime`` and ``wcsftime`` functions in the ``"C"`` locale (7.23.3.5, 7.24.5.1). The ``%Z`` specifier is replaced with the string "GMT". .. _c_imp_locale_specific_behavior: Locale-Specific Behavior ------------------------ * Additional members of the source and execution character sets beyond the basic character set (5.2.1). Both the source and execution character sets include all members of the ASCII character set. * The presence, meaning, and representation of additional multibyte characters in the execution character set beyond the basic character set (5.2.1.2). The execution character set does not contain multibyte characters. * The shift states used for the encoding of multibyte characters (5.2.1.2). The source and execution character sets does not contain multibyte characters. * The direction of writing of successive printing characters (5.2.2). Characters are printed from left to right. * The decimal-point character (7.1.1). The decimal-point character is '``.``'. * The set of printing characters (7.4, 7.25.2). This is determined by the ASCII character set. * The set of control characters (7.4, 7.25.2). This is determined by the ASCII character set. * The set of characters tested for by the ``isalpha``, ``isblank``, ``islower``, ``ispunct``, ``isspace``, ``isupper``, ``iswalpha``, ``iswblank``, ``iswlower``, ``iswpunct``, ``iswspace``, or ``iswupper`` functions (7.4.1.2, 7.4.1.3, 7.4.1.7, 7.4.1.9, 7.4.1.10, 7.4.1.11, 7.25.2.1.2, 7.25.2.1.3, 7.25.2.1.7, 7.25.2.1.9, 7.25.2.1.10, 7.25.2.1.11). The functions ``isblank``, ``iswalpha``, ``iswblank``, ``iswlower``, ``iswpunct``, ``iswspace`` and ``iswupper`` are not supported. ``islower`` tests for the characters '``a`` to '``z``'. ``isupper`` tests for the characters '``A``' to '``Z``'. ``isspace`` tests for the characters ' ', '``\f``', '``\n``', '``\r``', '``\t``' and '``\v``'. ``isalpha`` tests for upper and lower case characters. ``ispunct`` tests for all printable characters except space and alphanumeric characters. * The native environment (7.11.1.1). The native environment is the same as the minimal environment for C translation. * Additional subject sequences accepted by the numerical conversion functions (7.20.1, 7.24.4.1). No additional subject sequences are accepted by the numerical conversion functions. * The collation sequence of the execution character set (7.21.4.3, 7.24.4.4.2). The comparison carried out by the function ``strcoll`` is identical to the comparison carried out by the function ``strcmp``. * The contents of the error message strings set up by the ``strerror`` function (7.21.4.3, 7.24.4.4.2). The contents of the error message strings are given in :ref:`c_imp_error_message_strings`. .. tabularcolumns:: p{2cm}p{4cm} .. _c_imp_error_message_strings: .. table:: Error message strings +------------------+------------------------------------+ | Value | String | +==================+====================================+ | ``EPERM`` | Not owner | +------------------+------------------------------------+ | ``ENOENT`` | No such file or directory | +------------------+------------------------------------+ | ``EINTR`` | Interrupted system call | +------------------+------------------------------------+ | ``EIO`` | I/O error | +------------------+------------------------------------+ | ``ENXIO`` | No such device or address | +------------------+------------------------------------+ | ``EBADF`` | Bad file number | +------------------+------------------------------------+ | ``EAGAIN`` | No more processes | +------------------+------------------------------------+ | ``ENOMEM`` | Not enough space | +------------------+------------------------------------+ | ``EACCES`` | Permission denied | +------------------+------------------------------------+ | ``EFAULT`` | Bad address | +------------------+------------------------------------+ | ``EBUSY`` | Device or resource busy | +------------------+------------------------------------+ | ``EEXIST`` | File exists | +------------------+------------------------------------+ | ``EXDEV`` | Cross-device link | +------------------+------------------------------------+ | ``ENODEV`` | No such device | +------------------+------------------------------------+ | ``ENOTDIR`` | Not a directory | +------------------+------------------------------------+ | ``EISDIR`` | Is a directory | +------------------+------------------------------------+ | ``EINVAL`` | Invalid argument | +------------------+------------------------------------+ | ``ENFILE`` | Too many open files in system | +------------------+------------------------------------+ | ``EMFILE`` | Too many open files | +------------------+------------------------------------+ | ``ETXTBSY`` | Text file busy | +------------------+------------------------------------+ | ``EFBIG`` | File too large | +------------------+------------------------------------+ | ``ENOSPC`` | No space left on device | +------------------+------------------------------------+ | ``ESPIPE`` | Illegal seek | +------------------+------------------------------------+ | ``EROFS`` | Read-only file system | +------------------+------------------------------------+ | ``EMLINK`` | Too many links | +------------------+------------------------------------+ | ``EPIPE`` | Broken pipe | +------------------+------------------------------------+ | ``EDOM`` | Math argument | +------------------+------------------------------------+ | ``ERANGE`` | Result too large | +------------------+------------------------------------+ | ``ENAMETOOLONG`` | File or path name too long | +------------------+------------------------------------+ | ``ENOSYS`` | Function not implemented | +------------------+------------------------------------+ | ``ENOTEMPTY`` | Directory not empty | +------------------+------------------------------------+ | ``ELOOP`` | Too many symbolic links | +------------------+------------------------------------+ * Character classifications that are supported by the ``iswctype`` function (7.25.1). The character classifications supported by ``iswctype`` are given in :ref:`c_imp_wide_char_mappings`. .. tabularcolumns:: p{2cm}p{4cm} .. _c_imp_wide_char_mappings: .. table:: Wide character mappings +------------------+------------------------------------+ | Value | Description | +==================+====================================+ | ``WCT_TOLOWER`` | Convert to lower case | +------------------+------------------------------------+ | ``WCT_TOUPPER`` | Convert to upper case | +------------------+------------------------------------+