SFI-Functions - SFI Function Reference

Document Revised: Wed May 25 23:38:16 2005

CBg_file_test_all(CIfile, CItest);

CBsfi_file_check(CIfile, CImode);

CBsfi_file_crawler_add_search_path(CIself, CIpattern_paths, CIfile_pattern);

CBsfi_file_crawler_add_tests(CIself, CItests);

CBsfi_file_crawler_crawl(CIself);

CBsfi_file_crawler_destroy(CIself);

CBsfi_file_crawler_list_files(CIsearch_path, CIfile_pattern, CIfile_test);

CBsfi_file_crawler_needs_crawl(CIself);

CBsfi_file_crawler_new();

CBsfi_file_crawler_pop(CIself);

CBsfi_file_crawler_set_cwd(CIself, CIcwd);

CBsfi_guard_deregister(CIguard);

CBsfi_guard_is_protected(CIvalue);

CBsfi_guard_n_snap_values();

CBsfi_guard_protect(CIguard, CInth_hazard, CIvalue);

CBsfi_guard_register(CIn_hazards);

CBsfi_guard_snap_values(CIn_values, CIvalues);

CBsfi_msg_default_handler(CImsg);

CBsfi_msg_log_elist(CIlog_domain, CImtype, CIlbit1, CIlbit2, CI...);

CBsfi_msg_log_printf(CIlog_domain, CIlevel, CIformat, CI...);

CBsfi_msg_log_trampoline(CIlog_domain, CImtype, CIlbit1, CIlbit2, CIlbitargs, CIhandler, CIvbitlist);

CBsfi_msg_set_thread_handler(CIhandler);

CBsfi_msg_type_ident(CImtype);

CBsfi_msg_type_label(CImtype);

CBsfi_msg_type_lookup(CIident);

CBsfi_msg_type_register(CIident, CIdefault_ouput, CIlabel, CIRETURN);

CBsfi_path_get_filename(CIfilename, CIparentdir);

CBsfi_ring_split(CIhead1, CIhead2);

CBsfi_thread_abort(CIthread);

CBsfi_thread_aborted();

CBsfi_thread_awake_after(CIstamp);

CBsfi_thread_emit_wakeups(CIwakeup_stamp);

CBsfi_thread_get_name(CIthread);

CBsfi_thread_get_pid(CIthread);

CBsfi_thread_queue_abort(CIthread);

CBsfi_thread_run(CIname, CIfunc, CIuser_data);

CBsfi_thread_self();

CBsfi_thread_self_pid();

CBsfi_thread_set_wakeup(CIwakeup_func, CIwakeup_data, CIdestroy);

CBsfi_thread_sleep(CImax_useconds);

CBsfi_thread_wakeup(CIthread);

CBsfi_time_from_string(CItime_string);

CBsfi_time_from_string_err(CItime_string, CIerror_p);

CBsfi_time_from_utc(CIustime);

CBsfi_time_system();

CBsfi_time_to_string(CIustime);

CBsfi_time_to_utc(CIustime);

CBg_file_test_all(CIfile, CItest); nokeep; l l l. CIconst gchar* CIfile; T{ a file to test T} CIGFileTest CItest; T{ bitfield of CIGFileTest flags T}

This is the AND version of CBg_file_test(). That is, all file tests specified in the CItest bits have to succed for this function to return TRUE. This function is implemented via CBsfi_file_check(), which allowes for more detailed mode tests and is recommended over use of this function. Here is the list of possible CIGFileTest flags:

G_FILE_TEST_IS_REGULAR - test for a recular file

G_FILE_TEST_IS_SYMLINK - test for a symlink

G_FILE_TEST_IS_DIR - test for a directory

G_FILE_TEST_IS_EXECUTABLE - test for an executable

G_FILE_TEST_EXISTS - test whether the file exists

