utility.library Reference¶

Comprehensive function reference for utility.library, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/AG/utility).

This page documents 43 functions of utility.library. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.

Function index¶

AddNamedObject()
AllocateTagItems()
AllocNamedObjectA()
Amiga2Date()
ApplyTagChanges()
AttemptRemNamedObject()
CallHookPkt()
CheckDate()
CloneTagItems()
Date2Amiga()
FilterTagChanges()
FilterTagItems()
FindNamedObject()
FindTagItem()
FreeNamedObject()
FreeTagItems()
GetTagData()
GetUniqueID()
MapTags()
NamedObjectName()
NextTagItem()
PackBoolTags()
PackStructureTags()
RefreshTagItemClones()
ReleaseNamedObject()
RemNamedObject()
SDivMod32()
SDivMod64()
SMult32()
SMult64()
Stricmp()
Strncat()
Strncpy()
Strnicmp()
TagInArray()
ToLower()
ToUpper()
UDivMod32()
UDivMod64()
UMult32()
UMult64()
UnpackStructureTags()
VSNPrintf()

`AddNamedObject()`¶

AddNamedObject -- add a named object to the given namespace. (V39)

Synopsis

success = AddNamedObject(nameSpace, object); D0 A0 A1

BOOL AddNamedObject(NamedObject*,NamedObject*);

Function

Adds a new item to a NameSpace. If the NameSpace doesn't support duplicate names, a search for a duplicate will be made, and 0 (failure) will be returned. Otherwise, the entry will be Enqueue()ed to the NameSpace.

Inputs

nameSpace - the name space to add to (NULL for root namespace) object - the object to add (If NULL, will return failure)

Results

success - whether the operation succeeded. Check this always!

`AllocateTagItems()`¶

AllocateTagItems -- allocate a tag list. (V36)

Synopsis

tagList = AllocateTagItems(numTags); D0 D0

TagItem*AllocateTagItems(ULONG);

Function

Allocates the specified number of usable TagItems slots.

Note that to access the TagItems in 'tagList', you should use
the function NextTagItem(). This will insure you respect any
chaining (TAG_MORE) and secret hiding places (TAG_IGNORE) that
this function might generate.

Inputs

numTags - the number of TagItem slots you want to allocate.

Results

tagList - the allocated chain of TagItem structures, or NULL if there was not enough memory. An allocated tag list must eventually be freed using FreeTagItems().

See also

FreeTagItems(), CloneTagItems()

`AllocNamedObjectA()`¶

AllocNamedObjectA -- allocate a named object. (V39)

Synopsis

object = AllocNamedObjectA(name, tagList); D0 A0 A1

NamedObject*AllocNamedObjectA(STRPTR,TagItem*);

object = AllocNamedObject(name, Tag1, ...);

NamedObject*AllocNamedObject(STRPTR, ULONG, ...);

Function

Allocates a NamedObject and initializes it as needed to the name given. This object can then be used as an object in the namespaces. Tags can be given to make an object contain a namespace such that nested namespaces can be built. When the object is allocated, it automatically has one use. If you later wish to release this object such that others may remove it from the namespace you must do a ReleaseNamedObject().

Inputs

name - name for the object (must not be NULL) tagList - tags with additional information for the allocation or NULL

Results

object - the object allocated, or NULL for failure. The object is defined as a pointer to a pointer. You can do what you wish with the pointer. (It may be NULL or contain a pointer to memory that you had asked for in the tags.)

See also

FreeNamedObject()

`Amiga2Date()`¶

Amiga2Date -- fill in a ClockData structure based on a system time stamp (V36)

Synopsis

Amiga2Date(seconds,result); D0 A0

VOID Amiga2Date(ULONG,ClockData*);

Function

Fills in a ClockData structure with the date and time calculated from a ULONG containing the number of seconds from 01-Jan-1978 to the date.

Inputs

seconds - the number of seconds from 01-Jan-1978. result - a pointer to a ClockData structure that will be altered by this function

See also

CheckDate(), Date2Amiga()

`ApplyTagChanges()`¶

ApplyTagChanges -- change a tag list based on a second tag list. (V39)

Synopsis

ApplyTagChanges(list,changeList); A0 A1

VOID ApplyTagChanges(TagItem*,TagItem*);

Function

For any tag that appears in both 'list' and 'changeList', this function will change the ti_Data field of the tag in 'list' to match the ti_Data field of the tag in 'changeList'. In effect, 'changeList' contains a series of new values for tags already in 'list'. Any tag in 'changeList' that is not in 'list' is ignored.

Inputs

list - a list of existing tags (may be NULL) changeList - a list of tags to modify 'list' with (may be NULL)

See also

FilterTagChanges()

`AttemptRemNamedObject()`¶

AttemptRemNamedObject -- attempt to remove a named object. (V39)

Synopsis

