TEKlib reference manual

Modules and libraries

teklib

OVERVIEW

The majority of TEKlib's functionality is located in shared modules. The link libraries provide only functions that operate on elementary data structures (such as lists, hooks and taglists), and they allow the setup of applications and modules.

LIBRARIES
FUNCTIONS

Taglists

One of the most versatile data structures in TEKlib are arrays of key/value pairs. These pairs are called tags, hence the term tagitem for the resulting data structure, and taglist for an array composed of tagitems. Example: 

struct TTagItem my_taglist[5] =
{
    MY_Points, vertices,
    MY_NumPoints, (TTAG) 3,
    MY_Color, (TTAG) 0xff0000,
    MY_Name, "Red triangle",
    TTAG_DONE
};

The TTAG type has the guaranteed ability to carry pointers on all architectures. This allows, in essence, to transport any kind of data in tagitems. The tti_Tag field can contain user codes or control codes. User codes are identified by their combination with TTAG_USER, for example 

#define MY_Points    (TTAG_USER + 0x10001)
#define MY_NumPoints (TTAG_USER + 0x10002)
#define MY_Color     (TTAG_USER + 0x10003)
#define MY_Name      (TTAG_USER + 0x10004)

A tag not containing TTAG_USER is considered a control tag, which determines how a single item is to be interpreted, or how an array of tagitems should be traversed. The meanings of control tags are:

Once a function is designed to accept a taglist argument, it becomes more flexible for future API changes. By assigning a default value to each tag argument, any number of new taglist arguments can be added to the function, without ever breaking existing code: 

void API_func(TTAGITEM *tags)
{
    TINT numv = (TINT) TGetTag(tags, MY_NumPoints, (TTAG) 3);
    TFLOAT *v = (TFLOAT *) TGetTag(tags, MY_Points, def_vertices);
    TSTRPTR n = (TSTRPTR) TGetTag(tags, MY_Name, "Def. Triangle");
    TUINT rgb = (TUINT) TGetTag(tags, MY_Color, (TTAG) 0xff0000);
    /* ... more tags in the future ... */
}
NOTES
  • As the sizes of TFLOAT and TDOUBLE types are not regulated in TEKlib, they should be transported as pointer references. Aside from TTAG type values and pointers, only integers (up to the size of TUINTPTR) should be placed into the field tti_Value.

Lists

TEKlib lists are doubly-linked, with a stop node, which appears before the first and after the last node of a list.

The forward iterator for this topology looks like this: 

struct TNode *next, *node = list->tlh_Head;
for (; (next = node->tln_Succ); node = next)
{
    /*
     * you can operate on 'node' here, remove it safely,
     * insert past it, as well as 'break' out from and
     * 'continue' the loop.
     */
}

TEKMain()

void TEKMain(struct TTask *task)
FUNCTION

In a freestanding application, TEKlib resolves a platform-specific entrypoint like main() or intercepts the entrypoint provided by the platform's binary loader, performs initializations with reasonable defaults, and then enters TEKMain().

Resources such as argc, argv, return values and other properties are made available to the framework in named atoms. See TEKCreate(), util:TGetArgC(), util:TGetArgV(), util:TSetRetVal() for details.

If you need more control over the startup procedure then you can write your own startup library using TEKCreate().

EXAMPLE

Unless you write a more convenient C++ startup library of your own, the TEKlib application entrypoint for a C++ application would look like this: 

extern "C" void TEKMain(struct TTask *task)
{
    /* ... */
}
SEE ALSO

teklib:TEKCreate(), exec:TGetExecBase()

TEKCreate()

basetask = TEKCreate(tags)
struct TTask*        TTAGITEM*
FUNCTION

This function creates an initial TEKlib context. All further functionality is related to and derived from this handle. If initialization fails, the return value is TNULL. If successful, the initial task handle refers to the process/thread context in which the caller is running. The handle is being destroyed with a call to teklib:TDestroy(), which will clean up and free all resources.

This kind of startup allows for integratation of TEKlib into foreign environments, and you can use it for writing your own startup library.

RESULTS
  • basetask - initial context handle.
INPUTS
  • tags - Pointer to an array of tag items, or TNULL.
    • TExecBase_ArgC, (TUINT) - Submit a main() entrypoint's number of arguments to the framework. If applicable, argc, argv will be made available in a named atom sys.argv. See also util:TGetArgC(). Default: undefined
    • TExecBase_ArgV, (TSTRPTR) - Submit a main() entrypoint's array of arguments to the framework. If applicable, argc, argv will be made available in a named atom sys.argv. See also util:TGetArgV(). Default: undefined
    • TExecBase_RetValP, (TINT *) - Submit a pointer to a possible return value. The pointer will be made available in a named atom sys.returnvalue. The variable being pointed to should be initialized with zero. See also util:TSetRetVal() for setting the return value in an application. Default: undefined
    • TExecBase_ModInit, (struct TInitModule *) - Submit a TNULL-terminated array of internal startup modules to your application. This allows you to link modules to applications statically. Internal modules will be looked up first, i.e. before any of the search strategies for modules from disk apply. Default: TNULL
    • TExecBase_ProgDir, (TSTRPTR) - Override the path to TEKlib's logical PROGDIR: volume, which by default resembles to the directory in which the application resides. Default: the application directory
    • TExecBase_ModDir, (TSTRPTR) - Some platforms support this tag argument for setting a global search path for modules, overriding the hardcoded internal default (e.g. /opt/tek/mod). Local modules (those in PROGDIR:mod) are not affected, as those will always be probed first. Default: platform-specific.
    • TExecBase_SysDir, (TSTRPTR) - Some platforms support this tag argument for setting a global system directory, overriding the hardcoded internal default (e.g. C:\Programs\Common Shared Files\tek), which also resembles to the logical SYS: volume in TEKlib's filesystem namespace. Default: platform-specific
NOTES
  • It is platform-specific whether you are allowed to create more than one instance of TEKlib per application. Most platforms currently supported do, but this would be something unadvisable to depend on.
  • Applications running in the POSIX environment depend on the argv vector to determine their logical program directory. You are advised to pass the tags TExecBase_ArgC and TExecBase_ArgV. If they are unavailable, use TExecBase_ProgDir to supply this information.
  • Not all platforms support this kind of startup, since a fully-fledged TEKlib context cannot be described by the basetask handle alone. For example, if associating thread-specific data requires manipulation of the stack layout, then it is possible that the respective platform can only provide TEKMain().
SEE ALSO

teklib:TEKMain()

TAddHead()

TAddHead(list,         node)
         struct TList* struct TNode *
FUNCTION

Add a node at the head of a doubly linked list.

INPUTS
  • list - Pointer to a list header
  • node - Pointer to a node to be added
SEE ALSO

teklib:TAddTail(), teklib:TInitList()

TAddTail()

TAddTail(list,         node)
         struct TList* struct TNode *
FUNCTION

Add a node at the tail of a doubly linked list.

INPUTS
  • list - Pointer to a list header
  • node - Pointer to a node to be added
SEE ALSO

teklib:TAddHead(), teklib:TInitList()

TRemove()

TRemove(node)
        struct TNode*
FUNCTION

Unlink a node from whatever list it is linked to.

INPUTS
  • node - Pointer to a node to be removed
NOTES
  • Using this function with a node not being part of a list will be fatal.
SEE ALSO

teklib:TRemHead(), teklib:TRemTail(), teklib:TInitList()

TRemHead()

node = TRemHead(list)
struct TNode*   struct TList*
FUNCTION

Unlink and return the first node from a doubly linked list.

RESULTS
  • node - Pointer to the node being unlinked from the list, or TNULL
INPUTS
  • list - Pointer to a list header
SEE ALSO

teklib:TRemTail(), teklib:TRemove(), teklib:TInitList()

TRemTail()

node = TRemTail(list)
struct TNode*   struct TList*
FUNCTION

Unlink and return the last node from a doubly linked list.

RESULTS
  • node - Pointer to the node being unlinked from the list, or TNULL
INPUTS
  • list - Pointer to a list header
SEE ALSO

teklib:TRemHead(), teklib:TRemove(), teklib:TInitList()

TDestroy()

TDestroy(handle)
         struct THandle*
FUNCTION

Destroy a generic handle by calling its destructor. If either handle or handle->thn_DestroyFunc is TNULL, then nothing will happen.

INPUTS
  • handle - Pointer to a generic object handle
NOTES
  • No memory whatsoever will be freed by this function
SEE ALSO

teklib:TDestroyList(), teklib:TFindHandle()

TInitList()

TInitList(list)
          struct TList*
FUNCTION

Prepare a list header structure. After initialization the list will be empty and ready for use.

INPUTS
  • list - Pointer to a list structure
SEE ALSO