CBsfi_file_check(CIfile, CImode); nokeep; l l l. CIconst gchar* CIfile; T{ possibly relative filename T} CIconst gchar* CImode; T{ feature string T} h'-2m'CIRETURNS: T{ TRUE if CIfile adhears to CImode T}

Perform various checks on CIfile and return whether all checks passed. On failure, errno is set appropriately, and FALSE is returned. Available features to be checked for are:

e - CIfile must exist

r - CIfile must be readable

w - CIfile must be writable

x - CIfile must be executable

f - CIfile must be a regular file

d - CIfile must be a directory

l - CIfile must be a symbolic link

c - CIfile must be a character device

b - CIfile must be a block device

p - CIfile must be a named pipe

s - CIfile must be a socket.

CBsfi_file_crawler_add_search_path(CIself, CIpattern_paths, CIfile_pattern); nokeep; l l l. CISfiFileCrawler* CIself; T{ valid CISfiFileCrawler T} CIconst gchar* CIpattern_paths; T{ colon (semicolon under win32) seperated search path T} CIconst gchar* CIfile_pattern; T{ wildcard pattern for file names T} h'-2m'CIRETURNS: T{ a singly linked list with newly allocated strings T}

This function takes a search path (possibly containing wildcards) and adds them to the file crawlers search list. If CIfile_pattern is non NULL, it is appended to each directory element extracted from CIpattern_paths, before attempting file system searches. CBsfi_file_crawler_needs_crawl() may return TRUE after calling this function.

CBsfi_file_crawler_add_tests(CIself, CItests); nokeep; l l l. CISfiFileCrawler* CIself; T{ valid CISfiFileCrawler T} CIGFileTest CItests; T{ CIGFileTest test flags T}

By default, results returned by CIself are only tested for existence. If additional file tests have to be met by the results, they can be set by this function.

CBsfi_file_crawler_crawl(CIself); nokeep; l l l. CISfiFileCrawler* CIself; T{ valid CISfiFileCrawler T}

Collect the next file or directory if possible, new results need not arrive after calling this function, and more than one may. This function does nothing if CBsfi_file_crawler_needs_crawl() returns FALSE.

CBsfi_file_crawler_destroy(CIself); nokeep; l l l. CISfiFileCrawler* CIself; T{ valid CISfiFileCrawler T}

Destroy an existing file crawler and free any resources allocated by it.

CBsfi_file_crawler_list_files(CIsearch_path, CIfile_pattern, CIfile_test); nokeep; l l l. CIconst gchar* CIsearch_path; T{ colon (semicolon under win32) seperated search path with '?' and '*' wildcards T} CIconst gchar* CIfile_pattern; T{ wildcard pattern for file names T} CIGFileTest CIfile_test; T{ GFileTest file test condition (e.g. G_FILE_TEST_IS_REGULAR) or 0 T} h'-2m'CIRETURNS: T{ an CISfiRing with newly allocated strings T}

Given a search path with wildcards, list all files matching CIfile_pattern, contained in the directories which the search path matches. Files that do not pass CIfile_test are not listed.

CBsfi_file_crawler_needs_crawl(CIself); nokeep; l l l. CISfiFileCrawler* CIself; T{ valid CISfiFileCrawler T}

RETURNS: TRUE if CBsfi_file_crawler_crawl() should be called Figure whether collecting all matching files has finished now. If not, CBsfi_file_crawler_crawl() needs to be called until this function returns FALSE.

CBsfi_file_crawler_new(); Create a new file crawler. A file crawler collects all files matching a given search path and file test. CBsfi_file_crawler_crawl() needs to be called as long as CBsfi_file_crawler_needs_crawl() returns TRUE to collect all matching files.

CBsfi_file_crawler_pop(CIself); nokeep; l l l. CISfiFileCrawler* CIself; T{ valid CISfiFileCrawler T}

RETURNS: newly allocated string containig resulting filename Fetch next result if any or NULL.