result = AttemptRemNamedObject(object); D0 A0

LONG AttemptRemNamedObject(NamedObject*);

Function

Attempts to remove an object from whatever NameSpace it's in. You must have found the object first (in order to get a use count) before trying to remove it. If the object is in use or is in the process of being removed, this function will return a failure code. If the object is fully removed, the object will then be available to be FreeNamedObject().

Inputs

object - the object to attempt to remove The object must be valid

Results

success - FALSE if object is still in use (somewhere) TRUE if object was removed

`CallHookPkt()`¶

CallHookPkt -- invoke a Hook function callback. (V36)

Synopsis

return = CallHookPkt(hook,object,message); D0 A0 A2 A1

ULONG CallHookPkt(Hook*,APTR,APTR);

Function

Performs the callback standard defined by a Hook structure. This function is really very simple; it effectively performs a JMP to Hook->h_Entry.

It is probably just as well to do this operation in an
assembly language function linked in to your program, possibly
from a compiler supplied library or a builtin function.

It is anticipated that C programs will often call a 'varargs'
variant of this function which will be named CallHook. This
function must be provided in a compiler specific library, but
an example of use would be:

result = CallHook(hook,dataobject,COMMAND_ID,param1,param2);

The function CallHook() can be implemented in many C compilers
like this:

ULONG CallHook(struct Hook *hook, APTR object, ULONG command, ... )
{
    return(CallHookPkt(hook,object,(APTR)&command));
}

Inputs

hook - pointer to an initialized Hook structure as defined in object - useful data structure in the particular context the hook is being used for. message - pointer to a message to be passed to the hook. This is not an Exec Message structure, but is a message in the OOP sense.

Results

return - the value returned by the hook function.

`CheckDate()`¶

CheckDate -- checks a ClockData structure for legal date. (V36)

Synopsis

seconds = CheckDate(date); D0 A0

ULONG CheckDate(ClockData*);

Function

Determines if the ClockData structure contains legal date information and returns the number of seconds from 01-Jan-1978 to that date, or 0 if the ClockData structure contains illegal data.

Inputs

date - a filled-in ClockData structure

Results

seconds - 0 if date is invalid, otherwise the number of seconds from 01-Jan-1978 to the date

Bugs

The wday field of the ClockData structure is not checked.

See also

Amiga2Date(), Date2Amiga()

`CloneTagItems()`¶

CloneTagItems -- copy a tag list. (V36)

Synopsis

clone = CloneTagItems(original); D0 A0

TagItem*CloneTagItems(TagItem*);

Function

Copies the essential contents of a tag list into a new tag list.

The cloning is such that calling FindTagItem() with a given tag on
the original or cloned tag lists will always return the same
tag value. That is, the ordering of the tags is maintained.

Inputs

original - tag list to clone. May be NULL, in which case an empty tag list is returned.

Results

clone - copy of the original tag list, or NULL if there was not enough memory. This tag list must eventually by freed by calling FreeTagItems().

`Date2Amiga()`¶

Date2Amiga -- calculate seconds from 01-Jan-1978. (V36)

Synopsis

seconds = Date2Amiga(date); D0 A0

ULONG Date2Amiga(ClockData*);

Function

Calculates the number of seconds from 01-Jan-1978 to the date specified in the ClockData structure.

Inputs

date - pointer to a ClockData structure containing the date of interest.

Results

seconds - the number of seconds from 01-Jan-1978 to the date specified.

See also

Amiga2Date(), CheckDate()

`FilterTagChanges()`¶

FilterTagChanges -- eliminate tags which specify no change. (V36)

Synopsis

FilterTagChanges(changeList,originalList,apply); A0 A1 D0

VOID FilterTagChanges(TagItem*,TagItem*, ULONG);

Function

This function goes through changeList. For each item found in changeList, if the item is also present in originalList, and their data values are identical, then the tag is removed from changeList. If the two tag's data values are different and the 'apply' value is non-zero, then the tag data in originalList will be updated to match the value from changeList.

Inputs

changeList - list of new tags (may be NULL) originalList - a list of existing tags (may be NULL) apply - boolean specification as to whether the data values in originalList are to be updated to the data values in changeList.

Example

Assume you have an attribute list for an object (originalList) which looks like this:

    {ATTR_Size,  "large"},
    {ATTR_Color, "orange"},
    {ATTR_Shape, "square"}

If you receive a new tag list containing some changes (changeList),
which looks like this:

    {ATTR_Size,  "large"},
    {ATTR_Shape, "triangle"}

If you call FilterTagChanges(), changeList will be modified to
contain only those attributes which are different from those
in originalList. All other items will have their tag values set to
TAG_IGNORE. The resulting changeList will become:

    {TAG_IGNORE, "large"},
    {ATTR_Shape, "triangle"}