teklib:TAddHead(), teklib:TAddTail(), teklib:TRemove(), teklib:TRemHead(), teklib:TRemTail()

TInsert()

TInsert(list,         node,         prednode)
        struct TList* struct TNode* struct TNode*
FUNCTION

Insert a node into a list after prednode. If prednode is TNULL, then this function is equivalent to teklib:TAddTail().

INPUTS
  • list - Pointer to a list to insert to
  • node - Pointer to a node to insert
  • prednode - Pointer to a node in the list after which to insert
SEE ALSO

teklib:TRemove(), teklib:TAddTail(), teklib:TAddHead()

TNodeUp()

TNodeUp(node)
        struct TNode*
FUNCTION

Move a node one position towards the head of the list it is linked to. In other words, if the node is not already at the head of the list, swap its position with its predecessor.

INPUTS
  • node - Pointer to a node
NOTES
  • Using this function with a node not being part of a list will be fatal.
SEE ALSO

teklib:TRemove(), teklib:TAddTail(), teklib:TAddHead()

TGetTag()

value = TGetTag(taglist,  tag,  defvalue)
TTAG            TTAGITEM* TUINT TTAG
FUNCTION

Parse a list of tag items and return the value associated with the first matching tag identifier. If the specified tag is not contained in the list, then the default value is returned.

taglists are arrays of tagitems. Each tagitem is composed from a key/value pair. Many TEKlib functions accept a taglist argument for making them more robust for future extensions.

The tag field can contain control tags and user tags. User tags must be combined with the TTAG_USER flag. Control tags are:

RESULTS
  • value - Value associated with the tag in the taglist, otherwise the default value
INPUTS
  • taglist - Pointer to an array of tag items
  • tag - Tag to be queried
  • defvalue - Default value
NOTES
  • The TTAG type is capable of carrying pointers. This allows, in essence, to transport any kind of data in tag items, even on 64bit architectures. An unfortunate side-effect is that assigning a value to tti_Value may require a typecast to TTAG for getting rid of complaints from the compiler.
SEE ALSO

teklib:TForEachTag()

TDestroyList()

TDestroyList(list)
             struct TList*
FUNCTION

Unlinks all nodes from a list (in first-to-last order) and calls teklib:TDestroy() on each individual entry. Note that this function expects all nodes (their heading structure) to be of the generic handle datatype, otherwise the consequences would be nasty.

Nothing will happen if list is TNULL or if the list is empty.

INPUTS
  • list - list to clear
SEE ALSO

teklib:TDestroy(), teklib:TFindHandle()

TNewInstance()

inst = TNewInstance(mod,  possize, negsize)
TAPTR               TAPTR TUINT    TUINT
FUNCTION

This function creates a module instance copy. The module base can be duplicated alongside with a preceding function table.

possize and {{negsize]] determine the size of the module base and the size of a preceding function table, respectively. Usually these arguments will be set to mod->tmd_PosSize and mod->tmd_NegSize, which will create an exact copy a of the module. However, it is also possible to extend the module base and function table.

A pointer to the duplicated module base is returned. teklib:TNewInstance() is typically used in a module's instance open function.

RESULTS
  • inst - A copy of the module base and function table, or TNULL
INPUTS
  • mod - Pointer to module base
  • possize - Positive size of the module, in bytes
  • negsize - Negative size of the module, in bytes

The negative size is the size of the function table that normally precedes the module base.

SEE ALSO

teklib:TFreeInstance(), teklib:TInitVectors()

TFreeInstance()

TFreeInstance(inst)
              struct TModule *
FUNCTION

This function frees a module instance. It respects the size of the module base as well as its negative size, that is, the size of the function table preceding it.

This function is normally used in a module's instance close function.

INPUTS
  • inst - Pointer to a module instance
SEE ALSO

teklib:TNewInstance(), teklib:TInitVectors()

TInitVectors()

TInitVectors(mod,  vectors, numv)
             TAPTR TAPTR*   TUINT
FUNCTION

This function takes a pointer to a table of function pointers and places them in front of a module base (in reverse order - a simple memory copy would be inappropriate here). This function is normally used in a module's init function.

INPUTS
  • mod - Module base pointer
  • vectors - Pointer to a table of function pointers
  • numv - Number of entries
SEE ALSO

teklib:TNewInstance(), teklib:TFreeInstance()

TFindHandle()

handle = TFindHandle(list,  name)
TAPTR                TLIST* TSTRPTR
FUNCTION

Find the first occurance of a named handle in a list. The name is expected in each node's handle->thn_Data field. Only lists containing only nodes with a conforming object handle may be searched with this function. Name comparison is case-sensitive.

RESULTS
  • handle - Ptr to named handle, or TNULL if not found in the list
INPUTS
  • list - Pointer to a list structure
  • name - Name of a handle to look up
SEE ALSO

teklib:TDestroy(), teklib:TDestroyList()

TForEachTag()

(TODO) 

complete = TForEachTag(taglist,  function,       userdata)
TBOOL                  TTAGITEM* TTAGFOREACHFUNC TAPTR
FUNCTION

This function traverses a list of tagitems, and for each item it calls a user-supplied function according of the following type: 

TCALLBACK TBOOL function(TAPTR userdata, TTAGITEM *item)

The userdata argument is passed to the callback function and otherwise remains invisible to TForEachTag(). The callback function has to return TTRUE to continue traversal, or TFALSE to abort.

RESULTS
  • complete - TTRUE if the list was traversed completely

When all items were traversed without interruption, then the return value from TForEachTag() will be TTRUE. TFALSE will be returned otherwise.

INPUTS
  • taglist - an array of tagitems to traverse
  • function - callback function to call for each item traversed
  • userdata - user data argument passed to the callback function
SEE ALSO

teklib:TGetTag()

TInitHook()

TInitHook(hook,         func,     data)
          struct THook* THOOKFUNC TAPTR
FUNCTION

Initialize a hook structure with a function and user data.

INPUTS
  • hook - Hook structure to be initialized
  • func - C calling conventions function pointer
  • data - User data to be associated with the hook
PURPOSE

TEKlib hooks allow the transparent transition from e.g. register- to stack-based calling conventions. hook->thk_Entry is invoked by teklib:TCallHookPkt() and follows TEKlib's per-platform calling conventions (as declared with THOOKENTRY). It however may point to a stub function calling the actual user function in hook->thk_SubEntry, which in turn may be entirely specific for the used language or compiler.

SEE ALSO

teklib:TCallHookPkt()

TCallHookPkt()

result = TCallHookPkt(hook,         object, message)
TTAG                  struct THook* TAPTR   TTAG
FUNCTION

Invokes a hook function, passing it an object and message.

RESULTS
  • result - specific to the invoked hook function
INPUTS
  • object - An object to be processed by the hook
  • message - An action code
NOTES
  • TEKlib hooks are commonly used for destructors, hashing functions, module initialization, task creation, tag iterators etc. Therefore, TEKlib comes with a range of pre-defined hook message types, such as TMSG_DESTROY, TMSG_CALCHASH32, TMSG_OPENMODULE, TMSG_INITTASK, TMSG_FOREACHTAG, to name only examples. User-defined messages start at TMSG_USER, but the user is free to bypass TEKlib's message codes altogether by seperating system hooks from his own.

SEE ALSO: teklib:TInitHook()

TAddTime()

TAddTime(a,     b)
         TTIME* TTIME*
FUNCTION

Add time b to time a, leaving the result in time a.

INPUTS
  • a - Pointer to a time structure to add to
  • b - Pointer to a time structure to be added
SEE ALSO

teklib:TSubTime(), teklib:TCmpTime(), teklib:TAddDate(), teklib:CreateTime()

TSubTime()

TSubTime(a,     b)
         TTIME* TTIME*
FUNCTION

Subtract time b from time a, leaving the result in time a.

INPUTS
  • a - Pointer to a time structure to subtract from
  • b - Pointer to a time structure to be subtracted
SEE ALSO

teklib:TAddTime(), teklib:TCmpTime(), teklib:TSubDate()

TCmpTime()

res = TCmpTime(a,     b)
TINT           TTIME* TTIME*
FUNCTION

Compare time a with time b.

RESULTS
  • res - result of comparison:
    • 1 - if time a refers to a later point in time than time b
    • -1 - if time a refers to a earlier point in time than time b
    • 0 - if time a is equal to time b.
INPUTS
  • a - Pointer to a time structure, first operand
  • b - Pointer to a time structure, second operand
SEE ALSO

teklib:TAddTime(), teklib:TSubTime(), teklib:TDiffDate()

TAddDate()

TAddDate(date,  ndays, time)
         TDATE* TINT   TTIME*
FUNCTION

Add a number of days and optionally a time to a date.