CBsfi_file_crawler_set_cwd(CIself, CIcwd); nokeep; l l l. CISfiFileCrawler* CIself; T{ valid CISfiFileCrawler T} CIconst gchar* CIcwd; T{ absolute path T}

Set the path to be assumed the current working directory.

CBsfi_guard_deregister(CIguard); nokeep; l l l. CISfiGuard* CIguard; T{ a valid CISfiGuard as returned from CBsfi_guard_register() T}

Deregister a guard previously registered by a call to CBsfi_guard_register(). Deregistration is performed in constant time.

CBsfi_guard_is_protected(CIvalue); nokeep; l l l. CIgpointer CIvalue; T{ hazard pointer value T} h'-2m'CIRETURNS: T{ TRUE if a hazard pointer protecting CIvalue has been found T}

Check whether CIvalue is protected by a hazard pointer guard. If multiple pointer values are to be checked, use CBsfi_guard_snap_values() instead, as this function has CBO(n_hazard_pointers) time complexity. If only one pointer value needs to be looked up though, calling CBsfi_guard_is_protected() will provide a result faster than calling CBsfi_guard_snap_values() and looking up the pointer in the filled-in array. Lookup within hazard pointer arrays will always occour in ascending order to allow pointer migration as described in CBsfi_guard_snap_values() and CBsfi_guard_register().

CBsfi_guard_n_snap_values(); nokeep; l l l. h'-2m'CIRETURNS: T{ an upper bound on the number of registered hazard pointers T}

Retrieve an upper bound on the number of hazard pointer value slots currently required for a successfull call to CBsfi_guard_snap_values(). Note that a subsequent call to CBsfi_guard_snap_values() may still fail due to addtional guards being registerted meanwhile. In such a case CBsfi_guard_n_snap_values() and CBsfi_guard_snap_values() can simply be called again.

CBsfi_guard_protect(CIguard, CInth_hazard, CIvalue); nokeep; l l l. CISfiGuard* CIguard; T{ a valid CISfiGuard as returned from CBsfi_guard_register() T} CIguint CInth_hazard; T{ index of the hazard pointer to use for protection T} CIgpointer CIvalue; T{ a hazardous pointer value or NULL to reset protection T}

Protect the node pointed to by CIvalue from being destroyed by another thread and against the ABA problem caused by premature reuse. For this to work, threads destroying nodes of the type pointed to by CIvalue need to suspend destruction as long as nodes are protected, which can by checked by calls to CBsfi_guard_is_protected() or by searching the values returned from CBsfi_guard_snap_values(). Descriptions of safe memory reclamation and ABA problem detection via hazard pointers guards can be found in CIhttp://www.research.ibm.com/people/m/michael/podc-2002.pdf , CIhttp://www.cs.brown.edu/people/mph/HerlihyLM02/smli_tr-2002-112.pdf , CIhttp://research.sun.com/scalable/Papers/CATS2003.pdf and CIhttp://www.research.ibm.com/people/m/michael/ieeetpds-2004.pdf . The exact sequence of steps to protect and access a node is as follows:

1) Store the adress of a node to be protected in a hazard pointer

2) Verify that the hazard pointer points to a valid node

3) Dereference the node only as long as it's protected by the hazard pointer.

For example:

0: SfiGuard *guard = sfi_guard_register (1);

1: peek_head_label:

2: auto GSList *node = shared_list_head;

3: sfi_guard_protect (guard, 0, node);

4: if (node != shared_list_head) goto peek_head_label;

5: operate_on_protected_node (node);

6: sfi_guard_deregister (guard);

CBsfi_guard_register(CIn_hazards); nokeep; l l l. CIguint CIn_hazards; T{ number of required hazard pointers T} h'-2m'CIRETURNS: T{ a valid CISfiGuard T}

Retrieve a new guard for node protection of the current thread. The exact mechanism of protection is described in CBsfi_guard_protect(). Note that CBsfi_guard_snap_values() will walk the hazard pointer array in ascending order, so that pointers may migrate from array positions with a lower index to positions with a higher index while retaining protection, according to condition C2 as described in CIhttp://www.research.ibm.com/people/m/michael/podc-2002.pdf . If an equally or bigger sized hazard pointer array was previously deregistered by this thread, registration takes constant time.