If 'apply' was set to 0, originalList would be unchanged. If 'apply'
was non-zero, originalList would be changed to:

    {ATTR_Size,  "large"},
    {ATTR_Color, "orange"},
    {ATTR_Shape, "triangle"}

See also

ApplyTagChanges()

`FilterTagItems()`¶

FilterTagItems -- remove selected items from a tag list. (V36)

Synopsis

numValid = FilterTagItems(tagList,filterArray,logic); D0 A0 A1 D0

ULONG FilterTagItems(TagItem*,Tag *,ULONG);

Function

Removes tag items from a tag list (by changing ti_Tag to TAG_IGNORE) depending on whether its ti_Tag value is found in an array of tag values.

If the 'logic' parameter is TAGFILTER_AND, then all items
not appearing in 'tagArray' are excluded from 'tagList'.

If 'logic' is TAGFILTER_NOT, then items not found in 'tagArray'
are preserved, and the ones in the array are cast out.

Inputs

tagList - input list of tag items which is to be filtered by having selected items changed to TAG_IGNORE. filterArray - an array of tag values, terminated by TAG_DONE, as specified in the documentation for TagInArray(). logic - specification whether items in 'tagArray' are to be included or excluded in the filtered result.

Results

numValid - number of valid items left in resulting filtered list.

See also

TagInArray()

`FindNamedObject()`¶

FindNamedObject -- find the next object of a given name. (V39)

Synopsis

object = FindNamedObject(nameSpace, name, lastObject); D0 A0 A1 A2

NamedObject*FindNamedObject(NamedObject*, STRPTR, NamedObject*);

Function

Finds an object and adds to the open count of the object. The object is guaranteed not to be freed until ReleaseNamedObject() is called. The name comparison is caseless, using the current locale string comparison routines.

If name is NULL, then all objects will be matched.

If lastObject is non-NULL, it must be an object from the same
NameSpace found on a previous call to FindNamedObject(). It
will not be freed by this call. The search will start at the
node after lastobject, if non-NULL.

nameSpace is the name space from the named object given
or the root name space if NULL is given.

Inputs

nameSpace - the name space to search name - the name of the object to search for lastObject - the starting point for the search or NULL

Results

object - the first match found, or NULL for no match

See also

ReleaseNamedObject()

`FindTagItem()`¶

FindTagItem -- scan a tag list for a specific tag. (V36)

Synopsis

tag = FindTagItem(tagValue,tagList); D0 D0 A0

TagItem*FindTagItem(Tag,TagItem*);

Function

Scans a tag list and returns a pointer to the first item with ti_Tag matching the 'tagValue' parameter.

Inputs

tagValue - tag value to search for tagList - tag item list to search (may be NULL)

Results

tag - a pointer to the item with ti_Tag matching 'tagValue' or NULL if no match was found.

`FreeNamedObject()`¶

FreeNamedObject -- frees a name object. (V39)

Synopsis

FreeNamedObject(object); A0

VOID FreeNamedObject(NamedObject*);

Function

Free one of a number of structures used by utility.library. The item must not be a member of any NameSpace, and no one may have it open other than yourself. If the object also contained a NameSpace, that namespace must be empty. Any additional space allocated via the datasize parameter for AllocNamedObject() is also released.

Inputs

object - the object to be freed

See also

AllocNamedObjectA()

`FreeTagItems()`¶

FreeTagItems -- free an allocated tag list. (V36)

Synopsis

FreeTagItems(tagList); A0

VOID FreeTagItems(TagItem*);

Function

Frees the memory of a TagItem list allocated either by AllocateTagItems() or CloneTagItems().

Inputs

tagList - list to free, must have been obtained from AllocateTagItems() or CloneTagItems() (may be NULL)

See also

AllocateTagItems(), CloneTagItems()

`GetTagData()`¶

GetTagData -- obtain the data corresponding to a tag. (V36)

Synopsis

value = GetTagData(tagValue,defaultVal,tagList); D0 D0 D1 A0

ULONG GetTagData(Tag,ULONG,TagItem*);

Function

Searches a tag list for a matching tag, and returns the corresponding ti_Data value for the TagItem found. If no match is found, this function returns the value passed in as 'default'.

Inputs

tagValue - tag value to search for. defaultVal - value to be returned if tagValue is not found. tagList - the tag list to search.

Results

value - the ti_Data value for the first matching TagItem, or 'default' if a ti_Tag matching 'Tag' is not found.

`GetUniqueID()`¶

GetUniqueID -- return a relatively unique number. (V39)

Synopsis

id = GetUniqueID(); D0

ULONG GetUniqueID(VOID);

Function

Returns a unique value each time it is called. This is useful for things that need unique ID such as the GadgetHelp ID, etc. Note that this is only unique for 4,294,967,295 calls to this function. Under normal use this is not a problem. This function is safe in interrupts.