INPUTS
  • tdate - Date structure
  • ndays - Number of days to add. Can be 0.
  • time - Pointer to a TTIME structure. Can be TNULL.
NOTES
  • Do not add negative values in the time structure, use the function teklib:TSubDate() instead.
SEE ALSO

teklib:TSubDate(), teklib:TDiffDate()

TSubDate()

TSubDate(date,  ndays, time)
         TDATE* TINT   TTIME*
FUNCTION

Subtract a number of days and optionally a time from a date.

INPUTS
  • tdate - Date structure
  • ndays - Number of days to subtract. Can be 0.
  • time - Pointer to a TTIME structure. Can be TNULL.
NOTES
  • Do not subtract negative values in the time structure, use the function TAddDate() instead.
SEE ALSO

teklib:TAddDate(), teklib:TDiffDate()

TDiffDate()

days = TDiffDate(date1, date2, timep)
TINT             TDATE* TDATE* TTIME*
FUNCTION

This function returns the difference in number of days between date1 and date2. The difference in time will be inserted, optionally, into the time structure being pointed to by timep.

Note that if date1 is before date2, the resulting number of days will be negative, but the time difference (in seconds and microseconds) will always be inserted as positive numbers.

RESULTS
  • days - Number of days difference
INPUTS
  • date1, date2 - Pointers to TDATE structures
  • timep - Pointer to a TTIME structure receiving a time difference, or TNULL
SEE ALSO

teklib:TAddDate(), teklib:TSubDate()

TCreateTime()

success = TCreateTime(timep, d,   s,   us)
TBOOL                 TTIME* TINT TINT TINT
FUNCTION

This function composes a TEKlib time from days, seconds and microseconds.

RESULTS
  • success - Boolean
INPUTS
  • timep - Pointer to a TIME structure receiving the result
  • d - Number of days
  • s - Number of seconds
  • us - Number of microseconds
SEE ALSO

teklib:ExtractTime(), teklib:AddTime()

TExtractTime()

success = TExtractTime(timep, dp,   sp,   usp)
TBOOL                  TTIME* TINT* TINT* TINT*
FUNCTION

This function extracts from a TEKlib time the number of days, seconds and microseconds.

RESULTS
  • success - Boolean
INPUTS
  • timep - Pointer to a TIME structure
  • dp - Pointer to a number of days, or TNULL
  • sp - Pointer to a number of seconds, or TNULL
  • usp - Pointer to a number of microseconds, or TNULL
SEE ALSO

teklib:TCreateTime()

TInitInterface()

TInitInterface(interface,         module,         name,   version)
               struct TInterface* struct TModule* TSTRPTR TUINT16
FUNCTION

This function initializes an interface structure.

INPUTS
  • interface - Pointer to an TInterface structure
  • module - Pointer to a TModule structure to which the interface belongs
  • name - Name of the interface
  • version - Version of the interface

TGetNextEntry()

entry = TGetNextEntry(handle)
TAPTR                 struct THandle*
FUNCTION

Get the next entry from a handle by dispatching TMSG_GETNEXTENTRY.

RESULTS
  • entry - Next entry, or TNULL if no next entry available
INPUTS
  • handle - Pointer to a generic object handle

string

FUNCTIONS

TStrLen()

len = TStrLen(string)
TSIZE         TSTRPTR

TStrCpy()

dest = TStrCpy(dest,   source)
TSTRPTR        TSTRPTR TSTRPTR

TStrNCpy()

dest = TStrNCpy(dest,   source, maxlen)
TSTRPTR         TSTRPTR TSTRPTR TSIZE
NOTES
  • If the length of source is less than maxlen, this function does not pad the remainder of dest with null bytes. This is in contrast to the strncpy() standard library function.

TStrCat()

dest = TStrCat(dest,   source)
TSTRPTR        TSTRPTR TSTRPTR

TStrNCat()

dest = TStrNCat(dest,   source, maxlen)
TSTRPTR         TSTRPTR TSTRPTR TSIZE

TStrCmp()

res = TStrCmp(first,  second)
TINT          TSTRPTR TSTRPTR
NOTES
  • Either or both strings may be TNULL. A TNULL string is 'less than' a non-TNULL string.

TStrNCmp()

res = TStrNCmp(first,  second, maxlen)
TINT           TSTRPTR TSTRPTR TSIZE
NOTES

See annotations for string:TStrCmp()

TStrCaseCmp()

res = TStrCaseCmp(first,  second)
TINT              TSTRPTR TSTRPTR
NOTES

See annotations for string:TStrCmp()

TStrNCaseCmp()

res = TStrNCaseCmp(first,  second, maxlen)
TINT               TSTRPTR TSTRPTR TSIZE
NOTES

See annotations for string:TStrCmp()

TStrStr()

found = TStrStr(haystack, needle)
TSTRPTR         TSTRPTR   TSTRPTR

TStrChr()

found = TStrChr(string, character)
TSTRPTR         TSTRPTR TINT

TStrRChr()

found = TStrRChr(string, character)
TSTRPTR          TSTRPTR TINT

TStrToI()

numchars = TStrToI(string, valp)
TINT               TSTRPTR TINT*
FUNCTION

This function converts a string to a 32bit signed integer.

RESULTS
  • numchars - Number of characters converted, or:
    • -1 - Conversion error, invalid characters
    • -2 - Overflow or underflow occured
INPUTS
  • string - Pointer to a string to be converted
  • valp - Pointer to a value to be filled in by this function

exec

FUNCTIONS

TGetExecBase()

TExecBase = TGetExecBase(object)
struct TExecBase*        TAPTR
FUNCTION

This macro retrieves a pointer to the Exec module base from an Exec object. Objects provided by the Exec module are tasks, ports, memory managers, atoms, locks, and modules themselves.

RESULTS
INPUTS
BACKGROUND

The TEKlib framework is free of global data and carefully designed to be fully reentrant. It is the programmer's choice to put module base pointers into global variables.

Initially, an application is entered with a task handle only. It is usually required to query the Exec module base pointer from that handle before anything useful can be done. The module base pointer can then be stored in a global variable, if desired. A typical application startup may look like this: 

struct TExecBase *TExecBase;
struct TUtilBase *TUtilBase;