CBsfi_guard_snap_values(CIn_values, CIvalues); nokeep; l l l. CIguint* CIn_values; T{ location of n_values variable T} CIgpointer* CIvalues; T{ value array to fill in T} h'-2m'CIRETURNS: T{ TRUE if CIvalues provided enough space and is filled T}

Make a snapshot of all non-NULL hazard pointer values. TRUE is returned if the number of non-NULL hazard pointer values didn't exceed the size of the input value array provided by CIn_values, and all values are returned in the array pointed to by CIvalues. The number of values filled in is returned in CIn_values. FALSE is returned if not enough space was available to return all non-NULL values. CBsfi_guard_n_snap_values() may be used to retrieve the current upper bound on the number of registered guards. Note that a successive call to CBsfi_guard_snap_values() with the requested number of value slots supplied may still fail, because additional guards may have been registered meanwhile. In such a case CBsfi_guard_n_snap_values() and CBsfi_guard_snap_values() can simply be called again. This funciton will always walk the hazard pointer arrays supplied by CBsfi_guard_register() in ascending order, to allow pointer migration from lower to higher array indieces while retaining protection. The returned pointer values are unordered, so in order to perform multiple pointer lookups, we recommend sorting the returned array and then doing binary lookups. However if only a single pointer is to be looked up, calling CBsfi_guard_is_protected() should be considered.

CBsfi_msg_default_handler(CImsg); nokeep; l l l. CIconst SfiMessage* CImsg; T{

T}

This is the standard message handler, it produces CImessage in a prominent way on stderr. This function is MT-safe and may be called from any thread.

CBsfi_msg_log_elist(CIlog_domain, CImtype, CIlbit1, CIlbit2, CI...); nokeep; l l l. CIlog_domain; T{ log domain T} CImtype; T{ one of SFI_MSG_ERROR, SFI_MSG_WARNING, SFI_MSG_INFO, SFI_MSG_DIAG T} CIlbit1; T{ msg bit T} CIlbit2; T{ msg bit T} CI...; T{ list of more msg bits, NULL terminated T}

Log a message through SFIs logging mechanism. The current value of errno is preserved around calls to this function. Usually this function isn't used directly, but CBsfi_log_msg() is called instead which does not require NULL termination of its argument list and automates the CIlog_domain argument. The CIlog_domain indicates the calling module and relates to G_LOG_DOMAIN as used by CBg_log(). The msg bit arguments passed in form various parts of the log message, the following macro set is provided to construct the parts from printf-style argument lists: - CBSFI_MSG_TITLE(): format message title - CBSFI_MSG_TEXT1(): format primary message (also CBSFI_MSG_PRIMARY()) - CBSFI_MSG_TEXT2(): format secondary message, optional (also CBSFI_MSG_SECONDARY()) - CBSFI_MSG_TEXT3(): format details of the message, optional (also CBSFI_MSG_DETAIL()) - CBSFI_MSG_CHECK(): format configuration check statement to enable/disable log messages of this type. This function is MT-safe and may be called from any thread.

CBsfi_msg_log_printf(CIlog_domain, CIlevel, CIformat, CI...); nokeep; l l l. CIlog_domain; T{ log domain T} CIlevel; T{ one of SFI_MSG_ERROR, SFI_MSG_WARNING, SFI_MSG_INFO, SFI_MSG_DIAG or SFI_MSG_DEBUG T} CIformat; T{ printf-like format T} CI...; T{ printf-like arguments T}

Log a message through SFIs logging mechanism. The current value of errno is preserved around calls to this function. Usually this function isn't used directly, but through one of CBsfi_debug(), CBsfi_diag(), CBsfi_info(), CBsfi_warn() or CBsfi_error(). The CIlog_domain indicates the calling module and relates to G_LOG_DOMAIN as used by CBg_log(). This function is MT-safe and may be called from any thread.