Results

id - a 32-bit value that is unique.

`MapTags()`¶

MapTags -- convert ti_Tag values in a list via map pairing. (V36)

Synopsis

MapTags(tagList,mapList,mapType); A0 A1 D0

VOID MapTags(TagItem*,TagItem*,ULONG);

Function

Apply a "mapping list" mapList to tagList.

If the ti_Tag field of an item in tagList appears as ti_Tag in some
item in mapList, overwrite ti_Tag with the corresponding ti_Data
from the map list.

The mapType parameter specifies how the mapping operation is to
proceed, with the following available types:

    MAP_REMOVE_NOT_FOUND
    If a tag in tagList does not appear in the mapList, remove
    it from tagList.

    MAP_KEEP_NOT_FOUND
    To have items which do not appear in the mapList survive the
    mapping process as-is.

MapTags() is central to BOOPSI gadget interconnections where you want
to convert the tag values from one space (the sender) to another (the
receiver).

The procedure will change the values of the input tag list
tagList (but not mapList).

You can "filter" a list by passing MAP_REMOVE_NOT_FOUND as mapType,
and having the data items in mapList equal the corresponding tags.

You can perform the inverse filter ("everything but") by passing
a mapType of MAP_KEEP_NOT_FOUND, and creating a map item for every tag
you want to filter out, pairing it with a mapped data value of
TAG_IGNORE.

For safety and "order independence" of tag item arrays, if you
attempt to map some tag to the value TAG_DONE, the value TAG_IGNORE
will be substituted instead.

Inputs

tagList - input list of tag items which is to be mapped to tag values as specified in mapList. mapList - a "mapping list" tag list which pairs tag values expected to appear in tagList with new values to be substituted in the ti_Tag fields of tagList (may be NULL) mapType - one of the available mapping types as defined in

Example

* Consider this source list: *\ struct TagItem list[] = { {MY_SIZE, 71}, {MY_WEIGHT, 200}, {TAG_DONE, } };

\* And the mapping list: *\
    struct TagItem map[] =
    {
    {MY_SIZE,   HIS_TALL},
    {TAG_DONE,  }
    };

\* Then after MapTags(list,map,MAP_REMOVE_NOT_FOUND), 'list' will
   become: *\
    {HIS_TALL,71},
    {TAG_IGNORE,},
    {TAG_DONE,}

\* Or after MapTags(list,map,MAP_KEEP_NOT_FOUND), 'list' will
   become: *\
    {HIS_TALL,  71},
    {MY_WEIGHT, 200},
    {TAG_DONE,  }

Bugs

Prior to V39, the mapType parameter did not work. The function always behaved as if the parameter was set to MAP_KEEP_NOT_FOUND.

`NamedObjectName()`¶

NamedObjectName -- return the name of the object. (V39)

Synopsis

name = NamedObjectName(object); D0 A0

STRPTR NamedObjectName(NamedObject*);

Function

Returns the name of the object passed in... Note that the name string is passed back as just a pointer to a read-only name. If the object goes away, so does the name.

Inputs

object - the object, may be NULL in which case this function returns NULL.

Results

name - pointer to the name string, or NULL if 'object' is NULL.

See also

FindNamedObject(), RemNamedObject()

`NextTagItem()`¶

NextTagItem -- iterate through a tag list. (V36)

Synopsis

tag = NextTagItem(tagItemPtr); D0 A0

TagItem*NextTagItem(TagItem**);

Function

Iterates through a tag list, skipping and chaining as dictated by system tags. TAG_SKIP will cause it to skip the entry and a number of following tags as specified in ti_Data. TAG_IGNORE ignores that single entry, and TAG_MORE has a pointer to another array of tags (and terminates the current array!). TAG_DONE also terminates the current array. Each call returns either the next tagitem you should examine, or NULL when the end of the list has been reached.

Inputs

tagItemPtr - doubly-indirect reference to a TagItem structure. The pointer will be changed to keep track of the iteration.

Results

nextTag - each TagItem in the array or chain of arrays that should be processed according to system tag values defined in ) is returned in turn with successive calls.

Example

Iterate(struct TagItem tags); { struct TagItem tstate; struct TagItem *tag;

    tstate = tags;
    while (tag = NextTagItem(&tstate))
    {
    switch (tag->ti_Tag)
    {
        case TAG1: ...
               break;

        case TAG2: ...
               break;

        ...
    }
    }
}

`PackBoolTags()`¶

PackBoolTags -- builds a "flag" word from a tag list. (V36)

Synopsis

flags = PackBoolTags(initialFlags,tagList,boolMap); D0 D0 A0 A1

ULONG PackBoolTags(ULONG,TagItem*,TagItem*);

Function

Picks out the boolean tag items in a tag list and converts them into bit-flag representations according to a correspondence defined by the tag list 'boolMap'.

