The following functions from the POSIX specification are included for convenience:

eCos provides the following additional implementation-specific functions within the standard C library to adjust the date and time settings:

void cyg_libc_time_setdst(
    cyg_libc_time_dst state
);

This function sets the state of Daylight Savings Time. The values for state are:

CYG_LIBC_TIME_DSTNA   unknown
CYG_LIBC_TIME_DSTOFF  off
CYG_LIBC_TIME_DSTON   on

These values will be reflected in the tm_isdst member of a struct tm. No other meaning is given to CYG_LIBC_TIME_DSTNA, and in particular it is not interpreted as any sort of "auto-detect" value, as eCos does not have the extensive timezone information that would be required in order to provide this. A call to mktime() with tm_isdst set to -1 (which corresponds to CYG_LIBC_TIME_DSTNA) will be treated as if the supplied time is in UTC, i.e. with neither standard time nor Daylight Savings Time offsets applied.

void cyg_libc_time_setzoneoffsets(
    time_t stdoffset, time_t dstoffset
);

This function sets the offsets from UTC used when Daylight Savings Time is enabled or disabled. The offsets are in time_t‚s, which are seconds in the current inplementation.

Cyg_libc_time_dst cyg_libc_time_getzoneoffsets(
    time_t *stdoffset, time_t *dstoffset
);

This function retrieves the current setting for Daylight Savings Time along with the offsets used for both STD and DST. The offsets are both in time_t‚s, which are seconds in the current implementation.

cyg_bool cyg_libc_time_settime(
      time_t utctime
);

This function sets the current time for the system The time is specified as a time_t in UTC. It returns non-zero on error.

This math library is capable of being operated in several different compatibility modes. These options deal solely with how errors are handled.

There are 4 compatibility modes: ANSI/POSIX 1003.1; IEEE-754; X/Open Portability Guide issue 3 (XPG3); and System V Interface Definition Edition 3.

In IEEE mode, the matherr() function (see below) is never called, no warning messages are printed on the stderr output stream, and errno is never set.

In ANSI/POSIX mode, errno is set correctly, but matherr() is never called and no warning messages are printed on the stderr output stream.

In X/Open mode, errno is set correctly, matherr() is called, but no warning messages are printed on the stderr output stream.

In SVID mode, functions which overflow return a value HUGE (defined in math.h), which is the maximum single precision floating point value (as opposed to HUGE_VAL which is meant to stand for infinity). errno is set correctly and matherr() is called. If matherr() returns 0, warning messages are printed on the stderr output stream for some errors.

The mode can be compiled-in as IEEE-only, or any one of the above methods settable at run-time.

	Note
	This math library assumes that the hardware (or software floating point emulation) supports IEEE-754 style arithmetic, 32-bit 2's complement integer arithmetic, doubles are in 64-bit IEEE-754 format.

9.2.1.  matherr()

As mentioned above, in X/Open or SVID modes, the user can supply a function matherr() of the form:

int matherr( struct exception *e )

where struct exception is defined as:

struct exception {
  int type;
  char *name;
  double arg1, arg2, retval;
}; 

type is the exception type and is one of:

DOMAIN

argument domain exception

SING

argument singularity

OVERFLOW

overflow range exception

UNDERFLOW

underflow range exception

TLOSS

total loss of significance

PLOSS

partial loss of significance

name is a string containing the name of the function

arg1 and arg2 are the arguments passed to the function

retval is the default value that will be returned by the function, and can be changed by matherr()

	Note
	matherr must have “C” linkage, not “C++” linkage.

If matherr returns zero, or the user doesn't supply their own matherr, then the following usually happens in SVID mode:

Table 9.1. Behavior of math exception handling

Type	Behavior
DOMAIN	0.0 returned, errno=EDOM, and a message printed on stderr
SING	HUGE of appropriate sign is returned, errno=EDOM, and a message is printed on stderr
OVERFLOW	HUGE of appropriate sign is returned, and errno=ERANGE
UNDERFLOW	0.0 is returned and errno=ERANGE
TLOSS	0.0 is returned, errno=ERANGE, and a message is printed on stderr
PLOSS	The current implementation doesn't return this type

X/Open mode is similar except that the message is not printed on stderr and HUGE_VAL is used in place of HUGE

Here are some details about the implementation which might be interesting, although they do not affect the ISO-defined semantics of the library.

Here is a minimal eCos program which demonstrates the use of environments (see also the test case in language/c/libc/VERSION/tests/stdlib/getenv.c):

#include <stdio.h>
#include <stdlib.h> // Main header for stdlib functions

extern char **environ; // Standard environment definition

int
main( int argc, char *argv[] )
{
    char *str;
    char *env[] = { "PATH=/usr/local/bin:/usr/bin",
    "HOME=/home/fred",
    "TEST=1234=5678",
    "home=hatstand",
    NULL };

    printf("Display the current PATH environment variable\n");

    environ = (char **)&env;

    str = getenv("PATH");

    if (str==NULL) {
        printf("The current PATH is unset\n");
    } else {
        printf("The current PATH is \"%s\"\n", str);
    }
    return 0;
} 

The ISO C library has configuration options that control thread safety, i.e. working behavior if multiple threads call the same function at the same time.

The following functionality has to be configured correctly, or used carefully in a multi-threaded environment:

In some cases, to make eCos development easier, functions are provided (as specified by POSIX 1003.1) that define re-entrant alternatives, i.e. rand_r(), strtok_r(), asctime_r(), ctime_r(), gmtime_r(), and localtime_r(). In other cases, configuration options are provided that control either locking of functions or their shared data, such as with standard I/O streams, or by using per-thread data, such as with the errno variable.

In some other cases, like the setting of date and time, no re-entrant or thread-safe alternative or configuration is provided as it is simply not a worthwhile addition (date and time should rarely need to be set.)

The C library includes a function declared as:

void cyg_iso_c_start( void )

This function is used to start an environment in which an ISO C style program can run in the most compatible way.

What this function does is to create a thread which will invoke main() — normally considered a program's entry point. In particular, it can supply arguments to main() using the CYGDAT_LIBC_ARGUMENTS configuration option, and when returning from main(), or calling exit(), pending stdio file output is flushed and any functions registered with atexit() are invoked. This is all compliant with the ISO C standard in this respect.

This thread starts execution when the eCos scheduler is started. If the eCos kernel package is not available (and hence there is no scheduler), then cyg_iso_c_start() will invoke the main() function directly, i.e. it will not return until the main() function returns.

The main() function should be defined as the following, and if defined in a C++ file, should have “C” linkage:

extern int main(
    int argc,
    char *argv[] )

The thread that is started by cyg_iso_c_start() can be manipulated directly, if you wish. For example you can suspend it. The kernel C API needs a handle to do this, which is available by including the following in your source code.

extern cyg_handle_t cyg_libc_main_thread;

Then for example, you can suspend the thread with the line:

cyg_thread_suspend( cyg_libc_main_thread );

If you call cyg_iso_c_start() and do not provide your own main() function, the system will provide a main() for you which will simply return immediately.

In the default configuration, cyg_iso_c_start() is invoked automatically by the cyg_package_start() function in the infrastructure configuration. This means that in the simplest case, your program can indeed consist of simply:

int main( int argc, char *argv[] )
{
    printf("Hello eCos\n");
}

If you override cyg_package_start() or cyg_start(), or disable the infrastructure configuration option CYGSEM_START_ISO_C_COMPATIBILITY then you must ensure that you call cyg_iso_c_start() yourself if you want to be able to have your program start at the entry point of main() automatically.