void TEKMain(struct TTask *task)
{
    TExecBase = TGetExecBase(task);
    TUtilBase = TOpenModule("util", ...
    ...
}
SEE ALSO

exec:TGetHALBase()

TDoExec()

success = TDoExec(cmd,  tags)
TBOOL             TUINT TTAGITEM*
FUNCTION

Runs or initializes an Exec context. Depending on the cmd argument, TDoExec() performs missing initializations in the current task or services module opens, task creation and atom lookups. It is expected that the thread context in which this function is called was previously created using exec:TCreateSysTask().

RESULTS
INPUTS
NOTES

This function is of any use only for implementors of startup libraries.

SEE ALSO

exec:TCreateSysTask(), exec:TCreateTask()

TCreateSysTask()

task = TCreateSysTask(func,     tags)
struct TTask*         TTASKFUNC TTAGITEM*
FUNCTION

This function creates an Exec-internal task. If func is TNULL, a TEKlib task is placed in the caller's thread context, otherwise a new thread of execution is started at the given function.

This function is used to setup an initial TEKlib context (or an Exec task) before TEKlib is fully initialized. This function is not entirely safe in regular applications and the only sanctioned use is in startup libraries.

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TCreateTask(), exec:TDoExec(), exec:TGetTaskData()

TGetHALBase()

THALBase = TGetHALBase()
struct THALBase *
FUNCTION

Returns a pointer to the HAL module base. Access to the HAL layer is often required in device driver implementations.

RESULTS
SEE ALSO

exec:TGetExecBase()

TOpenModule()

modbase = TOpenModule(name,   version, tags)
struct TModule*       TSTRPTR TUINT16  TTAGITEM*
FUNCTION

Opens a module or a module instance. When the module's version is greater or equal the requested version and when the module can be loaded and initialized successfully, a pointer to the module base will be returned to the caller.

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TCloseModule(), exec:TGetExecBase()

TCloseModule()

TCloseModule(modbase)
             struct TModule *
FUNCTION

Closes a module or a module instance. When applied to the last reference or instance open then the module will be deinitalized, unloaded and freed.

INPUTS
SEE ALSO

exec:TOpenModule()

TCopyMem()

TCopyMem(source, dest, numbytes)
         TAPTR   TAPTR TSIZE
FUNCTION

Copy the given number of bytes from a source to a destination address in memory.

INPUTS
NOTES
  • Do not rely on overlapping copies to work with this function.
SEE ALSO

exec:TFillMem()

TFillMem()

TFillMem(start, numbytes, fillval)
         TAPTR  TSIZE     TUINT8
FUNCTION

Fill a range of memory with a 8bit value.

INPUTS
SEE ALSO

TCopyMem()

TCreateMemManager()

memmanager = TCreateMemManager(resource, type, tags)
struct TMemManager*            TAPTR     TUINT TTAGITEM*
FUNCTION

Create a memory manager. A memory manager can be passed to exec:TAlloc() for allocating memory with special functionality attached to it, such as automatic cleanup, tighter packing, thread-safety, etc. Memory managers can be stacked on top of each other. A memory manager is freed with a call to teklib:TDestroy().

TNULL is always a valid memory manager. A TNULL memory manager will cause exec:TAlloc() to use the system's general purpose allocator. Only a TNULL memory manager is intrinsically safe to use in a multitasking environment; other allocators must implement cross-task protection explicitely. See the TMMT_TaskSafe flag for details.

RESULTS
INPUTS
SEE ALSO

teklib:TDestroy(), exec:TAlloc(), exec:TAllocMsg(), exec:TGetMemManager(), exec:TCreatePool(), exec:TGetTaskMemManager()

TAlloc()

mem = TAlloc(memmanager,         size)
TAPTR        struct TMemManager* TSIZE
FUNCTION

This function allocates a block of memory from a memory manager. A pointer to the allocated block of memory is returned, or TNULL if the request cannot be satisfied. A TNULL memory manager is valid and directs requests to the system's general purpose allocator.

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TFree(), exec:TRealloc(), exec:TAlloc0(), exec:TCreateMemManager(), exec:TAllocMsg(), exec:TGetSize(), exec:TGetMemManager()

TAlloc0()

mem = TAlloc0(memmanager,         size)
TAPTR         struct TMemManager* TSIZE
FUNCTION

Allocate a blank block of memory from a memory manager. This function is equivalent to TAlloc() except for that the returned memory is guaranteed to be filled with all bytes set to zero.

RESULTS
INPUTS
SEE ALSO

exec:TAlloc(), exec:TFree()

TQueryInterface()

interface = TQueryInterface(module,         name,   version, tags)
struct TInterface*          struct TModule* TSTRPTR TUINT16  TTAGITEM*
FUNCTION

This function queries a module for an interface of the given name and version. Returns TNULL if no interface could be found or created. The resulting interface structure must be freed with a matching call to teklib:TDestroy() prior to closing the module from which it was obtained.

RESULTS
  • interface - Pointer to an interface structure
INPUTS
  • module - Module to obtain the interface from
  • name - Name of the interface
  • version - Minimum version of the interface
  • tags - Additional tags, passed to the module dispatch hook in an object of the type struct TInterfaceQuery via the field object->tifq_Tags.

SEE ALSO: exec:TOpenModule(), teklib:TDestroy()

TFree()

TFree(mem)
      TAPTR
FUNCTION

Return a block of memory to the memory manager it was allocated from.

INPUTS
NOTES
SEE ALSO

exec:TAlloc(), exec:TAllocMsg(), exec:TGetSize(), exec:TGetMemManager(), exec:TRealloc(), exec:TCreateMemManager()

TRealloc()

newmem = TRealloc(oldmem, newsize)
TAPTR             TAPTR   TSIZE
FUNCTION

Resize a block of memory that was allocated from a memory manager. If newsize is 0, the block of memory will be freed and the result will be TNULL.

This function departs from the usual realloc semantics in that it cannot be used to allocate a fresh block of memory. If a TNULL pointer is passed as the oldmem argument, this function returns TNULL.

If a reallocation fails and the return value is TNULL, the old block of memory still belongs to the user.

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TAlloc(), exec:TFree(), exec:TGetSize(), exec:TCreateMemManager()

TGetMemManager()

memmanager = TGetMemManager(mem)
struct TMemManager*         TAPTR
FUNCTION

Returns a pointer to the memory manager an allocation was made from.

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TGetSize(), exec:TAlloc(), exec:TCreateMemManager()

TGetSize()

size = TGetSize(mem)
TSIZE           TAPTR
FUNCTION

This function gets the size of a block of memory (in bytes) that was allocated from a memory manager.

RESULTS
INPUTS
SEE ALSO

exec:TGetMemManager(), exec:TAlloc()

TCreateLock()

lock = TCreateLock(tags)
struct TLock*      TTAGITEM*
FUNCTION

Create a locking object. A lock is a mechanism to protect resources from simultaneous accesses from multiple tasks. Only one accessor can hold the same lock at a given time.

A lock is destroyed with a call to teklib:TDestroy().

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TLock(), exec:TUnlock(), teklib:TDestroy()

TLock()

TLock(lock)
      struct TLock*
FUNCTION

Gain exclusive access to a lock. If another task is currenty holding the lock, the caller will block until the lock is free. If no other task holds the lock, then this function returns immediately with exclusive access.

This function is recursive (or 'nesting'), i.e. it may be called subsequently when the lock is already held by the current owner. In that case an internal counter is increased and this function returns immediately with a lock on the shared resource.

Each call per task must be paired with exactly one matching call to exec:TUnlock(), which will decrease the nesting counter. When the counter reaches zero, the control is handed over to the next waiter or, if there are no waiters, the lock is being released.

INPUTS
SEE ALSO

exec:TUnlock(), exec:TCreateLock()

TUnlock()

TUnlock(lock)
        struct TLock*
FUNCTION

Release access to a lock which was previously obtained with a call to exec:TLock(). The next task currently suspended waiting for the lock will gain exclusive access to the resource and resume.

INPUTS
SEE ALSO

exec:TLock(), exec:TCreateLock()

TAllocSignal()

signals = TAllocSignal(prefsignals)
TUINT                  TUINT
FUNCTION

Allocate a signal (or a set of preferred signals) from the current task. If prefsignals is 0 then this function will try to reserve any single free signal. Otherwise, this function tries to reserve the exact set specified.

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TFreeSignal(), exec:TSignal(), exec:TSetSignal(), exec:TWait()

TFreeSignal()

TFreeSignal(signals)
            TUINT
FUNCTION

Free a single or a set of signals and return them to a task's signal pool.

INPUTS
SEE ALSO

exec:TAllocSignal(), exec:TWait()

TSignal()

TSignal(task,         signals)
        struct TTask* TUINT
FUNCTION

Submit signals to a task. The signal(s) will show up in the signalled task. When the task was suspended waiting for any of the specified signals, it will resume its operation.

INPUTS
SEE ALSO

exec:TSetSignal(), exec:TWait(), exec:TAllocSignal()

TSetSignal()

oldsignals = TSetSignal(newsignals, sigmask)
TUINT                   TUINT       TUINT
FUNCTION

Set the current task's signal state to the signal bits in newsignals, masked through the bits in the sigmask argument, and return the old state of the tasks's signals to the caller.

INPUTS
EXAMPLES 
/* get the current state of all signals, but do not modify them */
signals = TSetSignal(0, 0);

/* clear the TTASK_SIG_ABORT signal */
TSetSignal(0, TTASK_SIG_ABORT);
SEE ALSO

exec:TSignal(), exec:TWait(), exec:TAllocSignal()

TWait()

signals = TWait(sigmask)
TUINT           TUINT
FUNCTION

Suspend the current task to wait for one or more of the signals specified in sigmask to arrive. Those bits will be cleared from the task's signal state and returned to the caller when the function returns. If sigmask is 0, this function will immediately return 0.

RESULTS
INPUTS
SEE ALSO

exec:TWaitPort(), exec:TSignal(), exec:TSetSignal(), exec:TAllocSignal(), exec:TWaitTime()

TCreatePort()

port = TCreatePort(tags)
struct TMsgPort*   TTAGITEM*
FUNCTION

Create a message port owned by the current task.

A message port is an access point for messages between tasks. It can be synchronized on using exec:TWaitPort(). Use exec:TGetPortSignal() to retrieve a port's underlying signal. Using this signal, one or more message ports can be synchronized on using exec:TWait().

A message port is destroyed with a call to teklib:TDestroy().

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TWaitPort(), exec:TWait(), exec:TPutMsg(), exec:TGetMsg(), teklib:TDestroy(), exec:TGetPortSignal(), exec:TGetUserPort()

TPutMsg()

TPutMsg(msgport,         replyport,       msg)
        struct TMsgPort* struct TMsgPort* TAPTR
FUNCTION

Put a message to a message port. If a replyport is specified, the message will be sent two-way, and there will be a reply expected at this port. If replyport is TNULL, the message will be sent one-way and does not return to the sender.

INPUTS
SEE ALSO

exec:TGetMsg(), exec:TAckMsg(), exec:TReplyMsg(), exec:TDropMsg(), exec:TSendMsg(), exec:TAllocMsg()

TGetMsg()

msg = TGetMsg(msgport)
TAPTR         struct TMsgPort*
FUNCTION

Unlink the next pending message from a port's message queue and return it to the caller. This function does not block; if the message queue is empty, this function returns immediately with TNULL.

RESULTS
INPUTS
SEE ALSO

exec:TPutMsg(), exec:TAckMsg(), exec:TReplyMsg(), exec:TDropMsg(), exec:TAllocMsg()

TAckMsg()

TAckMsg(msg)
        TAPTR
FUNCTION

Acknowledge a two-way message to its sender, i.e. return it to the replyport that was specified by the sender when the message was sent.

It is safe to apply this function to one-way messages as well; if the message was sent without the expectation of a reply or acknowledgement, it will silently be freed by returning the memory to its memory manager.

When a message is returned with this function, the sender must not rely on modifications made inside the message body. If a changed message is to be returned, then exec:TReplyMsg() should be used instead.

INPUTS
NOTES
SEE ALSO

exec:TReplyMsg(), exec:TDropMsg(), exec:TPutMsg(), exec:TAllocMsg()

TReplyMsg()

TReplyMsg(msg)
          TAPTR
FUNCTION

Reply a two-way message to its sender, i.e. return it to the replyport that was specified by the sender when the message was sent.

It is safe to apply this function to one-way messages as well; if the message was sent without the expectation of a reply or acknowledgement, it will silently be freed by returning the memory to its memory manager.

Use this function for transferring a modified message body back to its sender. If the message was not modified and it is only required to inform the sender that it has been processed, then exec:TAckMsg() should be used instead.

INPUTS
NOTES
SEE ALSO

exec:TAckMsg(), exec:TDropMsg(), exec:TPutMsg(), exec:TAllocMsg()

TDropMsg()

TDropMsg(msg)
         TAPTR
FUNCTION

Abandon a two-way message, i.e. return it to its replyport with the internal message status set to TMSG_STATUS_FAILED. This function is not guaranteed to return any modifications made inside the message body, it will only indicate failure.

It is safe to apply this function to one-way messages as well; if the message was sent without the expectation of a reply or acknowledgement, it will silently be freed by returning the memory to its memory manager.

In local address space this function is particularly useful for indicating failure to the caller of exec:TSendMsg().

INPUTS
SEE ALSO

exec:TSendMsg(), exec:TAckMsg(), exec:TReplyMsg(), exec:TPutMsg(), exec:TAllocMsg()

TSendMsg()

status = TSendMsg(port,            msg)
TUINT             struct TMsgPort* TAPTR
FUNCTION

This function sends a message two-way, synchronized, waiting for a reply or an acknowledgement before it returns to the caller.

The return value will be set to TMSG_STATUS_FAILED if the message has been dropped, or, depending on the return method, TMSG_STATUS_REPLIED or TMSG_STATUS_ACKD if it returned successfully.

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TPutMsg(), exec:TAckMsg(), exec:TReplyMsg(), exec:TDropMsg(), exec:TAllocMsg(), exec:TGetSyncPort()

TWaitPort()

msg = TWaitPort(port)
TAPTR           struct TMsgPort*
FUNCTION

Suspend the current task to wait for a message to arrive at the given message port. When a message is already present then this function returns immediately. A pointer to the next pending message is returned to the caller, but it is not removed from the queue. Use TGetMsg() to unlink the next message from a port.

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TCreatePort(), exec:TWait(), exec:TGetPortSignal(), exec:TGetMsg()

TGetPortSignal()

signal = TGetPortSignal(port)
TUINT                   struct TMsgPort*
FUNCTION

This function retrieves a message port's underlying signal. The typical use of that signal is to use exec:TWait() to combine waiting for messages from multiple ports.

RESULTS
INPUTS
SEE ALSO

exec:TCreatePort(), exec:TWait(), exec:TWaitPort()

TGetUserPort()

userport = TGetUserPort(task)
struct TMsgPort*        struct TTask*
FUNCTION

Get a pointer to a task's primary, asynchronous message port, which is reserved for the user. If the task argument is TNULL, the caller's own task will be queried.

Each task is supplied with an user port upon creation. More message ports can be created using exec:TCreatePort() during a task's lifetime.

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TGetSyncPort(), exec:TCreatePort(), exec:TGetPortSignal()

TGetSyncPort()

syncport = TGetSyncPort(task)
struct TMsgPort*        struct TTask*
FUNCTION

Get a pointer to a task's inbuilt syncport. If task is TNULL, the caller's own task will be addressed.

The syncport is reserved for synchronized message replies. It can be employed by the user if its usage remains strictly limited to that purpose.

For instance, it is not allowed to send messages using exec:TPutMsg() expecting a reply at a syncport. This would break Exec functions that might use the syncport (or the syncport's signal) internally. For asynchronous message communication use the task's user port, or create a new port using exec:TCreatePort().

RESULTS
INPUTS
SEE ALSO

exec:TGetUserPort(), exec:TCreatePort(), exec:TGetPortSignal(),

TCreateTask()

task = TCreateTask(hook,         taglist)
struct TTask*      struct THook* TTAGITEM*
FUNCTION

Creates a task, launches a new thread of execution and invokes the supplied hook with the message TMSG_INITTASK in the newly created context. A return value of TFALSE from the hook function causes this function to abandon task creation and to return TNULL. If the return value is TTRUE, TCreateTask() returns the newly created task handle to the caller, and invokes the hook again, this time with the message TMSG_RUNTASK.

The task handle is destroyed with a call to teklib:TDestroy(). This will synchronize on the task's completion and free its resources. TEKlib tasks must always leave gently through their function exit, and all task must be synchronized on properly, or the TEKlib framework panics at exit.

RESULTS
INPUTS
SEE ALSO

teklib:TDestroy(), exec:TFindTask(), exec:TGetTaskData(), exec:TGetUserPort(), exec:TCreateSysTask()

TFindTask()

task = TFindTask(name)
struct TTask*    TSTRPTR
FUNCTION

Find a named task in the system. If name is TNULL then this function will return a pointer to the caller's own task.

RESULTS
INPUTS
SEE ALSO

exec:TCreateTask()

TGetTaskData()

userdata = TGetTaskData(task)
TAPTR                   struct TTask*
FUNCTION

Get a pointer to a task's user data. A user data pointer can be supplied upon task creation using the TTask_UserData tag, and be set or overwritten using exec:TSetTaskData() during a task's lifetime.

RESULTS
INPUTS
SEE ALSO

exec:TSetTaskData(), exec:TCreateTask()

TSetTaskData()

olddata = TSetTaskData(task, userdata)
TAPTR                  TAPTR TAPTR
FUNCTION

Set a task's user data pointer and return the previous user data pointer to the caller.

A user data pointer can be supplied upon task creation using the TTask_UserData tag and queried with exec:TGetTaskData() during a task's lifetime.

RESULTS
INPUTS
SEE ALSO

exec:TGetTaskData(), exec:TCreateTask()

TGetTaskMemManager()

memmanager = TGetTaskMemManager(task)
struct TMemManager*             struct TTask*
FUNCTION

Get a pointer to a task's inbuilt memory manager. Allocations made from this memory manager are automatically freed when the task exits.

RESULTS
INPUTS
SEE ALSO

exec:TAlloc(), exec:TCreateMemManager()

TAllocMsg()

msg = TAllocMsg(size)
TAPTR           TSIZE
FUNCTION

Allocate memory for a message. Message allocations behave largely like regular allocations, but they originate from their own clsss of memory manager. Use exec:TFree() to return a message to its memory manager. exec:TGetSize() and exec:TGetMemManager() are valid also.

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TAllocMsg0(), exec:TAlloc(), exec:TFree(), exec:TPutMsg(), exec:TCreateMemManager()

TAllocMsg0()

msg = TAllocMsg0(size)
TAPTR            TSIZE
FUNCTION

Allocate memory for a message, blank. This function is equivalent to exec:TAllocMsg(), except for that the message returned is guaranteed to be filled with all bytes set to zero.

RESULTS
INPUTS
SEE ALSO

exec:TAllocMsg()

TLockAtom()

atom = TLockAtom(data, mode)
struct TAtom*    TATPR TUINT
FUNCTION

Depending on the mode argument, this function creates, obtains or destroys a named atom. Atoms are an extension to locks, allowing multiple accessors to create, locate and access resources by name. Also, atoms allow shared locking and locking attempts.

Atoms are recursive. This means the same task holding a lock on an atom is allowed to claim it subsequently, and this function returns with a nesting lock immediately. All locks per task must be paired with exactly one matching unlock operation.

Once locked by the caller, a data field can be associcated with an atom using exec:TSetAtomData() and retrieved with exec:TGetAtomData().

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TUnlockAtom(), exec:TSetAtomData(), exec:TGetAtomData(), exec:TCreateLock()

TUnlockAtom()

TUnlockAtom(atom,         mode)
            struct TAtom* TUINT
FUNCTION

Release access to an atom that has been locked with exec:TLockAtom().

INPUTS
SEE ALSO

exec:TLockAtom()

TGetAtomData()

data = TGetAtomData(atom)
TTAG                struct TAtom*
FUNCTION

Query an atom's user data tag. The atom should be in locked state and currently being owned by the caller.

RESULTS
INPUTS
SEE ALSO

exec:TSetAtomData(), exec:TLockAtom()

TSetAtomData()

olddata = TSetAtomData(atom,         data)
TTAG                   struct TAtom* TTAG
FUNCTION

Associate a user data tag with an atom. The atom should be in exclusively locked state and currently being owned by the caller.

RESULTS
INPUTS
SEE ALSO

exec:TGetAtomData(), exec:TLockAtom()

TCreatePool()

pool = TCreatePool(tags)
struct TMemPool*   TTAGITEM*
FUNCTION

Create a memory pool. A pool is an allocator that groups small allocations into larger ones. All pending allocations made from a pool will be returned to the pool's underlying memory manager once the pool is being destroyed with a call to teklib:TDestroy(). Pools grow and shrink on demand. Two parameters constitute their behavior:

  • Pudsize is the size of a 'puddle', i.e. a regular chunk of memory that will be allocated from an underlying memory manager when a request cannot be satisfied from the current set of puddles. Many small allocations can fit into a puddle.
  • Thressize is the maximum size of allocations that go into regular puddles. Allocations larger than that will go into puddles of their own. Thressize must be less or equal pudsize.

Both pudsize and thressize can be supplied in taglist arguments and remain constant during a pool's lifetime. By default, though, TEKlib pools try to determine appropriate settings for pudsize and thressize during a pool's lifetime and adapt these parameters dynamically.

Pools can be useful for sections of code that mainly deal with many objects of relatively constant sizes. Allocations in a pool are more tightly packed and on smaller boundaries than general-purpose allocations.

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TAllocPool(), exec:TFreePool(), exec:TReallocPool(), teklib:TDestroy(), exec:TCreateMemManager()

TAllocPool()

mem = TAllocPool(pool,            size)
TAPTR            struct TMemPool* TSIZE
FUNCTION

This function allocates a block of memory from a pool. A Pointer to the allocated block of memory is returned, or TNULL if the request cannot be satisfied.

RESULTS
INPUTS
SEE ALSO

exec:TFreePool(), exec:TReallocPool(), exec:TCreatePool()

TFreePool()

TFreePool(pool,            mem,  size)
          struct TMemPool* TUINT TSIZE
FUNCTION

Return a block of memory to the pool from which it was allocated.

INPUTS
SEE ALSO

exec:TAllocPool(), exec:TReallocPool(), exec:TCreatePool()

TReallocPool()

newmem = TReallocPool(pool,            oldmem, oldsize, newsize)
TAPTR                 struct TMemPool* TAPTR   TUINT    TSIZE
FUNCTION

Resize a block of memory that has been allocated from a pool. If newsize is 0 then the allocation will be freed, and the result will be TNULL. If oldmem is TNULL and oldsize is 0, a new block will be allocated.

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TAllocPool(), exec:TFreePool(), exec:TCreatePool()

TPutIO()

TPutIO(ioreq)
       struct TIORequest*
FUNCTION

This function puts an I/O request to the device or handler specified in the ioreq->io_Device field.

TPutIO() clears the TIOF_QUICK flag from the ioreq->io_Flags field, indicating that it prefers asynchronous execution, and forwards the request through the BeginIO-vector of the device.

Whether or not the request will be executed asynchronously remains transparent to the caller. After the request has been processed, it will return to the replyport specified in ioreq->io_ReplyPort and cause the replyport's signal to show up in the caller's task.

Always use exec:TWaitIO() to synchronize on completion of an I/O request and its removal from the replyport queue.

INPUTS
SEE ALSO

exec:TWaitIO(), exec:TDoIO(), exec:TCheckIO(), exec:TAbortIO(), exec:TPutMsg()

TWaitIO()

error = TWaitIO(ioreq)
TINT            struct TIORequest*
FUNCTION

This function waits for an I/O request to complete and unlinks it from its ioreq->io_ReplyPort. If the request has already finished or was processed synchronously then TWaitIO() drops through immediately.

RESULTS
INPUTS
SEE ALSO

exec:TPutIO(), exec:TDoIO(), exec:TCheckIO(), exec:TAbortIO(), exec:TPutMsg()

TDoIO()

error = TDoIO(ioreq)
TINT          struct TIORequest*
FUNCTION

This function performs an I/O request and waits for completion. TDoIO() indicates that it prefers synchronous execution by setting the TIOF_QUICK flag in the ioreq->io_Flags field before the request is forwarded through the BeginIO-vector of the device.

RESULTS
INPUTS
SEE ALSO

exec:TPutIO(), exec:TWaitIO(), exec:TCheckIO(), exec:TAbortIO(), exec:TPutMsg()

TCheckIO()

complete = TCheckIO(ioreq)
TBOOL               struct TIORequest*
FUNCTION

This function tests if an I/O request has been completed and returns its status to the caller.

Note that a finished I/O request still needs to be removed from the replyport's queue using exec:TWaitIO().

RESULTS
INPUTS
SEE ALSO

exec:TPutIO(), exec:TWaitIO(), exec:TDoIO(), exec:TAbortIO(), exec:TPutMsg()

TAbortIO()

error = TAbortIO(ioreq)
TINT              struct TIORequest*
FUNCTION

Ask a device to abort an I/O request that has been initiated using exec:TPutIO(). Note that abortion is a service that may or may not be granted by the addressed device or handler. You must in no way rely on successful abortion, and you still have to synchronize on the I/O request properly using exec:TWaitIO().

RESULTS
INPUTS
SEE ALSO

exec:TPutIO(), exec:TWaitIO(), exec:TDoIO(), exec:TCheckIO(), exec:TPutMsg()

TAllocTimeRequest()

timereq = TAllocTimeRequest(tags)
struct TTimeRequest*        TTAGITEM*
FUNCTION

This function opens the timer device and returns a pointer to a time request.

Each time request allocated by this function must be freed using exec:TFreeTimeRequest().

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TFreeTimeRequest()

TFreeTimeRequest()

TFreeTimeRequest(timereq)
                 struct TTimeRequest*
FUNCTION

This function frees a time request that was allocated with exec:TAllocTimeRequest().

INPUTS
SEE ALSO

exec:TAllocTimeRequest()

TGetSystemTime()

TGetSystemTime(timep)
               TTIME*
FUNCTION

This function queries a (relative) system time and inserts it into the time structure being pointed to by timep.

INPUTS
NOTES
SEE ALSO

exec:TGetUniversalDate(), exec:TGetLocalDate()

TGetUniversalDate()

error = TGetUniversalDate(datep)
TINT                      TDATE*
FUNCTION

This function queries the system's absolute time and date in UTC (Universal Time Coordinated) and inserts it into the TDATE being pointed to by datep.

RESULTS
INPUTS
NOTES
SEE ALSO

exec:TGetLocalDate(), exec:TGetSystemTime()

TGetLocalDate()

error = TGetLocalDate(datep)
TINT                  TDATE*
FUNCTION

This function queries the system's local time and date and inserts it into the TDATE being pointed to by datep.

RESULTS
INPUTS
SEE ALSO

exec:TGetUniversalDate(), exec:TGetSystemTime()

TWaitTime()

signals = TWaitTime(timeout, sigmask)
TUINT               TTIME*   TUINT
FUNCTION

Suspend the current task to wait for a set of signals or for a timeout. Any signals causing this function to return will be returned to the caller and cleared from the task's signal state. If a timeout causes the return then the return value is 0. If timeout is TNULL then this function is equivalent to exec:TWait().

INPUTS
RESULTS
SEE ALSO

exec:TWaitDate(), exec:TAllocTimeRequest(), exec:TGetSystemTime(), exec:TWait()

TWaitDate()

signals = TWaitDate(datep, sigmask)
TUINT               TDATE* TUINT
FUNCTION

Suspend the current task to wait for a set of signals or for an absolute date. Any signals causing this function to return will be returned to the caller and cleared from the task's signal state. If an expiring date causes the return then this function returns 0. If datep is TNULL then this function is equivalent to exec:TWait().

RESULTS
SEE ALSO

exec:TWaitTime(), exec:TAllocTimeRequest(), exec:TGetSystemDate()

TScanModules()

handle = TScanModules(tags)
struct THandle*       TTAGITEM*
FUNCTION

This function searches for modules that are available to TEKlib's module open function and, if successful, returns a handle that can be queried using teklib:TGetNextEntry(). Each invocation of teklib:TGetNextEntry() on the resulting handle returns a pointer to a taglist, or TNULL when there are no more entries available. Possible tags in this taglist, as currently defined, are:

  • TExec_ModuleName, (TSTRPTR) - Name of a module that would be available to exec:TOpenModule().

When you are done scanning for modules, the handle should be destroyed with teklib:TDestroy().

RESULTS
INPUTS
EXAMPLE

Scan the system for TEKlib modules with the prefix "io": 

TTAGITEM tags[2];
tags[0].tti_Tag = TExec_ModulePrefix;
tags[0].tti_Value = (TTAG) "io";
tags[1].tti_Tag = TTAG_DONE;
struct THandle *handle = TScanModules(tags);
if (handle)
{
    TTAGITEM *entry;
    while ((entry = TGetNextEntry(handle)))
        printf("%s\n", (TSTRPTR) TGetTag(entry, TExec_ModuleName, TNULL));
}
TDestroy(handle);

util

FUNCTIONS

TGetArgC()

argc = TGetArgC()
TINT
FUNCTION

Return an application's argument count.

RESULTS
  • argc - Number of arguments passd to the application

The result will be 0 if an argument vector is unsupported by the application startup.

SEE ALSO

util:TGetArgV(), util:TSetRetVal()

TGetArgV()

argv = TGetArgV()
TSTRPTR*
FUNCTION

Return an application's array of arguments.

RESULTS
  • argv - Pointer to a TNULL-terminated array of string pointers

The argument vector contains the arguments supplied to the application, or TNULL if an argument vector is unsupported by the application startup.

NOTES

If an argv vector is available, then it will always be terminated with an additional array element containing TNULL.

SEE ALSO

util:TGetArgC(), util:TSetRetVal()

TSetRetVal()

success = TSetRetVal(value)
TBOOL                TINT
FUNCTION

Set an application-wide return value. If supported by the application's entry point, the value will be returned to the hosting environment.

RESULTS
  • success - TTRUE if setting the return value succeeded.
INPUTS
  • value - Return value to set in the application
SEE ALSO

util:TGetArgC(), util:TGetArgV()

THeapSort()

success = THeapSort(refarray, length, hook)
TBOOL               TTAG*     TUINT   struct THook*
FUNCTION

Using the Heapsort algorithm, sort data of the given length, via a reference array and comparison hook. This layout allows you to sort any kind of data structure, including arrays of any type, and even lists. The reference array will usually contain indices or pointers.

RESULTS
  • success - Boolean

Possible reasons for failure are: No comparison function or reference array given or less than two entries to sort.

INPUTS
  • refarray - Array of references, i.e. indices or pointers
  • length - Number of entries to be sorted
  • hook - Comparison hook

The comparison hook function must return a value less than zero indicating "ref1 less than ref2", a value greater zero indicating "ref1 greater than ref2", and zero for "ref1 equal to ref2". It expects a pointer to the following data structure as its object: 

struct CmpData { TTAG ref1; TTAG ref2; };
NOTES

The Heapsort algorithm is slower than Quicksort, but it has no stack impact, and its performance is insensitive to the initial array order.

TSeekList()

newnode = TSeekNode(node,         steps)
struct TNode*       struct TNode* TINTPTR
FUNCTION

Seek in a doubly linked list by a given number of steps either forward (steps > 0) or backward (steps < 0), and return the node reached, or TNULL if seeked past end or before start of the list. If steps is zero, node is returned.

RESULTS
  • newnode - Node reached, or TNULL
INPUTS
  • node - Starting node
  • steps - Number of steps to seek

TIsBigEndian()

isbig = TIsBigEndian()
TBOOL
FUNCTION

Determine the host's endianness. If the host is a big endian architecture, a 32bit register containing 0x11223344 stored in memory would yield the byte sequence 0x11, 0x22, 0x33, 0x44. On such an architecture, this function returns TTRUE. On a little endian architecture, the byte sequence would be 0x44, 0x33, 0x22, 0x11, and this function returned TFALSE.

RESULTS
  • isbig - Boolean. TTRUE if the host is big endian.
SEE ALSO

util:THToNL(), util:THToNS(), util:TBSwap16(), util:TBSwap32()

TBSwap16()

TBSwap16(valp)
         TUINT16*
FUNCTION

Reverse the order of the two bytes in memory to which valp points.

INPUTS
  • valp - Pointer to a 16bit integer to swap
SEE ALSO

util:THToNL(), util:TBSwap32(), util:TIsBigEndian()

TBSwap32()

TBSwap32(valp)
         TUINT*
FUNCTION

Reverse the order of the four bytes in memory to which valp points.

INPUTS
  • valp - Pointer to a 32bit integer to swap
SEE ALSO

util:THToNL(), util:TBSwap16(), util:TIsBigEndian()

TStrDup()

dup = TStrDup(memmanager,         string)
TSTRPTR       struct TMemManager* TSTRPTR
FUNCTION

Allocate memory for, copy, and return a pointer to a duplicate of a string. If string is TNULL, a string will be allocated containing only a string's trailing zero-byte.

RESULTS
  • dup - A copy of the string, or TNULL if out of memory.
INPUTS
  • memmanager - Memory manager to allocate from, or TNULL
  • string - String to be duplicated
NOTES

The resulting string must be freed using exec:TFree().

SEE ALSO

util:TStrNDup()

TStrNDup()

dup = TStrNDup(memmanager,         string, maxlen)
TSTRPTR        struct TMemManager* TSTRPTR TSIZE
FUNCTION

Allocate memory for, copy, and return a pointer to a duplicate of a string. If string is TNULL, a string will be allocated containing only a string's trailing zero-byte. The duplicate will be limited to a maximum of maxlen characters.

RESULTS
  • dup - A copy of the string, or TNULL if out of memory.
INPUTS
  • memmanager - Memory manager to allocate from, or TNULL
  • string - String to be duplicated
  • maxlen - Maximum number of bytes to duplicate
NOTES

The resulting string must be freed using exec:TFree().

SEE ALSO

util:TStrDup()

TGetRand()

num = TGetRand(seed)
TUINT          TUINT
FUNCTION

From a seeding previous random number, generate a pseudo random number in the range from 0 to 2147483647 (hexadecimal 0x7fffffff).

RESULTS
  • num - Pseudo random number

TParseArgV()

handle = TParseArgV(template, argv,    args)
struct THandle*     TSTRPTR   TSTRPTR* TTAG*
FUNCTION

Parse an array of string pointers into an arguments array, according to a format template.

The array of string pointers is here referred to as 'argv', because a typical use of this function is to parse an application's commandline arguments. Note, however, that it can be applied to any other TNULL-terminated array of string pointers as well.

The template string specifies the expected format. Options in the template are separated by commas. Each argument consists of a name, an optional alias, and an optional set of qualifiers. Example: 

-s=SOURCE/A/M,-d=DEST/A/K

This format would require one or more source arguments and a single destination argument. Neither can be omitted. The SOURCE keyword (or its alias -s) does not need to appear in the command line. The DEST keyword (or its alias -d) must appear in the commandline to be valid. This is how the template would be interpreted:

SOURCE one two three DEST foo Valid
DEST foo -s one Valid
DEST foo Rejected - source missing
one two three foo Rejected - keyword missing
one two dest foo Valid - keywords are not case-sensitive
one two three -d foo four Valid - "four" would be added to SOURCE

An option without qualifiers represents a string argument. If present, a pointer to the string will be placed into the respective entry in the args array. Qualifiers are:

/S - Switch. This is considered a boolean variable. When this option is present, the value TTRUE will be written into the respective entry in the args array.

/N - This argument is considered an integer in decimal notation. When present, a pointer to a 32bit signed integer will be placed into the respective entry in the args array. A pointer to the number is inserted (not the number itself) so that the caller can determine whether the argument was specified.

/K - Keyword. The option will not be accepted unless the keyword appears in the argv vector.

/A - Required. This argument cannot be omitted. If not present, an error is returned.

/M - Multiple strings. Any number of strings will be accepted for this option. Not more than one /M modifier should appear in a template. Any arguments that cannot be assigned to other options will be added to this option. The respective entry in the args array will be a pointer to a TNULL-terminated array of string pointers.

If parsing is successful, this function returns a handle. When you are finished processing the arguments, this handle must be passed to teklib:TDestroy() to free all associated memory.

INPUTS
  • template - Format string
  • argv - Array of string pointers to be parsed
  • args - Pointer to an array of tags to be filled with arguments
RESULTS
  • handle - argument handle

The argument handle will be TNULL if parsing failed. When the application has finished processing the arguments, the handle must be passed to teklib:TDestroy() for freeing all associated memory.

EXAMPLE 
/* Template string */
TSTRPTR template = "-f=FROM/A,-c=CONTEXT/K,-r=RECURSE/S,-h=?/S";

/* Initialize args array to defaults */
TTAG args[4] = {TNULL, (TTAG) "linux_gcc", TFALSE, TFALSE};

/* Get argv vector */
TSTRPTR *argv = TGetArgV();

/* Pass argv + 1 so the program name argv[0] is excluded */
struct THandle *argh = TParseArgV(template, argv + 1, args);

if (argh && !args[3])
{
    /* Use the arguments here. Do not destroy the handle yet! */
}
else
{
    /* Either parsing failed or the "help" option was given */
    printusage();
}

/* Clean up */
TDestroy(argh);

THToNL()

val = THToNL(val)
TUINT         TUINT
FUNCTION

If the software is running on a little-endian architecture, this function will byte-swap the value. On a big-endian architecture, it will be returned unmodified. This will convert the specified value from/to network byte order on any architecture.

RESULTS
  • val - 32bit integer, byte-swapped if running on little-endian
INPUTS
  • val - 32bit integer
SEE ALSO

util:THToNS(), util:TIsBigEndian(), util:TBSwap32()

THToNS()

val = THToNS(val)
TUINT16      TUINT16
FUNCTION

If the software is running on a little-endian architecture, this function will byte-swap the value. On a big-endian architecture, it will be returned unmodified. This will convert the specified value from/to network byte order on any architecture.

RESULTS
  • val - 16bit integer, byte-swapped if running on little-endian
INPUTS
  • val - 16bit integer
SEE ALSO

util:THToNL(), util:TIsBigEndian(), util:TBSwap16()

TParseArgs()

handle = TParseArgs(template, argstring, argarray)
struct THandle*     TSTRPTR   TSTRPTR    TTAG*
FUNCTION

Parse an argument string into an arguments array, according to a format template.

The template string specifies the expected format. Options in the template are separated by commas. Each argument consists of a name, an optional alias, and an optional set of qualifiers.

If parsing is successful, then this function returns a handle. When you are finished processing the arguments, this handle must be passed to teklib:TDestroy() for freeing all associated memory.

See util:TParseArgV() for a detailed description of the expected format.

RESULTS
  • handle - Argument handle, or TNULL if parsing failed
INPUTS
  • template - Format string
  • argv - Array of string pointers to be parsed
  • args - Pointer to an array of tags to be filled
SEE ALSO

util:TGetArgs(), util:TParseArgV()

TGetArgs()

args = TGetArgs()
TSTRPTR
FUNCTION

Return an application's argument vector (argv) in a single string, with the individual items being seperated with spaces.

RESULTS
  • args - application arguments
SEE ALSO

util:TGetArgV()

TIsLeapYear()

isleapyear = TIsLeapYear(year)
TBOOL                    TUINT
FUNCTION

Check if year is a leap year.

RESULTS
  • isleapyear - TTRUE if leap year, TFALSE otherweise
INPUTS
  • year - Year to check
SEE ALSO

util:TIsValidDate()

TIsValidDate()

valid = TIsValidDate(day,  month, year)
TBOOL                TUINT TUINT  TUINT
FUNCTION

Check if the given combination from day, month, year is a valid date, e.g. 29, 2, 2003 would be an invalid date, and this function would return TFALSE.

RESULTS
  • valid - Boolean
INPUTS
  • day, month, year - Date
SEE ALSO

util:TIsLeapYear()

TYDayToDM()

success = TYDayToDM(yearday, year, pday,  pmonth)
TBOOL               TUINT    TUINT TUINT* TUINT*
FUNCTION

Convert a year and yearday to a month's day and month of the given year.

INPUTS
  • yearday - Daynumber in the respective year
  • year - The year
  • pday - Pointer to an integer receiving the day (may be TNULL)
  • pmonth - Pointer to an integer receiving the month (may be TNULL)
SEE ALSO

util:TDMYToYDay(), util:TMYToDay(), util:TPackDate(), util:TUnpackDate(), util:TDateToDMY()

TDMYToYDay()

yday = TDMYToYDay(day,  month, year)
TUINT             TUINT TUINT  TUINT
FUNCTION

Convert a date in the format day, month, year to yearday of the given year.

RESULTS
  • yday - Day of the year
INPUTS
  • day, month, year - Date
SEE ALSO

util:TYDayToDM(), util:TMYToDay(), util:TPackDate(), util:TUnpackDate(), util:TDateToDMY()

TMYToDay()

day = TMYToDay(month, year)
TUINT          TUINT  TUINT
FUNCTION

From the given month and year, calculate the number of days since 1-Jan-1601.

RESULTS
  • day - Day number since 1.1.1601
INPUTS
  • month - Month to convert
  • year - Year to convert
SEE ALSO

util:TYDayToDM(), util:DMYToYDay(), util:TPackDate(), util:TUnpackDate(), util:TDateToDMY()

TDateToDMY()

TDateToDMY(date,  pday,  pmonth, pyear, ptime)
           TDATE* TUINT* TUINT*  TUINT* TTIME*
FUNCTION

This function converts a date to a day, month, year, and the remaining fraction of the day into a time structure.

INPUTS
  • date - TEKlib Date
  • pday - Pointer to an integer for day (may be TNULL)
  • pmonth - Pointer to an integer for month (may be TNULL)
  • pyear - Pointer to an integer for year (may be TNULL)
  • ptime - Pointer to a TEKlib time (may be TNULL)
SEE ALSO

util:TYDayToDM(), util:TDMYToYDay(), util:TMYToDay(), util:TPackDate(), util:TUnpackDate()

TGetWeekDay()

wday = TGetWeekDay(day,  month, year)
TUINT              TUINT TUINT  TUINT
FUNCTION

This function gets the week's day number (0, sunday - 6, saturday) from a date given by day, month, year.

RESULTS
  • wday - Day of week
INPUTS
  • day - Day
  • month - Month
  • year - Year
SEE ALSO

util:TGetWeekNumber()

TGetWeekNumber()

wnumber = TGetWeekDay(day,  month, year)
TUINT                 TUINT TUINT  TUINT
FUNCTION

This function gets the year's week number from a date given by day, month, year.

RESULTS
  • wnumber - Week of year
INPUTS
  • day - Day
  • month - Month
  • year - Year
SEE ALSO

util:TGetWeekDay()

TPackDate()

success = TPackDate(datebox,         tdate)
TBOOL               struct TDateBox* TDATE*
FUNCTION

Convert a datebox structure to a date. All fields with a corresponding bit in datebox->tdb_Fields will be possibly taken into account. Fields required are TDB_YEAR and either TDB_MONTH, TDB_DAY or TDTB_YDAY. More fields like TDB_HOUR, TDB_MINUTE etc. will be incorporated to the resulting date as well, if they are present. If not enough relevant fields are provided then this function returns TFALSE.

See util:TUnpackDate() for a description of the flags in datebox->tdb_Fields.

RESULTS
  • success - TTRUE if conversion succeeded
INPUTS
  • datebox - Pointer to a source datebox structure
  • tdate - Pointer to a destination TDATE
SEE ALSO

util:TUnpackDate()

TUnpackDate()

TUnpackDate(date,  datebox,         fields)
            TDATE* struct TDateBox* TUINT16
FUNCTION

Convert a date to a datebox structure. At least the fields marked in the fields argument will be inserted to the resulting datebox structure.

Specific combinations of date fields may be sufficient for a given purpose, like TDB_DAY|TDB_MONTH|TDB_YEAR or TDB_YDAY|TDB_YEAR|TDB_SEC. If you want to receive all fields, pass TDB_ALL in the fields argument. The fields actually being inserted by this function (which can be more than requested) will be flagged as correponding bits in datebox->tdb_Fields.

INPUTS
  • date - pointer to a source date
  • datebox - pointer to a TDateBox structure to be filled in
  • fields - Fields to be inserted into the datebox structure. Valid flag fields:
    Flag Description corresponds to
    TDB_YEAR year datebox->tdb_Year
    TDB_YDAY day of year datebox->tdb_YDay
    TDB_MONTH month of year datebox->tdb_Month
    TDB_WEEK week of year datebox->tdb_Week
    TDB_WDAY day of week datebox->tdb_WDay
    TDB_DAY day of month datebox->tdb_Day
    TDB_HOUR hour of day datebox->tdb_Hour
    TDB_MINUTE minute of hour datebox->tdb_Minute
    TDB_SEC second of minute datebox->tdb_Sec
    TDB_USEC 1/1000000th sec datebox->tdb_USec
    TDB_ALL all of the above all of the above
SEE ALSO

util:TPackDate()

Document generated on Wed Mar 18 00:57:35 2009