A boolean tag item is one where only the logical value of
the ti_Data is relevant. If this field is 0, the value is
FALSE, otherwise TRUE.

Inputs

initialFlags - a starting set of bit-flags which will be changed by the processing of TRUE and FALSE boolean tags in tagList. tagList - a TagItem list which may contain several tag items defined to be boolean by their presence in boolMap. The logical value of ti_Data determines whether a tag item causes the bit-flag value related by boolMap to be set or cleared in the returned flag longword. boolMap - a tag list defining the boolean tags to be recognized, and the bit (or bits) in the returned longword that are to be set or cleared when a boolean Tag is found to be TRUE or FALSE in tagList.

Results

flags - the accumulated longword of bit-flags, starting with initialFlags and modified by each boolean tag item encountered.

Example

* define some nice user tag values ... *\ enum mytags { tag1 = TAG_USER+1, tag2, tag3, tag4, tag5 };

\* this TagItem list defines the correspondence between boolean tags
 * and bit-flag values.
 *\
struct TagItem boolMap[] =
{
    {tag1,     0x0001},
    {tag2,     0x0002},
    {tag3,     0x0004},
    {tag4,     0x0008},
    {TAG_DONE, }
};

\* You are probably passed these by some client, and you want
 * to "collapse" the boolean content into a single longword.
 *\

struct TagItem boolExample[] =
{
    {tag1,     TRUE},
    {tag2,     FALSE},
    {tag5,     Irrelevant},
    {tag3,     TRUE},
    {TAG_DONE, }
};

\* Perhaps 'boolFlags' already has a current value of 0x800002. *\
boolFlags = PackBoolTags(boolFlags,boolExample,boolMap);

\* The resulting new value of 'boolFlags' will be 0x80005. \*

`PackStructureTags()`¶

PackStructureTags -- pack a structure with values from taglist. (V39)

Synopsis

num = PackStructureTags(pack,packTable,tagList); D0 A0 A1 A2

ULONG PackStructureTags(APTR,ULONG *,TagItem*);

Function

For each table entry, a FindTagItem() will be done and if the matching tag is found in the taglist, the data field will be packed into the given structure based on the packtable definition.

Inputs

pack - a pointer to the data area to fill in. packTable - a pointer to the packing information table. See for definition and macros. tagList - a pointer to the taglist to pack into the structure

Results

num - the number of tag items packed

`RefreshTagItemClones()`¶

RefreshTagItemClones -- rejuvenate a clone from the original. (V36)

Synopsis

RefreshTagItemClones(clone,original) A0 A1

VOID RefreshTagItemClones(TagItem*,TagItem*);

Function

If (and only if) the tag list 'clone' was created from 'original' by CloneTagItems(), and if 'original' has not been changed in any way, you can reset the clone list to its original state by using this function.

Inputs

clone - return value from CloneTagItems(original) original - a tag list that hasn't changed since CloneTagItems()

`ReleaseNamedObject()`¶

ReleaseNamedObject -- free a named object. (V39)

Synopsis

ReleaseNamedObject(object); A0

VOID ReleaseNamedObject(NamedObject*);

Function

Decrements the open count of the object. If the object has been removed, and the count goes to 0, the remover will be notified that the object is now free.

Inputs

object - the object to release. (No action if NULL)

See also

FindNamedObject(), RemNamedObject()

`RemNamedObject()`¶

RemNamedObject -- remove a named object. (V39)

Synopsis

RemNamedObject(object, message); A0 A1

VOID RemNamedObject(NamedObject*,Message*);

Function

This function will post a request to release the object from whatever NameSpace it is in. It will reply the message when the object is fully removed. The message.mn_Node.ln_Name field will contain the object pointer or NULL if the object was removed by another process.

This function will effectively do a ReleaseNamedObject()
thus you must have "found" the object first.

Inputs

object - the object to remove: Must be a valid NamedObject. message - message to ReplyMsg() (must be supplied)

Results

The message is replied with the ln_Name field either being the object or NULL. If it contains the object, the object is completely removed.

`SDivMod32()`¶

SDivMod32 -- signed 32 by 32 bit division and modulus. (V36)

Synopsis

quotient:remainder = SDivMod32(dividend,divisor); D0 D1 D0 D1

LONG:LONG SDivMod32(LONG,LONG);

Function

Divides the signed 32 bit dividend by the signed 32 bit divisor and returns a signed 32 bit quotient and remainder.

Inputs

dividend - signed 32 bit dividend. divisor - signed 32 bit divisor.

Results

quotient - signed 32 quotient of the division. remainder - signed 32 remainder of the division.

Notes

Unlike other Amiga library function calls, the utility.library 32 bit math routines do NOT require A6 to be loaded with a pointer to the library base. A6 can contain anything the application wishes. This is in order to avoid overhead in calling them.