CBsfi_msg_log_trampoline(CIlog_domain, CImtype, CIlbit1, CIlbit2, CIlbitargs, CIhandler, CIvbitlist); nokeep; l l l. CIlog_domain; T{ log domain T} CImtype; T{ one of SFI_MSG_ERROR, SFI_MSG_WARNING, SFI_MSG_INFO, SFI_MSG_DIAG T} CIlbit1; T{ msg bit T} CIlbit2; T{ msg bit T} CIlbitargs; T{ va_list list of more msg bits, NULL terminated T} CIhandler; T{ message handler T} CIvbitlist; T{ NULL terminated array of msg bits T}

Construct a log message from the arguments given and let CIhandler process it. This function performs no logging on its own, it is used internally by CBsfi_log_msg_elist() to collect arguments and construct a message. All logging functionality has to be implemented by CIhandler. Note that all thread-local msg bits are deleted after invokation of this funtcion, so all msg bits created in the current thread are invalid after calling this function. Direct use of this function is not recommended except for implementations of logging mechanisms. This function is MT-safe and may be called from any thread.

CBsfi_msg_set_thread_handler(CIhandler); nokeep; l l l. CISfiMsgHandler CIhandler; T{ a valid CISfiMsgHandler or NULL T}

Set the handler function for messages logged in the current thread. If NULL is specified as handler, the standard handler will be used. For handler implementations that require an extra data argument, see CBsfi_thread_set_qdata(). This function is MT-safe and may be called from any thread.

CBsfi_msg_type_ident(CImtype); nokeep; l l l. CISfiMsgType CImtype; T{

T}

Retrive the string identifying the message type CItype. For invalid (non registered) message types, NULL is returned. This function is MT-safe and may be called from any thread.

CBsfi_msg_type_label(CImtype); nokeep; l l l. CISfiMsgType CImtype; T{

T}

Retrive the label identifying the message type CItype. Usually, this is a translated version of CBsfi_msg_type_ident() or NULL if non was registered with the message type. This function is MT-safe and may be called from any thread.

CBsfi_msg_type_lookup(CIident); nokeep; l l l. CIconst gchar* CIident; T{ message identifier, e.g. "error", "warning", "info", etc... T}

Find the message type correspondign to CIident. If no message type was found 0 is returned (note that 0 is also the value of SFI_MSG_NONE). This function is MT-safe and may be called from any thread.

CBsfi_msg_type_register(CIident, CIdefault_ouput, CIlabel, CIRETURN); nokeep; l l l. CIident; T{ message identifier T} CIdefault_ouput; T{ an existing CISfiMsgType or FALSE or TRUE T} CIlabel; T{ a translated version of CIident T} CIRETURN; T{ message type id T}

Register a new message type with identifier CIident and user digestible name CIlabel. If this function is called multiple times with the same identifier, the type id acquired by the first call will be returned and the other arguments are ignored. As long as the new message type isn't configured individually via CBsfi_msg_enable(), CBsfi_msg_allow() or their complements, it shares the configuration of CIdefault_ouput. If FALSE or TRUE is passed as CIdefault_ouput, this corresponds to SFI_MSG_NONE or SFI_MSG_FATAL respectively which are unconfigrable and always have their output disabled or enabled respectively. As an exception to the rest of the message API, this function may be called before CBsfi_init(). However note, that MT-safety is only ensured for calls occouring after CBsfi_init(). This function is MT-safe and may be called from any thread.

CBsfi_path_get_filename(CIfilename, CIparentdir); nokeep; l l l. CIconst gchar* CIfilename; T{ possibly relative filename T} CIconst gchar* CIparentdir; T{ possibly relative parent directory path T} h'-2m'CIRETURNS: T{ a newly allocated absolute pathname T}