In addition, the utility.library math routines preserve all
address registers including A0 and A1

`SDivMod64()`¶

SDivMod64 -- signed 64 by 32 division with 32 bit result (V47)

Synopsis

result = SDivMod64(dividendhi,dividendlo,divisor); D0:D1 D1 D0 D2

LONG SDivMod64(LONG,ULONG,LONG);

Function

Returns the quotient of the unsigned 64 bit division of the divisor in registers D1 and D0, with the upper 32 bits in D1, by the divisor in D2 in D0. The remainder is returned in D1.

Inputs

dividendhi, dividendlo: upper and lower 32 bits of the dividend divisor: 32 bit divisor

Results

result - the 32 bit quotient in D0 and the remainder in D1 on overflow, registers are unchanged and the V processor bit is set

Notes

In addition, the utility.library math routines preserve all
address registers including A0 and A1

`SMult32()`¶

SMult32 -- signed 32 by 32 bit multiply with 32 bit result. (V36)

Synopsis

result = SMult32(arg1,arg2); D0 D0 D1

LONG SMult32(LONG,LONG);

Function

Returns the signed 32 bit result of multiplying arg1 by arg2.

Inputs

arg1, arg2 - numbers to multiply

Results

result - the signed 32 bit result of multiplying arg1 by arg2.

Notes

In addition, the utility.library math routines preserve all
address registers including A0 and A1

`SMult64()`¶

SMult64 -- signed 32 by 32 bit multiply with 64 bit result. (V39)

Synopsis

result = SMult64(arg1,arg2); D0:D1 D0 D1

LONG SMult64(LONG,LONG);

Function

Returns the signed 64 bit result of multiplying arg1 by arg2.

Inputs

arg1, arg2 - numbers to multiply

Results

result - the signed 64 bit result of multiplying arg1 by arg2.

Notes

In addition, the utility.library math routines preserve all
address registers including A0 and A1

`Stricmp()`¶

Stricmp -- case-insensitive string comparison. (V37)

Synopsis

result = Stricmp(string1,string2); D0 A0 A1

LONG Stricmp(STRPTR,STRPTR);

Function

This function compares two strings, ignoring case using a generic case conversion routine. If the strings have different lengths, the shorter is treated as if it were extended with zeros.

Inputs

string1, string2 - strings to be compared

Results

result - relationship between string1 and string2 <0 means string1 < string2 =0 means string1 = string2 >0 means string1 > string2

Notes

Whenever locale.library is installed in a system, this function is replaced by language-specific code. This means that depending on which language the user has currently selected, identical pairs of strings may return different values when passed to this function. This fact must be taken into consideration when using this function.

See also

Strnicmp(), StrnCmp()

`Strncat()`¶

Strncat -- concatenate two strings, length limited (V47)

Synopsis

end = Strncat(dst,src,size) D0 A1 A0 D0

UBYTE *Strncat(UBYTE *dst,const UBYTE *src,ULONG bufsize);

Function

Appends the source string at the end of the destionation string possibly truncating the result to fit to the buffer. Returns a pointer to the terminating NUL of the target string, or NULL if the string was truncated.

Inputs

src - source string to be appended. If NULL, it is treated as if it were an empty string. dst - buffer to write to, or NULL. In case the target buffer is NULL, NULL is returned immediately. bufsize - size of the target buffer in bytes. If this is 0, then no data is copied and NULL is returned immediately.

Results

end - pointer to the NUL byte of the target string, or NULL in case the target was truncated.

Notes

The curious return code allows easy chaining of multiple Strncat() calls. Even in case the target was truncated, it is always NUL terminated.

See also

RawDoFmt()

`Strncpy()`¶

Strncpy -- copy a string, length limited (V47)

Synopsis

end = Strncpy(dst,src,size) D0 A1 A0 D0

UBYTE *Strncpy(UBYTE *dst,const UBYTE *src,ULONG bufsize);

Function

Copies one string into another, possibly truncating it to the target buffer size. Returns a pointer to the terminating NUL of the target string, or NULL if the target was truncated.

Inputs

src - source string to be copied. If NULL, it is treated as if it were an empty string. dst - buffer to write to, or NULL. In case the target buffer is NULL, NULL is returned immediately. bufsize - size of the target buffer in bytes. If this is 0, then no data is copied and NULL is returned immediately.

Results

end - pointer to the NUL byte of the target string, or NULL in case the target buffer was too short.

Notes

The curious return code allows easy chaining of multiple Strncpy() calls, i.e. Strncpy(src2,Strncpy(src1,buffer,size),size) concatenates the source strings src1 and src2 in the same buffer. Note that even if the target buffer is too small, a partial copy has been performed and the result is still NUL-terminated.

See also

RawDoFmt()

`Strnicmp()`¶

Strnicmp -- length-limited case-insensitive string compare. (V37)

Synopsis

result = Strnicmp(string1,string2,length); D0 A0 A1 D0

LONG Strnicmp(STRPTR,STRPTR,LONG);

Function

This function compares two strings, ignoring case using a generic case conversion routine. If the strings have different lengths, the shorter is treated as if it were extended with zeros. This function never compares more than 'length' characters.

Inputs

string1, string2 - strings to be compared length - maximum number of characters to examine

Results

result - relationship between string1 and string2 <0 means string1 < string2 =0 means string1 = string2 >0 means string1 > string2

Notes

See also

Stricmp(), StrnCmp()

`TagInArray()`¶

TagInArray -- check if a tag value appears in an array of tag values. (V36)

Synopsis

result = TagInArray(tagValue,tagArray); D0 D0 A0

BOOL TagInArray(Tag,Tag *);

Function

Performs a quick scan to see if a tag value appears in an array terminated with TAG_DONE. Returns TRUE if the value is found.

The 'tagArray' must be terminated by TAG_DONE. Note that this is an
array of tag values, NOT an array of TagItems.

Inputs

tagValue - tag value to search array for in array. tagArray - a simple array of tag values terminated by TAG_DONE.

Results

result - TRUE if tagValue was found in tagArray.

See also

FilterTagItems()

`ToLower()`¶

ToLower -- convert a character to lower case. (V37)

Synopsis

char = ToLower(char); D0 D0

UBYTE ToLower(UBYTE);

Function

Converts a character to lower case, handling international character sets.

Inputs

char - character to be converted.

Results

char - lower case version of the input character.

Notes

Whenever locale.library is installed in a system, this function is replaced by language-specific code. This means that depending on which language the user has currently selected, a given character may return different results when passed to this function. This fact must be taken into consideration when using this function.

See also

ToUpper(), ConvToLower()

`ToUpper()`¶

ToUpper -- convert a character to upper case. (V37)

Synopsis

char = ToUpper(char); D0 D0

UBYTE ToUpper(UBYTE);

Function

Converts a character to upper case, handling international character sets.

Inputs

char - character to be converted.

Results

char - upper case version of input character.

Notes

Whenever locale.library is installed in a system, this function is replaced by language-specific code. This means that depending on which language the user has currently selected, a given character may return different results when passed to this function. This fact must be taken into consideration when using this function.

See also

ConvToLower()

`UDivMod32()`¶

UDivMod32 -- unsigned 32 by 32 bit division and modulus. (V36)

Synopsis

quotient:remainder = UDivMod32(dividend,divisor); D0 D1 D0 D1

ULONG:ULONG UDivMod32(ULONG,ULONG);

Function

Divides the unsigned 32 bit dividend by the unsigned 32 bit divisor and returns an unsigned 32 bit quotient and remainder.

Inputs

dividend - unsigned 32 bit dividend. divisor - unsigned 32 bit divisor.

Results

quotient - unsigned 32 quotient of the division. remainder - unsigned 32 remainder of the division.

Notes

In addition, the utility.library math routines preserve all
address registers including A0 and A1

`UDivMod64()`¶

UDivMod64 -- unsigned 64 by 32 division with 32 bit result (V47)

Synopsis

result = UDivMod64(dividendhi,dividendlo,divisor); D0:D1 D1 D0 D2

ULONG UDivMod64(ULONG,ULONG,ULONG);

Function

Returns the quotient of the unsigned 64 bit division of the divisor in registers D1 and D0, with the upper 32 bits in D1, by the divisor in D2 in D0. The remainder is returned in D1.

Inputs

dividendhi, dividendlo: upper and lower 32 bits of the dividend divisor: 32 bit divisor

Results

result - the 32 bit quotient in D0 and the remainder in D1 on overflow, registers are unchanged and the V processor bit is set

Notes

In addition, the utility.library math routines preserve all
address registers including A0 and A1

`UMult32()`¶

UMult32 -- unsigned 32 by 32 bit multiply with 32 bit result. (V36)

Synopsis

result = UMult32(arg1,arg2); D0 D0 D1

ULONG UMult32(ULONG,ULONG);

Function

Returns the unsigned 32 bit result of multiplying arg1 by arg2.

Inputs

arg1, arg2 - numbers to multiply

Results

result - the unsigned 32 bit result of multiplying arg1 by arg2.

Notes

In addition, the utility.library math routines preserve all
address registers including A0 and A1

`UMult64()`¶

UMult64 -- unsigned 32 by 32 bit multiply with 64 bit result. (V39)

Synopsis

result = UMult64(arg1,arg2); D0:D1 D0 D1

ULONG UMult64(ULONG,ULONG);

Function

Returns the unsigned 64 bit result of multiplying arg1 by arg2.

Inputs

arg1, arg2 - numbers to multiply

Results