Construct an absolute filename from CIfilename, using CIparentdir as parent directory if CIfilename is not absolute. If CIparentdir is not absolute, it is assumed to be current directory relative. An exception are filenames starting out with '~' and '~USER', these are interpreted to refer to '/home' or '/home/USER' respectively.

CBsfi_ring_split(CIhead1, CIhead2); nokeep; l l l. CISfiRing* CIhead1; T{ a non-empty ring T} CISfiRing* CIhead2; T{ a ring node different from CIhead1 contained in CIhead1 T} h'-2m'CIRETURNS: T{ CIhead2 for convenience T}

Split a ring into two parts, starting the second ring with CIhead2. CIhead2 must therefore be non-NULL and must be contained in the ring formed by CIhead1.

CBsfi_thread_abort(CIthread); nokeep; l l l. CISfiThread* CIthread; T{ thread to abort T}

Abort a currently running thread. This function does not return until the thread in question terminated execution. Note that the thread handle gets invalidated with invocation of CBsfi_thread_abort() or CBsfi_thread_queue_abort().

CBsfi_thread_aborted(); nokeep; l l l. h'-2m'CIRETURNS: T{ TRUE if the thread should abort execution T}

Find out if the currently running thread should be aborted (the thread is supposed to return from its main thread function). This function or alternatively CBsfi_thread_sleep() should be called periodically, to react to thread abortion requests and to update internal accounting information.

CBsfi_thread_awake_after(CIstamp); nokeep; l l l. CIguint64 CIstamp; T{ stamp to trigger wakeup T}

Wake the current thread up at the next invocation of CBsfi_thread_emit_wakeups() with a wakup_stamp greater than CIstamp.

CBsfi_thread_emit_wakeups(CIwakeup_stamp); nokeep; l l l. CIguint64 CIwakeup_stamp; T{ wakeup stamp to trigger wakeups T}

Wake all currently sleeping threads up which queued a wakeup through CBsfi_thread_awake_after() with a stamp smaller than CIwakeup_stamp.

CBsfi_thread_get_name(CIthread); nokeep; l l l. CISfiThread* CIthread; T{ a valid SfiThread handle T} h'-2m'CIRETURNS: T{ thread name T}

Return the name of CIthread as specified upon invokation of CBsfi_thread_run() or assigned by CBsfi_thread_set_name().

CBsfi_thread_get_pid(CIthread); nokeep; l l l. CISfiThread* CIthread; T{ a valid SfiThread handle T} h'-2m'CIRETURNS: T{ thread id T}

Return the specific id for CIthread. This function is highly system dependant. The thread id may deviate from the overall process id or not. On linux, threads have their own id, allthough since kernel 2.6, they share the same process id.

CBsfi_thread_queue_abort(CIthread); nokeep; l l l. CISfiThread* CIthread; T{ thread to abort T}

Same as CBsfi_thread_abort(), but returns as soon as possible, even if thread hasn't stopped execution yet. Note that the thread handle gets invalidated with invocation of CBsfi_thread_abort() or CBsfi_thread_queue_abort().

CBsfi_thread_run(CIname, CIfunc, CIuser_data); nokeep; l l l. CIconst gchar* CIname; T{ thread name T} CISfiThreadFunc CIfunc; T{ function to execute in new thread T} CIgpointer CIuser_data; T{ user data to pass into CIfunc T} h'-2m'CIRETURNS: T{ new thread handle or NULL in case of error T}

Create a new thread running CIfunc.

CBsfi_thread_self(); nokeep; l l l. h'-2m'CIRETURNS: T{ thread handle T}

Return the thread handle of the currently running thread.

CBsfi_thread_self_pid(); nokeep; l l l. h'-2m'CIRETURNS: T{ thread id T}

Return the thread specific id. This function is highly system dependant. The thread id may deviate from the overall process id or not. On linux, threads have their own id, allthough since kernel 2.6, they share the same process id.