result - the unsigned 64 bit result of multiplying arg1 by arg2.

Notes

In addition, the utility.library math routines preserve all
address registers including A0 and A1

`UnpackStructureTags()`¶

UnpackStructureTags -- unpack a structure to values in taglist. (V39)

Synopsis

num = UnpackStructureTags(pack,packTable,tagList); D0 A0 A1 A2

ULONG UnpackStructureTags(APTR,ULONG *,TagItem*);

Function

For each table entry, a FindTagItem() will be done and if the matching tag is found in the taglist, the data in the structure will be placed into the memory pointed to by the tag's ti_Data. ti_Data must point to a LONGWORD.

Inputs

pack - a pointer to the data area to be unpacked packTable - a pointer to the packing information table. See for definition and macros tagList - a pointer to the taglist to unpack into

Results

num - the number of tag items unpacked

See also

FindTagItem(), PackStructureTags()

`VSNPrintf()`¶

VSNPrintf -- print formatted data, length limited (V47)

Synopsis

length = VSNPrintf(buffer,bufsize,fmt,data) D0 A0 D0 A1, A2

LONG VSNPrintf(UBYTE *buffer,ULONG bufsize,const UBYTE *fmt,APTR data);

LONG SNPrintf(UBYTE *buffer,ULONG bufsize,const UBYTE *fmt,...);

Function

Prints formatted data using the format instructions of RawDoFmt() into a length-limited buffer, and returns the full number of characters (including NUL) that would have been written in total for an unlimited buffer size.

Inputs

buffer - buffer to write to, or NULL if only the size of the required buffer is to be determined bufsize - buffer size into which the output is to fit fmt - format string, using the formatting instructions of RawDoFmt(), see there for details data - data stream containing the source to be formatted

Results

length - buffer size required for the output. This may be larger than the buffer

Notes

The output is always NUL terminated if a buffer is supplied and its size is non-zero. The return code of this function indicates the size the output buffer must at least have to hold the full formatted output, INCLUDING the NUL byte. Note that this is different from the ANSI function which returns the (hypothetical) string size.

Starting with version 47.3, both the LVO and the argument register
order of this function have been changed for compatibility reasons.
Make sure to have a recent copy of the AmigaOS include files so that
your applications use the correct API to call VSNPrintf().

See also

RawDoFmt()

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

utility.library Reference¶

Function index¶

AddNamedObject()¶

AllocateTagItems()¶

AllocNamedObjectA()¶

Amiga2Date()¶

ApplyTagChanges()¶

AttemptRemNamedObject()¶

CallHookPkt()¶

CheckDate()¶

CloneTagItems()¶

Date2Amiga()¶

FilterTagChanges()¶

FilterTagItems()¶

FindNamedObject()¶

FindTagItem()¶

FreeNamedObject()¶

FreeTagItems()¶

GetTagData()¶

GetUniqueID()¶

MapTags()¶

NamedObjectName()¶

NextTagItem()¶

PackBoolTags()¶

PackStructureTags()¶

RefreshTagItemClones()¶

ReleaseNamedObject()¶

RemNamedObject()¶

SDivMod32()¶

SDivMod64()¶

SMult32()¶

SMult64()¶

Stricmp()¶

Strncat()¶

Strncpy()¶

Strnicmp()¶

TagInArray()¶

ToLower()¶

ToUpper()¶

UDivMod32()¶

UDivMod64()¶

UMult32()¶

UMult64()¶

UnpackStructureTags()¶

VSNPrintf()¶

`AddNamedObject()`¶

`AllocateTagItems()`¶

`AllocNamedObjectA()`¶

`Amiga2Date()`¶

`ApplyTagChanges()`¶

`AttemptRemNamedObject()`¶

`CallHookPkt()`¶

`CheckDate()`¶

`CloneTagItems()`¶

`Date2Amiga()`¶

`FilterTagChanges()`¶

`FilterTagItems()`¶

`FindNamedObject()`¶

`FindTagItem()`¶

`FreeNamedObject()`¶

`FreeTagItems()`¶

`GetTagData()`¶

`GetUniqueID()`¶

`MapTags()`¶

`NamedObjectName()`¶

`NextTagItem()`¶

`PackBoolTags()`¶

`PackStructureTags()`¶

`RefreshTagItemClones()`¶

`ReleaseNamedObject()`¶

`RemNamedObject()`¶

`SDivMod32()`¶

`SDivMod64()`¶

`SMult32()`¶

`SMult64()`¶

`Stricmp()`¶

`Strncat()`¶

`Strncpy()`¶

`Strnicmp()`¶

`TagInArray()`¶

`ToLower()`¶

`ToUpper()`¶

`UDivMod32()`¶

`UDivMod64()`¶

`UMult32()`¶

`UMult64()`¶

`UnpackStructureTags()`¶

`VSNPrintf()`¶