CBsfi_thread_set_wakeup(CIwakeup_func, CIwakeup_data, CIdestroy); nokeep; l l l. CISfiThreadWakeup CIwakeup_func; T{ wakeup function to be called by CBsfi_thread_wakeup() T} CIgpointer CIwakeup_data; T{ data passed into CBwakeup_func() T} CIGDestroyNotify CIdestroy; T{ destroy handler for CIwakeup_data T}

Set the wakeup function for the current thread. This enables the thread to be woken up through CBsfi_thread_wakeup() even if not sleeping in CBsfi_thread_sleep(). The wakeup function must be thread-safe, so it may be called from any thread, and it should be fast, because the global thread system lock is held during its invokation. Per thread, the wakeup function may be set only once.

CBsfi_thread_sleep(CImax_useconds); nokeep; l l l. CIglong CImax_useconds; T{ maximum amount of micro seconds to sleep (-1 for infinite time) T} h'-2m'CIRETURNS: T{ TRUE while the thread should continue execution T}

Sleep for the amount of time given. This function may get interrupted by wakeup requests from CBsfi_thread_wakeup(), abort requests from CBsfi_thread_queue_abort() or other means. It returns whether the thread is supposed to continue execution after waking up. This function or alternatively CBsfi_thread_aborted() should be called periodically, to react to thread abortion requests and to update internal accounting information.

CBsfi_thread_wakeup(CIthread); nokeep; l l l. CISfiThread* CIthread; T{ thread to wake up T}

Wake up a currently sleeping thread. In practice, this function simply causes the next call to CBsfi_thread_sleep() within CIthread to last for 0 seconds.

CBsfi_time_from_string(CItime_string); nokeep; l l l. CIconst gchar* CItime_string; T{ string containing human readable date and time T} h'-2m'CIRETURNS: T{ parsed time in micro seconds or 0 on error T}

Simple variant of CBsfi_time_from_string_err().

CBsfi_time_from_string_err(CItime_string, CIerror_p); nokeep; l l l. CIconst gchar* CItime_string; T{ string containing human readable date and time T} CIgchar** CIerror_p; T{ location for newly allocated string containing conversion errors T} h'-2m'CIRETURNS: T{ parsed time in micro seconds, may be 0 on error T}

Parse date and time from a string of characters and indicate possible errors. Several attempts are made to reconstruct a valid date and time despite possible errors. However, if all attempts fail, the returned time is 0. The time returned is UTC, refer to CBsfi_time_from_utc() in order to retrieve the local standard time.

CBsfi_time_from_utc(CIustime); nokeep; l l l. CISfiTime CIustime; T{ UTC relative time in micro seconds T} h'-2m'CIRETURNS: T{ local standard time in micro seconds T}

Convert the Coordinated Universal Time (UTC) CIustime into local standard time. This function is MT-safe and may be called from any thread.

CBsfi_time_system(); nokeep; l l l. h'-2m'CIRETURNS: T{ Current system time in micro seconds T}

Get the current system time in micro seconds. Subsequent calls to this function do not necessarily return greater values. In fact, a second call may return a value smaller than the first call under certain system conditions. The time returned is UTC, refer to CBsfi_time_from_utc() in order to retrieve the local standard time. This function is MT-safe and may be called from any thread.

CBsfi_time_to_string(CIustime); nokeep; l l l. CISfiTime CIustime; T{ time in micro seconds T} h'-2m'CIRETURNS: T{ newly allocated string T}

Retrieve the time CIustime in human readable form. The returned time string describes UTC time and thus contains no time zone or UTC offset information.

CBsfi_time_to_utc(CIustime); nokeep; l l l. CISfiTime CIustime; T{ local standard time in micro seconds T} h'-2m'CIRETURNS: T{ UTC relative time in micro seconds T}

Convert the local standard time CIustime into Coordinated Universal Time (UTC). This function is MT-safe and may be called from any thread.

Document Revised: Wed May 25 23:38:16 2005