Table of Contents
FASMLIB is portable general-purpose library for 32bit x86 assembly language.
One it's purpose is to rid assembly programmers of rewriting basic routines every time. FASMLIB provides many commonly-used routines. They are well tested, easy to use, and tend to prevent bugs in code.
Another purpose is to allow assembly programmers have single source working for multiple operation systems. FASMLIB wraps some most common routines of supported OSes, with same interface for all OSes. Thus all your code which uses FASMLIB can run under any supported platform. This multiplatform support is of course limited to x86 32bit processors. Currently win32 and linux platforms are supported.
FASMLIB is designed to allow people to use it easily with only pure assembly, without need for macros. But for FASM users, FASMLIB contains couple of optional high-level macros that can make it's usage easier.
FASMLIB is NOT designed to be fast. Simplicity of usage, bugproofnes, powerfulness and maintability are more important.
FASMLIB is designed to be both simple to use and powerful. This is often solved by having two versions of procedures, one simple for common use, and one powerful
Altough name may suggest FASMLIB is only for use with FASM (Flat Assembler), this is not true. FASMLIB currently has support for FASM, MASM, NASM and YASM. Support for more assemblers can be added on demand. This name is remnaint from time when it was FASM-only library. Currently I am considering renaming it to "LibASM" by version 1.
This chapter describes how to use FASMLIB. First, we will learn how to include it to your project, in various assemblers. Then, we will learn how your code should work with FASMLIB. Example code is in FASM, NASM and YASM compatible syntax.
To access FASMLIB from anywhere on your disk, you should set up envirnment variable "FASMLIB". It should point into directory where FASMLIB archive is unpacked.
Following is description how to set up persistent environment variable on supported platforms.
On win32. rightclick My Computer, select Properties - Advanced - Environment Variables, click New. Set Variable Name to "FASMLIB" and Variable Value to path to FASMLIB directory
On linux with bash. add following line to your ~/.bashrc file:
export FASMLIB=<path to fasmlib directory>
This chapter discusses specifics of using FASMLIB in various assemblers.
Users of FASM can include FASMLIB into their project directly by including it's sources. This is prefered method for FASM.
First you need to define target operating system, and include FASMLIB sources. To do it, add these lines to code section:
SYSTEM equ win32 ;SYSTEM equ linux include "%FASMLIB%/include/fasm/fasmlib-src"
Then you must set place for FASMLIB variables. For this, you use IncludeIData and IncludeUData macros.
IncludeIData defines initialized data. You can place this in any writable and readable place, prefereably into data section.
IncludeUData reserves space for uninitialized data. You should place this at the end of data section, so that unitialized data here won't be present in executable file, only reserved at header.
Example 2.1. win32 example:
format PE console include '%FASMINC%/win32ax.inc' .code SYSTEM EQU win32 include '%FASMLIB%/include/fasm/fasmlib-src.inc' start: <<- your code here ->> .data <<- your data here ->> IncludeIData IncludeUData .end start
Example 2.2. linux example:
format ELF executable entry start ;code segment readable executable SYSTEM equ linux include '%FASMLIB%/include/fasm/fasmlib-src.inc' start: <<- your code here ->> ;data segment readable writeable <<- your data here ->> IncludeIData IncludeUData
You can call FASMLIB procedures with near call
call mem.init
Arguments are pushed in reverse order. That means you call mem.copy(dest,src,size) with:
push [size] push [src] push [dest] call mem.copy
All arguments are dword-sized. That means, even if you are passing byte or word sized value, you must push it as dword
push dword 'a' push [stream] call stream.write.char
Qword (64bit) arguments are passed as two dwords
push 0 push dword [dist+4] ;push high order dword push dword [dist] ;push low order dword push [handle] call file.seek
Procedure always clears it's arguments from stack, not caller.
push [size] push [src] push [dest] call mem.copy ;no need for add esp, 3*4 here
Every procedure preserves EBX, ECX, ESI, EDI, EBP and DF.
Every procedure that doesn't return 64bit value preserves EDX too.
Every procedure returns error status in CF. If CF is set, error occured, and EAX contains error code. More on error handling in next chapter.
push 100h ;size of block call mem.alloc ;allocate block of memory jc error ;check error
Procedure returns dword (32 bit) value in EAX.
push 100h ;size of block call mem.alloc ;allocate block of memory jc error ;check error mov [block], eax ;save returned value
Procedure returns qword (64 bit) value in EDX:EAX.
push [handle] call file.tell ;call procedure which returns qword jc error ;check error mov dword [value], eax ;save low order dword of returned value mov dword [value+4], edx ;save high order dword of returned value
Procedure returns boolean value in ZF.
push 100h ;size of blocks to compare push [block2] ;pointer to block push [block1] ;pointer to another block call mem.cmp ;compare blocks jc error ;check error first! je same ;blocks are same jne different ;blocks are different
Function can also return overflow, or end-reached notice in OF
push 100h ;read 100h bytes from file push edi ;to buffer pointed by edi push [handle] ;from our file handle call fileio.read jc error ;check error first! jo EOF_reached ;file.read sets OF when end of file is reached
If function wants to return equal/greater/lesser state, it can use combination of ZF/OF/SF to setup flags for signed conditional jumps.
push 100h ;size of memory blocks push esi ;compare memory block pointed by esi push edi ;to memory block pointed by edi call mem.cmp ;compare memory blocks contents jc error jg edi_greater ;edi block is greater jl esi_greater ;esi block is greater (edi is lesser) je equal ;both blocks are equal
you can use all signed conditional jumps: je, jne, jg, jge, jl, jle, jng, jnge, jnl, jnle.
To include FASMLIB definitions to MASM project, add this line to your code segment:
%include @Environ(fasmlib)\\include\\masm\\fasmlib.inc
Now compile your file to MS-COFF file:
ml.exe /c /coff myfile.asm
Finally, you must link your project with FASMLIB library file. Library for MASM is "bin/fasmlib2.lib" in FASMLIB directory. You can refer to it using environment variable FASMLIB. This is example using MS link:
link /subsystem:console myfile.obj "%FASMLIB%\bin\fasmlib2.lib" kernel32.lib
Example 2.3.
.586 .model flat, stdcall option casemap:none ; case sensitive ;include FASMLIB headers %include @Environ(FASMLIB)\\include\\masm\\fasmlib.inc .data <<- your data here ->> .code start: <<- your code here ->> end start
You can call FASMLIB procedures with near call
call mem_init
Arguments are pushed in reverse order. That means you call mem.copy(dest,src,size) with:
push size push src push dest call mem_copy
All arguments are dword-sized. That means, even if you are passing byte or word sized value, you must push it as dword
push dword ptr 'a' push stream call stream_write_char
Qword (64bit) arguments are passed as two dwords
push 0 push dword ptr [dist+4] ;push high order dword push dword ptr [dist] ;push low order dword push handle call file_seek
Procedure always clears it's arguments from stack, not caller.
push size push src push dest call mem_copy ;no need for add esp, 3*4 here
Every procedure preserves EBX, ECX, ESI, EDI, EBP and DF.
Every procedure that doesn't return 64bit value preserves EDX too.
Every procedure returns error status in CF. If CF is set, error occured, and EAX contains error code. More on error handling in next chapter.
push 100h ;size of block call mem_alloc ;allocate block of memory jc error ;check error
Procedure returns dword (32 bit) value in EAX.
push 100h ;size of block call mem_alloc ;allocate block of memory jc error ;check error mov block, eax ;save returned value
Procedure returns qword (64 bit) value in EDX:EAX.
push handle call file_tell ;call procedure which returns qword jc error ;check error mov dword ptr [value], eax ;save low order dword of returned value mov dword ptr [value+4], edx ;save high order dword of returned value
Procedure returns boolean value in ZF.
push 100h ;size of blocks to compare push offset block2 ;pointer to block push offset block1 ;pointer to another block call mem_cmp ;compare blocks jc error ;check error first! je same ;blocks are same jne different ;blocks are different
Function can also return overflow, or end-reached notice in OF
push 100h ;read 100h bytes from file push edi ;to buffer pointed by edi push handle ;from our file handle call fileio_read jc error ;check error first! jo EOF_reached ;file.read sets OF when end of file is reached
If function wants to return equal/greater/lesser state, it can use combination of ZF/OF/SF to setup flags for signed conditional jumps.
push 100h ;size of memory blocks push esi ;compare memory block pointed by esi push edi ;to memory block pointed by edi call mem_cmp ;compare memory blocks contents jc error jg edi_greater ;edi block is greater jl esi_greater ;esi block is greater (edi is lesser) je equal ;both blocks are equal
you can use all signed conditional jumps: je, jne, jg, jge, jl, jle, jng, jnge, jnl, jnle.
To include FASMLIB definitions to NASM/YASM project, add this line to your source:
%include "%!FASMLIB/include/nasm/fasmlib.inc
Now compile your file to MS-COFF file:
nasm -f win32 myfile.asm
Finally, you must link your project with FASMLIB library file. Library file for NASM/YASM on win32 is "bin/fasmlib.lib" in FASMLIB directory. You can refer to it using environment variable FASMLIB. This is example using MS link:
link /subsystem:console myfile.obj "%FASMLIB%\bin\fasmlib.lib" kernel32.lib
Example 2.4.
myfile.asm:
;compile with: ; nasm -f win32 myfile.asm ;link with: (using MS link) ; link /entry:start /subsystem:console myfile.obj "%FASMLIB%/bin/fasmlib.lib" %include "%!FASMLIB/include/nasm/fasmlib.inc global _start [section .text] _start: <<- your code here ->> [section .data] <<- your data here ->>
To include FASMLIB definitions to NASM/YASM project, add this line to your source:
%include "%!FASMLIB/include/nasm/fasmlib.inc
Then compile your file to ELF object format:
nasm -f elf myfile.asm
or
yasm -f elf myfile.asm
Then you link it to executable: (bash)
ld myfile.obj $FASMLIB/bin/fasmlib.a -o myfile
Example 2.5.
myfile.asm:
;compile with: ; nasm -f elf myfile.asm ;link with: (in bash) ; ld -e _start myfile.o $FASMLIB/bin/fasmlib.a -o myfile %include "%!FASMLIB/include/nasm/fasmlib.inc global _start [section .text] _start: <<- your code here ->> [section .data] <<- your data here ->>
You can call FASMLIB procedures with near call
call mem.init
Arguments are pushed in reverse order. That means you call mem.copy(dest,src,size) with:
push [size] push [src] push [dest] call mem.copy
All arguments are dword-sized. That means, even if you are passing byte or word sized value, you must push it as dword
push dword 'a' push [stream] call stream.write.char
Qword (64bit) arguments are passed as two dwords
push 0 push dword [dist+4] ;push high order dword push dword [dist] ;push low order dword push [handle] call file.seek
Procedure always clears it's arguments from stack, not caller.
push [size] push [src] push [dest] call mem.copy ;no need for add esp, 3*4 here
Every procedure preserves EBX, ECX, ESI, EDI, EBP and DF.
Every procedure that doesn't return 64bit value preserves EDX too.
Every procedure returns error status in CF. If CF is set, error occured, and EAX contains error code. More on error handling in next chapter.
push 100h ;size of block call mem.alloc ;allocate block of memory jc error ;check error
Procedure returns dword (32 bit) value in EAX.
push 100h ;size of block call mem.alloc ;allocate block of memory jc error ;check error mov [block], eax ;save returned value
Procedure returns qword (64 bit) value in EDX:EAX.
push [handle] call file.tell ;call procedure which returns qword jc error ;check error mov dword [value], eax ;save low order dword of returned value mov dword [value+4], edx ;save high order dword of returned value
Procedure returns boolean value in ZF.
push 100h ;size of blocks to compare push [block2] ;pointer to block push [block1] ;pointer to another block call mem.cmp ;compare blocks jc error ;check error first! je same ;blocks are same jne different ;blocks are different
Function can also return overflow, or end-reached notice in OF
push 100h ;read 100h bytes from file push edi ;to buffer pointed by edi push [handle] ;from our file handle call fileio.read jc error ;check error first! jo EOF_reached ;file.read sets OF when end of file is reached
If function wants to return equal/greater/lesser state, it can use combination of ZF/OF/SF to setup flags for signed conditional jumps.
push 100h ;size of memory blocks push esi ;compare memory block pointed by esi push edi ;to memory block pointed by edi call mem.cmp ;compare memory blocks contents jc error jg edi_greater ;edi block is greater jl esi_greater ;esi block is greater (edi is lesser) je equal ;both blocks are equal
you can use all signed conditional jumps: je, jne, jg, jge, jl, jle, jng, jnge, jnl, jnle.
Every procedure returns error state in CF:
call file.open jc error
If CF=1 after returning from FASMLIB procedure, it means some error happened. In such case procedure hasn't completed it's task, and didn't return anything (most of times). You should check CF after !every! procedure, even if it's unlikely that function will return some error.
push [handle] call file.close jc error ;this can help catching bad handle
When procedure returns with CF=1, then EAX contains error code. Error code is symbolic constant. Name of these constants start with ERR_. Always use their symbolic name, not direct value, because it can change.
call file.open jc error_open ... error_open: cmp eax, ERR_FILE_NOT_FOUND je file_not_found jmp error
When procedure that returns 64bit value in EDX:EAX returns error, value of EDX is undefined
List of errors procedure can return is in description of every procedure. There can be also one or more + followed by name of other procedure. This means that other procedure is called internally, and it's return values can be returned aswell.
When you recieve error, you can handle it in way you like. You don't have to do anything extra for this, just check error value and continue execution. For example after getting ERR_FILE_NOT_FOUND from file.open, you can ask user to enter new file path etc.
call file.open jnc file_opened cmp eax, ERR_FILE_NOT_FOUND je enter_new_file_name jmp error_file_open file_opened:
Typical way to handle error is to release resources (close files, free memory etc.), then display error message, uninitialize FASMLIB and quit. To get error message from FASMLIB error code, use err.text. To uninitialize FASMLIB in case of unexpected error, use fasmlib.shutdown.To This is example of error hander:
_err_format db 10, "Error: %s!", 10, 0 ... error: ;EAX = error message associated with error code in EAX push eax call err.text ;write error message push eax push _err_format call stderr.write.format ;unintialize FASMLIB call fasmlib.uninit ;end program with exit code 1 push 1 call process.exit
These are very basic procedures of FASMLIB, and should be always used.
Initializes all modules in FASMLIB. In current version, it calls mem.init and stdstream.init .
Uninitializes all modules in FASMLIB. In current version, it calls mem.uninit and stdstream.uninit .
Uninitializes all modules in FASMLIB. In current version, it calls mem.uninit and stdstream.uninit . Procedure is meant to be used in error handlers only: it tries to uninitialize as much as possible, even if some error hapens. Use fasmlib.uninit for normal uninitialization.
FASMLIB provides library for working with strings. These are static strings, placed in user defined buffer. Strings are in ASCII format, eg. one byte per character. Strings are terminated by zero byte.
Common problem with such strings is that their maximal allowed size is limited. If someone tries to write string longer than buffer size into such buffer, it overflows and overwrites following data. This is most common method for exploiting software.
To prevent this happening, FASMLIB procedures always take pointer to string buffer and size of buffer. If you wish to disable buffer size limitation for particular string, just pass -1 (0xFFFFFFFF) as buffer size.
FASMLIB never reads beyond given buffer size. If source string is not terminated (no zero byte inside buffer), only part in buffer is taken as actual string.
Whenever result of string operation should overflow buffer, only portion of result which fits into buffer is written, and error ERR_BUFFER_FULL is returned.
This behavior allows limited working with constant-length and non-zero-terminated strings (for example section name in PE file header). It can be done by ignoring ERR_BUFFER_FULL error.
These are procedures that operate on strings.
stringPointer to destination string.
buflenSize of destination string buffer.
charCharacter which we are appending to string. Only low order byte of this dword is used, rest is ignored.
ERR_BUFFER_OVERFLOWDestination buffer is not big enough. Only first destlen bytes of string were written. String in destination buffer is NOT zero terminated.
ERR_ZERO_VALUEchar=0
ERR_ZERO_SIZEstrlen=0
+str.lendestPointer to destination string, the one into which we insert.
destlenSize of destination string buffer.
srcPointer to source string, the one we are inserting.
srclenSize of source string buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
posPosition in destination string where we are insrting. Position 0 corresponds to beginning of string, before first character.
ERR_OUT_OF_RANGEPosition is outside of destination string, pos > strlen(dest). You are trying to insert behind end of string.
ERR_BUFFER_OVERFLOWDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated.
ERR_ZERO_SIZEdestlen=0 or srclen=0.
+str.len+mem.copystringPointer to destination string, the one into which we insert.
buflenSize of destination string buffer.
charCharacter which we are inserting to string. Only low order byte of this dword is used, rest is ignored.
posPosition in destination string where we are insrting. Position 0 corresponds to beginning of string, before first character.
ERR_OUT_OF_RANGEPosition is outside of destination string, pos > strlen(dest). You are trying to insert behind end of string.
ERR_BUFFER_OVERFLOWDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated.
ERR_ZERO_SIZEdestlen=0 or srclen=0
+str.insdestPointer to destination string buffer.
destlenSize of destination string buffer.
srcPointer to source string.
srclenSize of source string buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
indexPosition in source string from where we start extracting. Position 0 corresponds to first character, included.
lenLength of string we want to extract.
CF set on error, otherwise EAX = dest, and OF set if string overlapped and less than len characters were copied
ERR_OUT_OF_RANGEPosition is outside of destination string, pos >= strlen(dest). You are trying to extract string from behind end of source string.
ERR_BUFFER_OVERFLOWDestination buffer is not big enough. Only first destlen bytes of extracted string were written. String in destination buffer is NOT zero terminated.
ERR_ZERO_SIZEdestlen=0 or srclen=0.
+str.len+mem.copyConverts characters in string to lowcase. Works only for ASCII characters (a-z and A-Z), no other encodings are supported.
Converts characters in string to upcase. Works only for ASCII characters (a-z and A-Z), no other encodings are supported.
Returns length of string. If string isn't zero-terminated within it's buffer, size of buffer is returned, and OF is set.
stringPointer to string.
buflenSize of string buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
Compares two strings, whether they are identical (case sensitive). If strings are different, tells which is greater (by comparing first different character). This is useful for sorting strings.
str1Pointer to first string.
str1lenSize of buffer of first string. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
str2Pointer to second string.
str2lenSize of buffer of second string. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
CF set on error, otherwise {flagscmp:flags set for signed conditional jumps}, and if ZF=0, then EAX = offset where strings differ
Compares two strings, whether they are identical. This procedure is case-insensitive for ASCII characters (a-z and A-Z). Other encodings are not supported. If strings are different, tells which is greater (by comparing first different character). This is useful for sorting strings.
str1Pointer to first string.
str1lenSize of buffer of first string. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
str2Pointer to second string.
str2lenSize of buffer of second string. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
CF set on error, otherwise {flagscmp:flags set for signed conditional jumps}, and if ZF=0, then EAX = offset where strings differ
stringPointer to string in which we are searching.
buflenSize of buffer of string in which we are searching. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
patternPointer to pattern string.
patlenSize of pattern string buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
stringPointer to string in which we are searching.
buflenSize of buffer of string in which we are searching. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
charCharacter which we are looking for.
FASMLIB provides several routines for conversion between binary formats and their string representations.
Currently supported are byte/word/dword binary numbers, and signed/unsigned decimal/hexadecimal ASCII string formats.
These procedures convert number to decimal string representation.
Converts unsigned byte (8bit) value to decimal string. For more options use extconv.b_dec .
Converts unsigned word (16bit) value to decimal string. For more options use extconv.w_dec .
Converts unsigned dword (32bit) value to decimal string. For more options use extconv.d_dec .
Converts unsigned qword (64bit) value to decimal string. For more options use extconv.q_dec .
Converts signed byte (8bit) value to decimal string. For more options use extconv.ib_dec .
Converts signed word (16bit) value to decimal string. For more options use extconv.iw_dec .
Converts signed dword (32bit) value to decimal string. For more options use extconv.id_dec .
Converts signed qword (64bit) value to decimal string. For more options use extconv.iq_dec .
Converts unsigned byte (8bit) value to decimal string. Supports padding of output with spaces or zeroes. For simpler version see conv.b_dec .
destPointer to destination string buffer.
destlenSize of destination string buffer.
valueByte value to convert. Only low order byte of this dword is used, rest is ignored.
paddingType of padding: type 0 is no padding, type 1 is prepending with spaces, type 2 is prepending with leading zeroes.
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
lenPointer to dword variable, which will on return hold length of output (terminating zero not included). Ignored if zero.
ERR_BUFFER_FULLDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated. Variable pointed by len contains destlen
ERR_ZERO_SIZEdestlen=0. Variable pointed by len is set to 0.
ERR_INVALID_MODEpadding > 2. Variable pointed by len is set to 0.
Converts unsigned word (16bit) value to decimal string. Supports padding of output with spaces or zeroes. For simpler version see conv.w_dec .
destPointer to destination string buffer.
destlenSize of destination string buffer.
valueWord value to convert. Only low order word of this dword is used, rest is ignored.
paddingType of padding: type 0 is no padding, type 1 is prepending with spaces, type 2 is prepending with leading zeroes.
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
lenPointer to dword variable, which will on return hold length of output (terminating zero not included). Ignored if zero.
ERR_BUFFER_FULLDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated. Variable pointed by len contains destlen
ERR_ZERO_SIZEdestlen=0. Variable pointed by len is set to 0.
ERR_INVALID_MODEpadding > 2. Variable pointed by len is set to 0.
Converts unsigned dword (32bit) value to decimal string. Supports padding of output with spaces or zeroes. For simpler version see conv.d_dec .
destPointer to destination string buffer.
destlenSize of destination string buffer.
valueDword value to convert.
paddingType of padding: type 0 is no padding, type 1 is prepending with spaces, type 2 is prepending with leading zeroes.
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
lenPointer to dword variable, which will on return hold length of output (terminating zero not included). Ignored if zero.
ERR_BUFFER_FULLDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated. Variable pointed by len contains destlen
ERR_ZERO_SIZEdestlen=0. Variable pointed by len is set to 0.
ERR_INVALID_MODEpadding > 2. Variable pointed by len is set to 0.
Converts unsigned qword (64bit) value to decimal string. Supports padding of output with spaces or zeroes. For simpler version see conv.q_dec .
destPointer to destination string buffer.
destlenSize of destination string buffer.
valuelowLow order dword of value to convert.
valuehighHigh order dword of value to convert.
paddingType of padding: type 0 is no padding, type 1 is prepending with spaces, type 2 is prepending with leading zeroes.
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
lenPointer to dword variable, which will on return hold length of output (terminating zero not included). Ignored if zero.
ERR_BUFFER_FULLDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated. Variable pointed by len contains destlen
ERR_ZERO_SIZEdestlen=0. Variable pointed by len is set to 0.
ERR_INVALID_MODEpadding > 2. Variable pointed by len is set to 0.
Converts signed byte (8bit) value to decimal string. Supports padding of output with spaces or zeroes, and explicit plus sign. For simpler version see conv.ib_dec .
destPointer to destination string buffer.
destlenSize of destination string buffer.
valueByte value to convert. Only low order byte of this dword is used, rest is ignored.
paddingType of padding: Type 0 is no padding. Type 1 is prepending with spaces, and sign counts into padding size. Type 2 is prepending with leading zeroes. In this type padlen specifies number digits displayed. One more character is always printed as sign (' ', '+' or '-').
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
plusSet to 1 if you want to display plus sign on positive numbers.
lenPointer to dword variable, which will on return hold length of output (terminating zero not included). Ignored if zero.
ERR_BUFFER_FULLDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated. Variable pointed by len contains destlen
ERR_INVALID_MODEpadding > 2, or plus > 1
ERR_ZERO_SIZEdestlen=0. Variable pointed by len is set to 0. Variable pointed by len is set to 0.
Converts signed word (16bit) value to decimal string. Supports padding of output with spaces or zeroes, and explicit plus sign. For simpler version see conv.iw_dec .
destPointer to destination string buffer.
destlenSize of destination string buffer.
valueWord value to convert. Only low order word of this dword is used, rest is ignored.
paddingType of padding: Type 0 is no padding. Type 1 is prepending with spaces, and sign counts into padding size. Type 2 is prepending with leading zeroes. In this type padlen specifies number digits displayed. One more character is always printed as sign (' ', '+' or '-').
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
plusSet to 1 if you want to display plus sign on positive numbers.
lenPointer to dword variable, which will on return hold length of output (terminating zero not included). Ignored if zero.
ERR_BUFFER_FULLDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated. Variable pointed by len contains destlen
ERR_ZERO_SIZEdestlen=0. Variable pointed by len is set to 0.
ERR_INVALID_MODEpadding > 2, or plus > 1 Variable pointed by len is set to 0.
Converts signed dword (32bit) value to decimal string. Supports padding of output with spaces or zeroes, and explicit plus sign. For simpler version see conv.id_dec .
destPointer to destination string buffer.
destlenSize of destination string buffer.
valueDword value to convert.
paddingType of padding: Type 0 is no padding. Type 1 is prepending with spaces, and sign counts into padding size. Type 2 is prepending with leading zeroes. In this type padlen specifies number digits displayed. One more character is always printed as sign (' ', '+' or '-').
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
plusSet to 1 if you want to display plus sign on positive numbers.
lenPointer to dword variable, which will on return hold length of output (terminating zero not included). Ignored if zero.
ERR_BUFFER_FULLDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated. Variable pointed by len contains destlen
ERR_ZERO_SIZEdestlen=0. Variable pointed by len is set to 0.
ERR_INVALID_MODEpadding > 2, or plus > 1 Variable pointed by len is set to 0.
Converts signed qword (64bit) value to decimal string. Supports padding of output with spaces or zeroes, and explicit plus sign. For simpler version see conv.iq_dec .
destPointer to destination string buffer.
destlenSize of destination string buffer.
valuelowLow order dword of value to convert.
valuehighHigh order dword of value to convert.
paddingType of padding: Type 0 is no padding. Type 1 is prepending with spaces, and sign counts into padding size. Type 2 is prepending with leading zeroes. In this type padlen specifies number digits displayed. One more character is always printed as sign (' ', '+' or '-').
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
plusSet to 1 if you want to display plus sign on positive numbers.
lenPointer to dword variable, which will on return hold length of output (terminating zero not included). Ignored if zero.
ERR_BUFFER_FULLDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated. Variable pointed by len contains destlen
ERR_ZERO_SIZEdestlen=0. Variable pointed by len is set to 0.
ERR_INVALID_MODEpadding > 2, or plus > 1 Variable pointed by len is set to 0.
These procedures convert number from decimal string representation.
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
ERR_NOT_DECIMALFirst character of string is not decimal digit.
ERR_OUT_OF_RANGEValue is > 255
ERR_ZERO_SIZEstrlen=0
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
ERR_NOT_DECIMALFirst character of string is not decimal digit.
ERR_OUT_OF_RANGEValue is > 65535
ERR_ZERO_SIZEstrlen=0
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
ERR_NOT_DECIMALFirst character of string is not decimal digit.
ERR_OUT_OF_RANGEValue is > 4294967295.
ERR_ZERO_SIZEstrlen=0
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
ERR_NOT_DECIMALFirst character of string is not decimal digit.
ERR_OUT_OF_RANGEValue is > 18446744073709551615.
ERR_ZERO_SIZEstrlen=0
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
ERR_NOT_DECIMALFirst character of string is not decimal digit.
ERR_OUT_OF_RANGEValue is greater than 127 or lesser than -128.
ERR_ZERO_SIZEstrlen=0
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
ERR_NOT_DECIMALFirst character of string is not decimal digit.
ERR_OUT_OF_RANGEValue is greater than 65535 or lesser than -65536.
ERR_ZERO_SIZEstrlen=0
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
ERR_NOT_DECIMALFirst character of string is not decimal digit.
ERR_OUT_OF_RANGEValue is greater than 2147483647 or lesser than -2147483648.
ERR_ZERO_SIZEstrlen=0
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
ERR_NOT_DECIMALFirst character of string is not decimal digit.
ERR_OUT_OF_RANGEValue is greater than 9223372036854775807 or lesser than -9223372036854775808.
ERR_ZERO_SIZEstrlen=0
Converts decimal string to unsigned byte (8bit) value. This is extended version, for simpler version see conv.dec_b .
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
lenPointer to dword variable, which will on return hold number of converted characters. Ignored if zero.
Converts decimal string to unsigned word (16bit) value. This is extended version, for simpler version see conv.dec_w .
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
lenPointer to dword variable, which will on return hold number of converted characters. Ignored if zero.
Converts decimal string to unsigned dword (32bit) value. This is extended version, for simpler version see conv.dec_d .
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
lenPointer to dword variable, which will on return hold number of converted characters. Ignored if zero.
Converts decimal string to unsigned qword (64bit) value. This is extended version, for simpler version see conv.dec_q .
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
lenPointer to dword variable, which will on return hold number of converted characters. Ignored if zero.
strlen
Converts decimal string to signed byte (8bit) value. This is extended version, for simpler version see conv.dec_ib .
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
allowplusIf 1, explicit "+" sign before number is allowed.
lenPointer to dword variable, which will on return hold number of converted characters. Ignored if zero.
Converts decimal string to signed word (16bit) value. This is extended version, for simpler version see conv.dec_iw .
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
allowplusIf 1, explicit "+" sign before number is allowed.
lenPointer to dword variable, which will on return hold number of converted characters. Ignored if zero.
Converts decimal string to signed dword (32bit) value. This is extended version, for simpler version see conv.dec_id .
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
allowplusIf 1, explicit "+" sign before number is allowed.
lenPointer to dword variable, which will on return hold number of converted characters. Ignored if zero.
Converts decimal string to signed qword (64bit) value. This is extended version, for simpler version see conv.dec_iq .
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
allowplusIf 1, explicit "+" sign before number is allowed.
lenPointer to dword variable, which will on return hold number of converted characters. Ignored if zero.
strlen
Following procedures convert to/from hexdecimal string representation.
Converts unsigned byte (8bit) value to hexadecimal string. For more options use extconv.b_hex .
Converts unsigned word (16bit) value to hexadecimal string. For more options use extconv.w_hex .
Converts unsigned dword (32bit) value to hexadecimal string. For more options use extconv.d_hex .
Converts unsigned qword (64bit) value to hexadecimal string. For more options use extconv.q_hex .
Converts signed byte (8bit) value to hexadecimal string. For more options use extconv.ib_hex .
Converts signed word (16bit) value to hexadecimal string. For more options use extconv.iw_hex .
Converts signed dword (32bit) value to decimal string. For more options use extconv.id_hex .
Converts signed qword (64bit) value to decimal string. For more options use extconv.iq_hex .
Converts unsigned byte (8bit) value to hex string. Supports padding of output with spaces or zeroes. For simpler version see conv.b_hex .
destPointer to destination string buffer.
destlenSize of destination string buffer.
valueByte value to convert. Only low order byte of this dword is used, rest is ignored.
paddingType of padding: type 0 is no padding, type 1 is prepending with spaces, type 2 is prepending with leading zeroes.
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
lenPointer to dword variable, which will on return hold length of output (terminating zero not included). Ignored if zero.
ERR_BUFFER_FULLDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated. Variable pointed by len contains destlen
ERR_ZERO_SIZEdestlen=0. Variable pointed by len is set to 0.
ERR_INVALID_MODEpadding > 2. Variable pointed by len is set to 0.
Converts unsigned word (16bit) value to hex string. Supports padding of output with spaces or zeroes. For simpler version see conv.w_hex .
destPointer to destination string buffer.
destlenSize of destination string buffer.
valueWord value to convert. Only low order word of this dword is used, rest is ignored.
paddingType of padding: type 0 is no padding, type 1 is prepending with spaces, type 2 is prepending with leading zeroes.
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
lenPointer to dword variable, which will on return hold length of output (terminating zero not included). Ignored if zero.
ERR_BUFFER_FULLDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated. Variable pointed by len contains destlen
ERR_ZERO_SIZEdestlen=0. Variable pointed by len is set to 0.
ERR_INVALID_MODEpadding > 2. Variable pointed by len is set to 0.
Converts unsigned dword (32bit) value to hex string. Supports padding of output with spaces or zeroes. For simpler version see conv.d_hex .
destPointer to destination string buffer.
destlenSize of destination string buffer.
valueDword value to convert.
paddingType of padding: type 0 is no padding, type 1 is prepending with spaces, type 2 is prepending with leading zeroes.
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
lenPointer to dword variable, which will on return hold length of output (terminating zero not included). Ignored if zero.
ERR_BUFFER_FULLDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated. Variable pointed by len contains destlen
ERR_ZERO_SIZEdestlen=0. Variable pointed by len is set to 0.
ERR_INVALID_MODEpadding > 2. Variable pointed by len is set to 0.
Converts unsigned qword (64bit) value to hex string. Supports padding of output with spaces or zeroes. For simpler version see conv.q_hex .
destPointer to destination string buffer.
destlenSize of destination string buffer.
valuelowLow order dword of value to convert.
valuehighHigh order dword of value to convert.
paddingType of padding: type 0 is no padding, type 1 is prepending with spaces, type 2 is prepending with leading zeroes.
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
lenPointer to dword variable, which will on return hold length of output (terminating zero not included). Ignored if zero.
ERR_BUFFER_FULLDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated. Variable pointed by len contains destlen
ERR_ZERO_SIZEdestlen=0. Variable pointed by len is set to 0.
ERR_INVALID_MODEpadding > 2. Variable pointed by len is set to 0.
Converts signed byte (8bit) value to hex string. Supports padding of output with spaces or zeroes, and explicit plus sign. For simpler version see conv.ib_hex .
destPointer to destination string buffer.
destlenSize of destination string buffer.
valueByte value to convert. Only low order byte of this dword is used, rest is ignored.
paddingType of padding: Type 0 is no padding. Type 1 is prepending with spaces, and sign counts into padding size. Type 2 is prepending with leading zeroes. In this type padlen specifies number digits displayed. One more character is always printed as sign (' ', '+' or '-').
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
plusSet to 1 if you want to display plus sign on positive numbers.
lenPointer to dword variable, which will on return hold length of output (terminating zero not included). Ignored if zero.
ERR_BUFFER_FULLDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated. Variable pointed by len contains destlen
ERR_ZERO_SIZEdestlen=0. Variable pointed by len is set to 0.
ERR_INVALID_MODEpadding > 2, or plus > 1 Variable pointed by len is set to 0.
Converts signed word (16bit) value to hex string. Supports padding of output with spaces or zeroes, and explicit plus sign. For simpler version see conv.iw_hex .
destPointer to destination string buffer.
destlenSize of destination string buffer.
valueWord value to convert. Only low order word of this dword is used, rest is ignored.
paddingType of padding: Type 0 is no padding. Type 1 is prepending with spaces, and sign counts into padding size. Type 2 is prepending with leading zeroes. In this type padlen specifies number of digits displayed. One more character is always printed as sign (' ', '+' or '-').
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
plusSet to 1 if you want to display plus sign on positive numbers.
lenPointer to dword variable, which will on return hold length of output (terminating zero not included). Ignored if zero.
ERR_BUFFER_FULLDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated. Variable pointed by len contains destlen
ERR_ZERO_SIZEdestlen=0. Variable pointed by len is set to 0.
ERR_INVALID_MODEpadding > 2, or plus > 1 Variable pointed by len is set to 0.
Converts signed dword (32bit) value to hex string. Supports padding of output with spaces or zeroes, and explicit plus sign. For simpler version see conv.id_hex .
destPointer to destination string buffer.
destlenSize of destination string buffer.
valueDword value to convert.
paddingType of padding: Type 0 is no padding. Type 1 is prepending with spaces, and sign counts into padding size. Type 2 is prepending with leading zeroes. In this type padlen specifies number digits displayed. One more character is always printed as sign (' ', '+' or '-').
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
plusSet to 1 if you want to display plus sign on positive numbers.
lenPointer to dword variable, which will on return hold length of output (terminating zero not included). Ignored if zero.
ERR_BUFFER_FULLDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated. Variable pointed by len contains destlen
ERR_ZERO_SIZEdestlen=0. Variable pointed by len is set to 0.
ERR_INVALID_MODEpadding > 2, or plus > 1 Variable pointed by len is set to 0.
Converts signed qword (64bit) value to hex string. Supports padding of output with spaces or zeroes, and explicit plus sign. For simpler version see conv.iq_hex .
destPointer to destination string buffer.
destlenSize of destination string buffer.
valuelowLow order dword of value to convert.
valuehighHigh order dword of value to convert.
paddingType of padding: Type 0 is no padding. Type 1 is prepending with spaces, and sign counts into padding size. Type 2 is prepending with leading zeroes. In this type padlen specifies number digits displayed. One more character is always printed as sign (' ', '+' or '-').
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
plusSet to 1 if you want to display plus sign on positive numbers.
lenPointer to dword variable, which will on return hold length of output (terminating zero not included). Ignored if zero.
ERR_BUFFER_FULLDestination buffer is not big enough. Only first destlen bytes of resulting string were written. String in destination buffer is NOT zero terminated. Variable pointed by len contains destlen
ERR_ZERO_SIZEdestlen=0. Variable pointed by len is set to 0.
ERR_INVALID_MODEpadding > 2, or plus > 1 Variable pointed by len is set to 0.
Following procedures convert to/from hexdecimal string representation.
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
ERR_NOT_HEXADECIMALFirst character of string is not hexadecimal digit.
ERR_OUT_OF_RANGEValue is > FF
ERR_ZERO_SIZEstrlen=0
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
ERR_NOT_HEXADECIMALFirst character of string is not hexadecimal digit.
ERR_OUT_OF_RANGEValue is > FFFF
ERR_ZERO_SIZEstrlen=0
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
ERR_NOT_HEXADECIMALFirst character of string is not hexadecimal digit.
ERR_OUT_OF_RANGEValue is > FFFFFFFF
ERR_ZERO_SIZEstrlen=0
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
ERR_NOT_HEXADECIMALFirst character of string is not hexadecimal digit.
ERR_OUT_OF_RANGEValue is > FFFFFFFFFFFFFFFF
ERR_ZERO_SIZEstrlen=0
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
ERR_NOT_HEXADECIMALFirst character of string is not hexadecimal digit.
ERR_OUT_OF_RANGEValue is lesser than -80 or greater than 7F.
ERR_ZERO_SIZEstrlen=0
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
ERR_NOT_HEXADECIMALFirst character of string is not hexadecimal digit.
ERR_OUT_OF_RANGEValue is lesser than -8000 or greater than 7FFF.
ERR_ZERO_SIZEstrlen=0
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
ERR_NOT_HEXADECIMALFirst character of string is not hexadecimal digit.
ERR_OUT_OF_RANGEValue is lesser than -80000000 or greater than 7FFFFFFF.
ERR_ZERO_SIZEstrlen=0
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
ERR_NOT_HEXADECIMALFirst character of string is not hexadecimal digit.
ERR_OUT_OF_RANGEValue is lesser than -8000000000000000 or greater than 7FFFFFFFFFFFFFFF.
ERR_ZERO_SIZEstrlen=0
Converts hexadecimal string to unsigned byte (8bit) value. This is extended version, for simpler version see conv.hex_b .
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
lenPointer to dword variable, which will on return hold number of converted characters. Ignored if zero.
Converts hexadecimal string to unsigned word (16bit) value. This is extended version, for simpler version see conv.hex_w .
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
lenPointer to dword variable, which will on return hold number of converted characters. Ignored if zero.
Converts hexadecimal string to unsigned dword (32bit) value. This is extended version, for simpler version see conv.hex_d .
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
lenPointer to dword variable, which will on return hold number of converted characters. Ignored if zero.
Converts hexadecimal string to unsigned qword (64bit) value. This is extended version, for simpler version see conv.hex_q .
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
lenPointer to dword variable, which will on return hold number of converted characters. Ignored if zero.
strlen
Converts hexadecimal string to signed byte (8bit) value. This is extended version, for simpler version see conv.hex_ib .
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
allowplusIf 1, explicit "+" sign before number is allowed.
lenPointer to dword variable, which will on return hold number of converted characters. Ignored if zero.
Converts hexadecimal string to signed word (16bit) value. This is extended version, for simpler version see conv.hex_iw .
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
allowplusIf 1, explicit "+" sign before number is allowed.
lenPointer to dword variable, which will on return hold number of converted characters. Ignored if zero.
Converts hexadecimal string to signed dword (32bit) value. This is extended version, for simpler version see conv.hex_id .
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
allowplusIf 1, explicit "+" sign before number is allowed.
lenPointer to dword variable, which will on return hold number of converted characters. Ignored if zero.
Converts hexadecimal string to signed qword (64bit) value. This is extended version, for simpler version see conv.hex_iq .
stringPointer to string to convert.
buflenSize of string's buffer. You can set this to -1 (FFFFFFFFh) if string is quaranteed to be properly zero-terminated.
allowplusIf 1, explicit "+" sign before number is allowed.
lenPointer to dword variable, which will on return hold number of converted characters. Ignored if zero.
strlen
FASMLIB memory management provides you basic heap functions, like allocation, rellocation, getting size of block and releasing allocated block. Additionally, it provides functions to copy, fill, compare, and search blocks of memory. There is extensive checking for invalid pointers, invalid size and heap corruption in the code.
Functions working with memory allocation require you to initialize memory management before they can be used. After you are done with using these function, you should uninitialize memory management. During uninitialization, heap corruption and memory leaks are checked.
If OS provides heap management (win32) then this one is used. If OS doesn't provide heap management (linux) then FASMLIB uses it's own heap manager.
Following are procedures for manipulation with static memory.
Copies contents block of memory of given size to another place. Supports overlapped copy (like "memmove" in C).
Compares contents of two blocks of memory. If they are different, returns offset of position where they are different. Additionally it says which block contents "is bigger", useful for sorting.
block1Pointer to beginning of first memory block
block2Pointer to beginning of second memory block
sizeNumber of bytes to compare
Finds first occurence of given block of memory in another block of memory. Uses fast Horspool algorithm.
blockPointer to block in which we will search.
blocksizeSize of block in which we search.
patternPointer to pattern which we are looking for.
patternsizeSize of pattern block.
CF = 1 on error, otherwise ZF = 1 if not found, otherwise EAX = offset (not pointer) in block, where the pattern was found
Heap is a standard way to provide flexible memory allocations. It allows you to easily allocate blocks of memory, resize them, and release them when they are no longer needed.
This is list of FASMLIB procedures for manipulation with heap.
Initializes FASMLIB memory managent. You need to call this procedure to use any of following procedures: mem.alloc , mem.alloc0 , mem.realloc , mem.realloc0 , mem.free , mem.size .
ERR_OUT_OF_MEMNot enough memory
ERR_UNKNOWNSystem returned error that wasn't translated to FASMLIB error. You can contact author about this, and translation can be added.
+mem.alloc_heapOnly on platforms where FASMLIB heap manager is used.
Unitializes FASMLIB memory managent. When module is not initialized, you cannot use following procedures: mem.alloc , mem.alloc0 , mem.realloc , mem.realloc0 , mem.free , mem.size . This procedure also checks for heap corruption and memory leaks .
ERR_MEMORY_LEAKYou've got a memory leak . Check all places where you call mem.alloc or mem.alloc0 , whether you always release allocated block with mem.free . Also check if you didn't forget to uninitialize standard streams prior to calling this procedure.
ERR_HEAP_CORRUPTHeap is corrupted . You was writing to memory outside of allocated block.
ERR_MODULE_NOT_INITIALIZEDModule is not initialized. Initialize module with mem.init first.
ERR_UNKNOWNSystem returned error that wasn't translated to FASMLIB error. You can contact author about this, and translation can be added.
+mem.free_heapOnly on platforms where FASMLIB heap manager is used
ERR_OUT_OF_MEMNot enough memory
ERR_ZERO_SIZEsize = 0
ERR_OUT_OF_RANGEsize is negative (or larger than 7FFFFFFFh if viewed as unsigned)
ERR_HEAP_CORRUPTHeap is corrupted . You was writing to memory outside of allocated block.
ERR_MODULE_NOT_INITIALIZEDModule is not initialized. Initialize module with mem.init to use this procedure.
ERR_UNKNOWNSystem returned error that wasn't translated to FASMLIB error. You can contact author about this, and translation can be added.
+mem.realloc_heapOnly on platforms where FASMLIB heap manager is used.
ERR_OUT_OF_MEMNot enough memory
ERR_ZERO_SIZEsize = 0
ERR_OUT_OF_RANGEsize is negative (or larger than 7FFFFFFFh if viewed as unsigned)
ERR_HEAP_CORRUPTHeap is corrupted . You was writing to memory outside of allocated block.
ERR_MODULE_NOT_INITIALIZEDModule is not initialized. Initialize module with mem.init to use this procedure.
ERR_UNKNOWNSystem returned error that wasn't translated to FASMLIB error. You can contact author about this, and translation can be added.
+mem.alloc+mem.fillReleases allocated block of memory returned from mem.alloc , mem.alloc0 , mem.realloc , or mem.realloc0 .
blockptrPointer to allocated memory block. This must be same pointer as returned from allocation function, pointer into block is not enough.
ERR_INVALID_POINTERBlockptr is not a valid allocated block pointer. This could also mean heap corruption , these two cases cannot be properly distinguished.
ERR_HEAP_CORRUPTHeap is corrupted . You was writing to memory outside of allocated block.
ERR_MODULE_NOT_INITIALIZEDModule is not initialized. Initialize module with mem.init to use this procedure.
ERR_UNKNOWNSystem returned error that wasn't translated to FASMLIB error. You can contact author about this, and translation can be added.
Rellocates (resizes) block of memory returned from mem.alloc , mem.alloc0 , mem.realloc , or mem.realloc0 . Block can be moved during this process, so you need to update pointer(s) to it. Contents of block are preserved. If block is enlarging, contents of added space are unknown, use mem.realloc0 to have them zeroed.
blockptrPointer to block to relocate. This must be same pointer as returned from allocation function, pointer into block is not enough.
newsizeNew size of block, in bytes
ERR_INVALID_POINTERBlockptr is not a valid allocated block pointer. This could also mean heap corruption , these two cases cannot be properly distinguished.
ERR_OUT_OF_MEMNot enough memory
ERR_ZERO_SIZEsize = 0
ERR_OUT_OF_RANGEsize is negative (or larger than 7FFFFFFFh if viewed as unsigned)
ERR_HEAP_CORRUPTHeap is corrupted . You was writing to memory outside of allocated block.
ERR_MODULE_NOT_INITIALIZEDModule is not initialized. Initialize module with mem.init to use this procedure.
ERR_UNKNOWNSystem returned error that wasn't translated to FASMLIB error. You can contact author about this, and translation can be added.
+mem.realloc_heapOnly on platforms where FASMLIB heap manager is used.
Rellocates (resizes) block of memory. Block can be moved during this process, so you need to update pointer(s) to it. Contents of block are preserved. If block is enlarging, contents of added space are filled with zeroes.
blockptrPointer to block to relocate. This must be same pointer as returned from allocation function, pointer into block is not enough.
newsizeNew size of block, in bytes
ERR_INVALID_POINTERBlockptr is not a valid allocated block pointer. This could also mean heap corruption , these two cases cannot be properly distinguished.
ERR_OUT_OF_MEMNot enough memory
ERR_ZERO_SIZEsize = 0
ERR_OUT_OF_RANGEsize is negative (or larger than 7FFFFFFFh if viewed as unsigned)
ERR_HEAP_CORRUPTHeap is corrupted . You was writing to memory outside of allocated block.
ERR_MODULE_NOT_INITIALIZEDModule is not initialized. Initialize module with mem.init to use this procedure.
ERR_UNKNOWNSystem returned error that wasn't translated to FASMLIB error. You can contact author about this, and translation can be added.
+mem.realloc_heapOnly on platforms where FASMLIB heap manager is used.
+mem.size+mem.realloc+mem.fillReturns size of memory block allocated by mem.alloc , mem.alloc0 , mem.realloc , or mem.realloc0 .
blockptrPointer to allocated memory block. This must be same pointer as returned from allocation function, pointer into block is not enough.
ERR_INVALID_POINTERBlockptr is not a valid allocated block pointer. This could also mean heap corruption , these two cases cannot be properly distinguished.
ERR_HEAP_CORRUPTHeap is corrupted . You was writing to memory outside of allocated block.
ERR_MODULE_NOT_INITIALIZEDModule is not initialized. Initialize module with mem.init to use this procedure.
ERR_UNKNOWNSystem returned error that wasn't translated to FASMLIB error. You can contact author about this, and translation can be added.
These are internal procedures of FASMLIB heap manager. These procedures may not be present at all. FASMLIB heap manager is used only when OS doesn't provide heap functions.
This is internal procedure of heap manager, that handles platform-dependent aspect of allocating entire heap. Do not call this procedure.
ERR_OUT_OF_MEMNot enough memory
ERR_ZERO_SIZEsize = 0
ERR_OUT_OF_RANGEsize is negative (or larger than 7FFFFFFFh if viewed as unsigned)
ERR_UNKNOWNSystem returned error that wasn't translated to FASMLIB error. You can contact author about this, and translation can be added.
This is internal procedure of heap manager, that handles platform-dependent aspect of resizing entire heap. Do not call this procedure.
heapptrPointer to heap block returned by mem.alloc_heap or by this procedure.
oldsizeCurrent size of heap. Must be provided by caller.
newsizeDesired size of heap.
ERR_INVALID_POINTERHeap pointer is invalid
ERR_OUT_OF_MEMNot enough memory
ERR_ZERO_SIZEnewsize = 0
ERR_OUT_OF_RANGEsize is negative (or larger than 7FFFFFFFh if viewed as unsigned)
ERR_UNKNOWNSystem returned error that wasn't translated to FASMLIB error. You can contact author about this, and translation can be added.
This is internal procedure of heap manager, that handles platform-dependent aspect of deallocating entire heap. Do not call this procedure.
heapptrPointer to heap, returned by mem.alloc_heap or mem.realloc_heap .
heapsizeCurrent size of heap. Must be provided by caller.
ERR_INVALID_POINTERHeap pointer is invalid
ERR_UNKNOWNSystem returned error that wasn't translated to FASMLIB error. You can contact author about this, and translation can be added.
Term Heap usually means area of memory containing all allocated blocks.
Term Heap Manager is used for routine that takes care of managing heap.
First, heap is initialized. This means heap manager allocates block of memory that will act as heap.
Heap is divided into blocks of varying size. Each block can be used (allocated) or unused. Consectutive unused blocks are merged into one. During allocation, heap manager searches blocks until it finds unused large enough block, and returns it. It can also split remaining unused space from block to create new block.
After long-term usage of heap, allocated blocks are spread among entire heap, not grouped together. There are small unused spaces between blocks, unlikely to be large enough for most allocations. This wastes memory, but it is never completely avoidable. This is called Heap Fragmentation.
One way how FASMLIB's heap manager prevents heap fragmentation is aligning block size to some higher value (64 by default, can be changed). Block still beheaves to caller as if it was smaller, but it's real size in heap is multiple of 64bytes. This makes small increases in size of block much faster, and prevents creation of very small blocks.
Every heap block is prepended by Block Header. Block header holds all info that heap manager needs about block. Problem pops out when user mistakenly overwrites this block header. Then, it is impossible to properly manage heap, and heap-managing procedure cannot continue to work. After this is detected, all heap procedures return ERR_HEAP_CORRUPT until you call mem.uninit to destroy heap.
Sometimes it is not possible for procedure to distinguish invalid pointer from corrupted heap. This can result in returning ERR_INVALID_POINTER instead of ERR_HEAP_CORRUPT. Anyway, both these errors are internal problem of your application, and should be investigated and solved.
Memory Leak is state, when you allocate some memory, and forget to release it. Such memory, even if not used anymore by code that allocated it, cannot be used, until memory management is uninitialized (usually at application exit). We say such memory is leaked.
Some people argue that memory is freed anyway as the application exits. This may be true, but still it isn't "right" way to do things. Also, if application is designed to be running for longer time, and it has code causing memory leak in it's looping part, then application's memory usage keeps growing, just by running. This is definitively bad.
Preventing memory leaks is not always so easy. In simplest case, each time you allocate block of memory, you immediately write the code to release it too. But sometimes you need to return allocated block to caller, and he must take care of releasing. So, when calling procedure that returns allocated block, be just as cautious as when allocating it yourself, and think lot if the block is released in every case.
FASMLIB helps you catching memory leaks as soon as your application producing them ends. If your application leaks some memory, it returns error ERR_MEMORY_LEAK when you call mem.uninit. FASMLIB finds memory leak by very simple mechanism: it counts all successful allocations, and if number of releasing isn't same, it's memory leak.
If mem.uninit returns you ERR_MEMORY_LEAK, you should browse through all your allocations, and check if allocated block is released in all cases. Most probably problem will be in recently added allocations, if you wasn't getting ERR_MEMORY_LEAK before.
FASMLIB provides several procedures to access files.
These routines are just wrappers of system procedures, and provide only basic access to files. You may want to use file streams instead.
Filesystem routines (directory access, disk enumeration, ...) are not supported yet.
nameName of file to create.
overwrSets behavior if file already exists: 1 = overwrites file, 0 = returns ERR_FILE_EXISTS.
modeSets access mode to file: 1 = write only, 2 = read/write
ERR_FILE_EXISTSFile with given name already exists (only returned if mode=0)
ERR_CANT_OPEN_FILEFile can't be created.
ERR_INVALID_MODEmode is not 0 or 1.
ERR_UNKNOWNPlatform-specific error during creating file.
namePointer to name of file to open. Must be zero-terminated string.
modeAccess mode to file: 0=read only, 1=write only, 2=read/write.
ERR_FILE_NOT_FOUNDFile with specified name wasn't found.
ERR_CANT_OPEN_FILEFile exists, but couldn't be opened.
ERR_INVALID_MODEmode > 2.
ERR_UNKNOWNPlatform-specific error during opening file.
namePointer to name of file to open. Must be zero-terminated string.
createSpecifies whether to create file if it doesn't exist. 1=create, 0=don't create.
modeAccess mode to file: 1=write only, 2=read/write.
ERR_FILE_NOT_FOUNDFile with specified name wasn't found. Only returned when create=0.
ERR_CANT_OPEN_FILEFile exists, but couldn't be opened.
ERR_INVALID_MODEmode=0, or mode>2, or create>1.
ERR_UNKNOWNPlatform-specific error during opening file.
+fileio.open+fileio.create+fileio.seek+fileio.closehandleFile handle (returned by fileio.open , fileio.create or fileio.append ).
bufferPointer to buffer where to read data.
countNumber of bytes to read.
CF set on error, otherwise EAX = number of bytes readen, and OF set if EOF was reached (less than count bytes read)
handleFile handle (returned by fileio.open , fileio.create or fileio.append ).
bufferPointer to data to write.
countSize of daata to write. Procedure does nothing if this is zero.
handleFile handle (returned by fileio.open , fileio.create or fileio.append ).
distlowLow order dword of distance to move.
disthighHigh order dword of distance to move.
modeMode of seeking. 0 = seek from beginning. 1 = seek relative distance from current position. 2 = seek from end (distance should be negative value).
ERR_NEGATIVE_SEEKSeek to negative file offset.
ERR_INVALID_HANDLEInvalid file handle.
ERR_OUT_OF_RANGEdist<0 when mode=0.
ERR_INVALID_MODEmode>2.
ERR_UNKNOWN
FASMLIB process management isn't very rich yet :)
FASMLIB Stream is just simply some thing, that you can write to and/or read from. Purpose of stream, is that they put everything that can behave this way under single interface. That means, if you have file, memory, and console as streams, then you can access them with exacly same code. It is slower than specialized code, but it prevents lot of code duplication.
Like every abstraction, streams are not good for everything. Using streams is slower and gives you less possibilities. But there is couple of things where streams are very useful.
Examples of what can be represented of stream:
Console is natural stream, for both reading and writing.
File is typical stream, and it also allows you to seek any position within file.
Block of memory can act as stream, for both reading and writing, and is seekable too.
Dynamic memory block is useful as stream for writing, because it can be enlarged any time to needed size, and you don't need to worry about buffer overflow.
Socket (network connection) is another typical stream.
Anoter advantage of stream, is that you can nest them. This means that one stream can write it's output to another stream. This way you can write flexible routines, like:
Text converter (EOL converter, locale converter).
Some types of data conversion.
Most types of encryption.
And, these routines can be reused on anything that is represented as stream. They can also be combined to use more such streams at once. For example, you can create chain of streams: create file stream, overload with base64 conversion, overload with compression, and overload with AES encryption. Then, when you write to topmost stream, actual data written to file will be encrypted with AES, compressed, converted to base64 and stored. When you want to write this data to socket, instead of file, you just replace file stream with socket stream. When you want different compression, you just replace that stream. So as you see, streams can be pretty useful, for some things.
Following is description of interface of FASMLIB streams. You don't need to understand most of following information, unless you want to create your own stream.
FASMLIB streams are implemented as typical objects, like ones from C++ or COM. Every stream object is structure stored in memory. First member of structure is pointer to virtual table. Virtual table holds addresses of methods associated with that object. Other members of stream structure are data of stream. Stream handle is just a pointer to stream object.
Users of library don't call methods directly, from virtual table. They use method wrapper procedures instead.
Structure of stream object is defined as STREAM in FASMLIB. Every stream object must have this structure, and it can have some additional data behind this structure. In OOP terms, STREAM is a base class.
Stream object consists of fields: (order of fields is different in actual structure)
DWORD vtab
Pointer to virtual table of this object. Virtual table holds pointers to methods used with this object.
BYTE allocated
Says whether stream object was allocated, and should be released on close, or if it is in static memory. If this is 1, then stream object memory would be freed with mem.free when stream.close is called.
BYTE wbuf.type
Type of write buffering. 0 means no buffering, 1 means static buffer, 2 means dynamic buffer.
DWORD wbuf
Pointer to beginning of write buffer. Can be 0, if no buffer is currently associated with stream.
DWORD wbuf.size
Size of read buffer.
DWORD wbuf.pos
Position of data inside write buffer. Only valid when wbuf.cnt is nonzero. This is index inside buffer, not pointer. Must be 0 if read buffer is disabled.
DWORD wbuf.cnt
Number of bytes stored in write buffer. When zero, buffer is empty. Must be 0 if read buffer is disabled.
BYTE rbuf.type
Type of read buffering. 0 means no buffering, 1 means static buffer, 2 means dynamic buffer.
DWORD rbuf
Pointer to beginning of read buffer. Can be 0, if no buffer is currently associated with stream.
DWORD rbuf.size
Size of read buffer
DWORD rbuf.pos
Position of data inside read buffer. Only valid when rbuf.cnt is nonzero. This is index inside buffer, not pointer. Must be 0 if read buffer is disabled.
DWORD rbuf.cnt
Number of bytes stored in buffer. When zero, buffer is empty. Must be 0 if read buffer is disabled.
BYTE rbuf.eof
Indicates that EOF was reached behind data that is in buffer.
Stream virtual table holds pointers to methods. Every stream class (file stream, stdout stream, ...) has it's own virtual table. Every stream object of that class points to it's virtual table.
Every stream virtual table starts with signature dword 'STRM'. This helps catching invalid pointers to stream objects.
Following signature, stream virtual table consists of pointers to these methods:
These are stream methods. Stream methods are just procedures with particular interface, that implement some functionality of stream.
Stream may or may not have each method implemented. Methods which are implemented are pointed by virtual table of given stream. Methods that are not implemented have zero pointer in virtual table.
These methods aren't called directly, you use method wrappers instead.
Reads data from stream to specified buffer. Blocks until enough data is read, or EOF occurs. Returns OF, if EOF occurs before requested ammount of bytes is read.
Pre-reads data from stream, and returns you pointer to them. Data still remain in stream, and will be readen by subsequent reads. Returned pointer is only valid until next operation with stream. Blocks until there is enough data available.
streamHandle of stream.
countNumber of bytes to peek.
readlenPointer to variable, which will hold number of chars in returned buffer. Only needed when function returns OF, otherwise it's equal to count. Ignored if 0.
Skips data from stream input. Skipping is like reading from stream, without actually storing readen data anywhere. Can be implemented with seeking forward.
Listed procedures are wrappers, which allow calling stream methods like normal procedures. They hide OOP aspect of streams from users of library.
Creates stream object. This call allows you to create static objects, dynamic object with static buffer, or dynamic objects with dynamic buffer.
objbufPointer to buffer to hold stream object. size of buffer must be at least "sizeof.STREAM". Set to 0 if you want procedure to allocate stream.
sizeNumber of additional bytes to allocate with object. These can be used to store additional data for methods. This value must be 0, if objbuf is nonzero (static stream object).
vtabPoints to object's virtual table . If readbuf=0, then peek method in virtual table must be 0.
readbufPointer to read buffer. 0 if none, 1 for dynamic buffer. Must be 0 if read method pointer is 0 in vtab.
rbuflenSize of read buffer. If readbuf=0, ignored. If readbuf=1, initial size of read buffer (allocated at creation). If readbuf=pointer, size of buffer. Must be 0 if read method pointer is 0 in vtab.
writebufPointer to write buffer, 0 if none, 1 for dynamic buffer. Must be 0 if write method pointer is 0 in vtab.
wbuflenSize of write buffer. If writebuf=0, ignored. If writebuf=1, initial size of buffer (allocated at creation). If writebuf=pointer, size of buffer. Must be 0 if write method pointer is 0 in vtab.
ERR_HANDLE_NOT_READABLEread=0 and some of peek, skip, readbug, rbuflen is non-zero.
ERR_OUT_OF_RANGEsize<0.
+mem.alloc0When pointer=0.
+mem.allocWhen readbuf=1 or writebuf=1.
+mem.fill+mem.freeCloses stream handle. If stream object was allocated, or it's buffers were allocated, they are deallocated.
ERR_INVALID_HANDLENot a valid stream handle.
ERR_HANDLE_CORRUPTHandle is corrupt. Probably you have overwriten stream object in memory. This might also be a FASMLIB bug.
+mem.free+stream close method streamHandle of stream to which we write.
bufferPointer to data to write.
countNumber of bytes to write. Procedure does nothing if count=0.
ERR_INVALID_HANDLENot a valid stream handle.
ERR_STREAM_NOT_WRITABLEStream is not writeable.
+stream write method streamHandle of stream to which we write.
valueByte value to write. Only low order byte of this dword is used, rest is ignored.
ERR_INVALID_HANDLENot a valid stream handle.
ERR_STREAM_NOT_WRITABLEStream is not writeable.
+stream.writestreamHandle of stream to which we write.
valueWord value to write. Only low order word of this dword is used, rest is ignored.
ERR_INVALID_HANDLENot a valid stream handle.
ERR_STREAM_NOT_WRITABLEStream is not writeable.
+stream.writeERR_INVALID_HANDLENot a valid stream handle.
ERR_STREAM_NOT_WRITABLEStream is not writeable.
+stream.writeReads data from stream to buffer. Blocks until enough data is read, or EOF occurs. Returns OF, if EOF occurs before requested ammount of bytes is read.
streamHandle of stream from which to read.
bufferPointer to buffer where data will be stored.
countNumber of bytes to read. Cannot be 0.
readbufPointer to procedure that does actual reading. Procedure recieves pointer to memory where to read, and number of bytes to read.
CF set on error, otherwise OF set if EOF was reached, and EAX = number of bytes readen. If OF=0, then EAX=count.
ERR_INVALID_HANDLEInvalid stream handle.
ERR_STREAM_NOT_READABLEStream is not readable.
ERR_ZERO_SIZEcount=0.
ERR_HANDLE_CORRUPTStream is corrupt. Either you are overwriting stream object somewhere, or it is an error in FASMLIB.
+stream read method Pre-reads data from stream, and returns you pointer to them. Data still remain in stream, and will be readen by subsequent reads. Returned pointer is only valid until next operation with stream. Blocks until there is enough data available.
streamHandle of stream.
countMinimal number of bytes to peek.
readlenPointer to variable, which will hold number of chars in returned buffer. When function returns OF=0, this number is greater or equal to count. When function returns OF=1, this number is less than than count. You can set this pointer to 0.
CF set on error, otherwise OF set if EOF was reached (less than count bytes readen), and EAX = pointer to buffer (READ ONLY, do not write there)
ERR_ZERO_SIZECount=0
ERR_INVALID_HANDLENot a stream handle.
ERR_HANDLE_NO_BUFFERStream doesn't have read buffer associated, nor peek method supported.
ERR_HANDLE_NOT_PEEKABLEStream is not peekable.
ERR_BUFFER_FULLHandle is associated with static buffer, with length smaller than count. Nothing was read from stream.
ERR_HANDLE_CORRUPTStream is corrupt, you are overwriting stream object somewhere (or it's error in FASMLIB).
+stream peek method Pre-reads byte from stream.. Returned byte still remain in stream, and will be readen by subsequent read. Blocks, if there is no data available.
CF set on error, otherwise OF set if EOF was reached, otherwise EAX = byte, zero extended to dword.
ERR_INVALID_HANDLENot a stream handle.
ERR_HANDLE_NO_BUFFERStream doesn't have read buffer associated, nor peek method supported.
ERR_HANDLE_NOT_PEEKABLEStream is not peekable.
ERR_HANDLE_CORRUPTStream is corrupt, you are overwriting stream object somewhere (or it's error in FASMLIB).
+stream.peekSkips data from stream input. Skipping is like reading from stream, without actually storing readen data anywhere.
streamHandle of stream to skip from.
countNumber of bytes to skip. Procedure does nothing if this is 0.
CF set on error, otherwise OF set if EOF was reached, and EAX = number of bytes skipped. If OF=0, then EAX=count.
ERR_INVALID_HANDLEInvalid stream handle passed.
ERR_HANDLE_NOT_READABLEStream is not readable.
+stream skip method +stream read method Used when stream doesn't have a skip method.
streamHandle of stream.
distlowLow order dword of distance to move.
disthighHigh order dword of distance to move.
modeMode of seeking. 0 = seek from beginning. 1 = seek relative distance from current position. 2 = seek from end (distance should be negative value).
ERR_NEGATIVE_SEEKSeek to negative offset.
ERR_INVALID_MODEmode > 2
ERR_HANDLE_NOT_SEEKABLEThis type of stream doesn't support seeking.
+stream seek method On most today systems, there are three default streams present. They are STDIN (standard input), STDOUT (standard output) and STDERR (standard error).
FASMLIB contains predefined stream objects for these streams. They are called stdin, stdout and stderr. They are defined as static global variables.
stdin is read-only stream. When program tries to read from it, program enters "line editing mode", where user can edit one line of text.
If user types more characters than program requested to read, rest of input is saved, and is returned by subsequent reads. These reads do not issue "line editing mode" if enough characters are saved from previous read.
If user types less characters than program requested to read, then program enters line editing mode again, and lets him type another line, until there are enough characters.
stdin can be, and often is, redirected from file (or pipe). That means that data readen from stdin are not entered by user in console, as usually. Because of that, calling application must always be ready to handle EOF (end of file) coming from stdin.
Following procedures are wrappers for some other stream procedures. They use stdin stream by default. Other arguments remain same as in original procedures.
This is just a call wrapper to text.read.char . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.line . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.chars . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.until . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.dec . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.dec_b . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.dec_w . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.dec_d . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.dec_q . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.idec . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.dec_ib . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.dec_iw . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.dec_id . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.dec_iq . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.hex . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.hex_b . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.hex_w . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.hex_d . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.hex_q . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.ihex . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.hex_ib . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.hex_iw . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.hex_id . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.read.hex_iq . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.fetch . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.fetch.char . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.fetch.str . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.skip.chars . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.skip.until . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.line . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.chars . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.until . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.dec . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.dec_b . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.dec_w . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.dec_d . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.dec_q . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.idec . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.dec_ib . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.dec_iw . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.dec_id . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.dec_iq . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.hex . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.hex_b . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.hex_w . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.hex_d . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.hex_q . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.ihex . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.hex_ib . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.hex_iw . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.hex_id . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extread.hex_iq . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extskip.chars . It specifies stdin as stream, and passes rest of arguments.
This is just a call wrapper to text.extskip.until . It specifies stdin as stream, and passes rest of arguments.
stdout is write-only stream. Anything you write to this stream is displayed on console.
Optionally, stdout can be redirected to file by parent application, but that doesn't matter to you.
Following procedures are wrappers for some other stream procedures. They use stdout stream by default. Other arguments remain same as in original procedures.
This is just a call wrapper to text.write . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.char . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.str . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.format . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.b_dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.w_dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.d_dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.q_dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.idec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.ib_dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.iw_dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.id_dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.iq_dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.b_hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.w_hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.d_hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.q_hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.ihex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.ib_hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.iw_hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.id_hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.write.iq_hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.b_dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.w_dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.d_dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.q_dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.idec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.ib_dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.iw_dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.id_dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.iq_dec . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.b_hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.w_hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.d_hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.q_hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.ihex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.ib_hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.iw_hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.id_hex . It specifies stdout as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.iq_hex . It specifies stdout as stream, and passes rest of arguments.
stderr is write-only stream. Anything you write to this stream is either displayed on console, or can be redirected to separate file.
You should write all normal output to stdout, and all error output to stderr. This allows to easily filter out error messages from normal output, just by redirecting stderr.
Following procedures are wrappers for some other stream procedures. They use stderr stream by default. Other arguments remain same as in original procedures.
This is just a call wrapper to text.write . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.char . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.str . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.format . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.b_dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.w_dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.d_dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.q_dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.idec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.ib_dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.iw_dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.id_dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.iq_dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.b_hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.w_hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.d_hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.q_hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.ihex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.ib_hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.iw_hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.id_hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.write.iq_hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.b_dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.w_dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.d_dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.q_dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.idec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.ib_dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.iw_dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.id_dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.iq_dec . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.b_hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.w_hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.d_hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.q_hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.ihex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.ib_hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.iw_hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.id_hex . It specifies stderr as stream, and passes rest of arguments.
This is just a call wrapper to text.extwrite.iq_hex . It specifies stderr as stream, and passes rest of arguments.
Initializes three standard streams: stdin , stdout and stderr . You should call this procedure before using these streams.
Uninitializes standard streams: stdin , stdout , stderr . You should call this procedure after you are done using these streams.
ERR_MODULE_NOT_INITIALIZEDModule wasn't initialized. Initialize module with stdstream.init first.
+stream.closeMemory streams put blocks of memory under stream interface.
Advantage of memory streams is that you can use text processing features of FASMLIB to work with memory.
These are description of memory stream method specifics.
These methods aren't called directly, you use stream method wrappers instead.
This is write method of memory stream . Don't call this procedure directly, use stream.write instead.
streamHandle of memory stream.
bufferPointer to data which we want to write.
countNumber of bytes to write.
CF set on error, otherwise OF set if EOF was reached (less than count bytes readen), and EAX = number of bytes readon.
ERR_BUFFER_FULLMemory buffer is full. No more place to write.
ERR_ZERO_SIZEcount = 0.
+mem.copyThis is read method of memory stream . Don't call this procedure directly, use stream.read instead.
streamHandle of memory stream.
bufferPointer to buffer where to store readen data.
countNumber of bytes to read.
This is peek method of memory stream . Don't call this procedure directly, use stream.peek instead.
streamHandle of memory stream.
countNumber of bytes to peek.
readlenPointer to variable, which will hold number of chars in returned buffer. Always returns all bytes up to end of buffer.
This is seek method of file stream . Don't call this procedure directly, use stream.seek instead.
This is tell method of file stream . Don't call this procedure directly, use file.tell instead.
This is skip method of memory stream . Don't call this procedure directly, use stream.skip instead.
Creates new memory stream . This is simple version. For more options see mstream.extcreate
Creates new memory stream . This is extended version. For simpler usage see mstream.create
objbufPointer to buffer for MSTREAM object. If 0, object is allocated.
bufferPointer to buffer where memory stream begins
bufszSize of buffer of memory stream.
File streams put file I/O under stream interface.
Advantage of file streams is that you can use other procedures that operate on streams, namely text processing features of FASMLIB. There is also better buffering support planned for future.
These are description of fstream method specifics.
These methods aren't called directly, you use stream method wrappers instead.
This is close method of file stream . Don't call this procedure directly, use file.close instead.
ERR_HANDLE_CORRUPTStream is corrupted. This can happen if you close file handle used by stream. This can also happen if you overwrite stream object.
ERR_UNKNOWNPlatform-specific error.
+fileio.closeThis is write method of file stream . Don't call this procedure directly, use file.write instead.
streamHandle of file stream to write to.
bufferPointer to data which we want to write.
countNumber of bytes to write.
ERR_HANDLE_CORRUPTStream is corrupted. This can happen if you close file handle used by stream. This can also happen if you overwrite stream object.
ERR_HANDLE_NOT_WRITEABLEStream is not readable.
ERR_UNKNOWNPlatform-specific error during writing to file.
+fileio.seek+fileio.writeThis is read method of file stream . Don't call this procedure directly, use file.read instead.
streamHandle of file stream to read from.
bufferPointer to buffer where we want to read data.
countNumber of bytes to read.
This is peek method of file stream . Don't call this procedure directly, use file.peek instead.
streamHandle of file stream to write to.
countNumber of bytes to peek.
readlenPointer to variable, which will hold number of chars in returned buffer. Only needed when function returns OF, otherwise it's equal to count. You can set this to 0, when you don't want handle case with OF=1.
This is seek method of file stream . Don't call this procedure directly, use file.seek instead.
streamHandle of file stream.
distlowLow order dword of distance to move.
disthighHigh order dword of distance to move.
modeMode of seeking. 0 = seek from beginning. 1 = seek relative distance from current position. 2 = seek from end (distance should be negative value).
ERR_HANDLE_CORRUPTStream is corrupted. This can happen if you close file handle used by stream. This can also happen if you overwrite stream object.
ERR_UNKNOWNPlatform-specific error.
+fileio.seekThis is tell method of file stream . Don't call this procedure directly, use file.tell instead.
ERR_HANDLE_CORRUPTStream is corrupted. This can happen if you close file handle used by stream. This can also happen if you overwrite stream object.
ERR_UNKNOWNPlatform-specific error.
+fileio.tellThese are just some aliases for those who like file.read more than stream.read...
nameName of file to create
overwrSets behavior if file already exists: 1 = overwrites file, 0 = returns ERR_FILE_EXISTS
modeSets access mode: 1 = write only, 2 = read/write
ERR_FILE_EXISTSFile with given name already exists (only returned if overwr=0)
ERR_CANT_OPEN_FILEFile can't be created.
ERR_INVALID_MODEmode = 0, or mode > 2, or overwr > 1
ERR_UNKNOWNPlatform-specific error during creating file.
+file.extcreateobjbufPointer to buffer for FSTREAM object. If 0, object is allocated.
nameName of file to create
overwrSets behavior if file already exists: 1 = overwrites file, 0 = returns ERR_FILE_EXISTS
modeSets access mode: 1 = write only, 2 = read/write
wbufRESERVED, must be 0
wbuflenRESERVED, must be 0
rbufPointer to read buffer. If 1, buffer will be allocated, and wbuflen holds initial size. If 0, read buffering is disabled. Must be 0 if mode = 1.
rbuflenIf rbuf=pointer, this is size of buffer. If rbuf=1, this is initial size of buffer. If rbuf=0, ignored. Must be 0 if mode = 1.
ERR_FILE_EXISTSFile with given name already exists (only returned if overwr=0)
ERR_CANT_OPEN_FILEFile can't be created.
ERR_INVALID_MODEmode = 0, or mode > 2, or overwr > 1
ERR_UNKNOWNPlatform-specific error during creating file.
+fileio.create+stream.create+fileio.closenamePointer to name of file to open. Must be zero-terminated string.
modeAccess mode to file: 0=read only, 1=write only, 2=read/write.
ERR_FILE_NOT_FOUNDFile with specified name wasn't found.
ERR_CANT_OPEN_FILEFile exists, but couldn't be opened.
ERR_INVALID_MODEmode > 2.
ERR_UNKNOWNPlatform-specific error during opening file.
+file.extopenobjbufPointer to buffer for FSTREAM object. If 0, object is allocated.
namePointer to name of file to open. Must be zero-terminated string.
modeAccess mode to file: 0=read only, 1=write only, 2=read/write.
wbufRESERVED, must be 0
wbuflenRESERVED, must be 0
rbufPointer to read buffer. If 1, buffer will be allocated, and wbuflen holds initial size. If 0, read buffering is disabled.
rbuflenIf rbuf=pointer, this is size of buffer. If rbuf=1, this is initial size of buffer. If rbuf=0, ignored.
ERR_FILE_NOT_FOUNDFile with specified name wasn't found.
ERR_CANT_OPEN_FILEFile exists, but couldn't be opened.
ERR_INVALID_MODEmode > 2.
ERR_UNKNOWNPlatform-specific error during opening file.
+fileio.open+stream.create+fileio.closenameName of file to create
createSpecifies whether to create file if it doesn't exist. 1=create, 0=don't create.
modeAccess mode to file: 1=write only, 2=read/write.
ERR_FILE_NOT_FOUNDFile with given name wasn't found. Only returned when create=0.
ERR_CANT_OPEN_FILEFile can't be created.
ERR_INVALID_MODEmode = 0, or mode > 2, or overwr > 1.
ERR_UNKNOWNPlatform-specific error during creating file.
+file.extappendobjbufPointer to buffer for FSTREAM object. If 0, object is allocated.
nameName of file to create
createSpecifies whether to create file if it doesn't exist. 1=create, 0=don't create.
modeAccess mode to file: 1=write only, 2=read/write.
wbufRESERVED, must be 0
wbuflenRESERVED, must be 0
rbufPointer to read buffer. If 1, buffer will be allocated, and wbuflen holds initial size. If 0, read buffering is disabled. Must be 0 if mode = 1.
rbuflenIf rbuf=pointer, this is size of buffer. If rbuf=1, this is initial size of buffer. If rbuf=0, ignored. Must be 0 if mode = 1.
ERR_FILE_NOT_FOUNDFile with given name wasn't found. Only returned when create=0.
ERR_CANT_OPEN_FILEFile can't be created.
ERR_INVALID_MODEmode = 0, or mode > 2, or overwr > 1, or rbuf is nonzero when mode=1, or rbuflen is nonzero when mode=1.
ERR_UNKNOWNPlatform-specific error during creating file.
+fileio.append+stream.create+fileio.closeobjbufPointer to buffer for FSTREAM object. If 0, object is allocated.
handleFile handle returned by fileio.open , fileio.create , or fileio.append .
modeAccess mode to file: 0=read only, 1=write only, 2=read/write. This mode should be same as one specified when opening handle. If mode for handle was 2, this can be 0 or 1, but not otherwise.
ERR_INVALID_HANDLEInvalid file handle passed
ERR_INVALID_MODEmode > 2.
ERR_UNKNOWNPlatform-specific error during opening file.
+file.extopen.handleobjbufPointer to buffer for FSTREAM object. If 0, object is allocated.
handleFile handle returned by fileio.open , fileio.create , or fileio.append .
modeAccess mode to file: 0=read only, 1=write only, 2=read/write. This mode should be same as one specified when opening handle. If mode for handle was 2, this can be 0 or 1, but not otherwise.
wbufRESERVED, must be 0
wbuflenRESERVED, must be 0
rbufPointer to read buffer. If 1, buffer will be allocated, and wbuflen holds initial size. If 0, read buffering is disabled.
rbuflenIf rbuf=pointer, this is size of buffer. If rbuf=1, this is initial size of buffer. If rbuf=0, ignored.
ERR_INVALID_HANDLEInvalid file handle passed
ERR_INVALID_MODEmode > 2.
ERR_UNKNOWNPlatform-specific error during opening file.
+stream.create+fileio.closeFASMLIB provides set of procedures for ASCII text processing.
These procedures operate on streams.
Procedures for writing ASCII text to streams.
Procedures for writing decimal numbers to streams.
streamHandle of stream to write to.
valuelowLow order dword of value to write.
valuehighHigh order dword of value to write.
Writes signed byte (8 bit) to stream as ASCII decimal string. This is simpler version of procedure, for extended version see text.extwrite.b_dec . For unsigned version, see text.write.b_dec .
Writes signed word (16 bit) to stream as ASCII decimal string. This is simpler version of procedure, for extended version see text.extwrite.iw_dec . For unsigned version, see text.write.w_dec .
Writes signed dword (32 bit) to stream as ASCII decimal string. This is simpler version of procedure, for extended version see text.extwrite.id_dec . For unsigned version, see text.write.d_dec .
Writes signed qword (64 bit) to stream as ASCII decimal string. This is simpler version of procedure, for extended version see text.extwrite.iq_dec . For unsigned version, see text.write.q_dec .
streamHandle of stream to write to.
valueValue to write as decimal string. Only low order word of this dword is used, rest is ignored.
paddingType of padding: type 0 is no padding, type 1 is prepending with spaces, type 2 is prepending with leading zeroes.
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
streamHandle of stream to write to.
valueValue to write as decimal string. Only low order word of this dword is used, rest is ignored.
paddingType of padding: type 0 is no padding, type 1 is prepending with spaces, type 2 is prepending with leading zeroes.
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
streamHandle of stream to write to.
valueValue to write as decimal string.
paddingType of padding: type 0 is no padding, type 1 is prepending with spaces, type 2 is prepending with leading zeroes.
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
streamHandle of stream to write to.
valuelowLow order dword of value to write.
valuehighHigh order dword of value to write.
paddingType of padding: type 0 is no padding, type 1 is prepending with spaces, type 2 is prepending with leading zeroes.
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
streamHandle of stream to write to.
valueValue to write as decimal string. Only low order byte of this dword is used, rest is ignored.
paddingType of padding: Type 0 is no padding. Type 1 is prepending with spaces, and sign counts into padding size. Type 2 is prepending with leading zeroes. In this type padlen specifies number digits displayed. One more character is always printed as sign (' ', '+' or '-').
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
plusSet to 1 if you want to display plus sign on positive numbers.
ERR_OUT_OF_RANGEpadlen > 4096
ERR_INVALID_MODEpadding > 2, or plus > 1
+text.extwrite.id_decstreamHandle of stream to write to.
valueValue to write as decimal string. Only low order word of this dword is used, rest is ignored.
paddingType of padding: Type 0 is no padding. Type 1 is prepending with spaces, and sign counts into padding size. Type 2 is prepending with leading zeroes. In this type padlen specifies number digits displayed. One more character is always printed as sign (' ', '+' or '-').
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
plusSet to 1 if you want to display plus sign on positive numbers.
ERR_OUT_OF_RANGEpadlen > 4096
ERR_INVALID_MODEpadding > 2, or plus > 1
+text.extwrite.id_decstreamHandle of stream to write to.
valueValue to write as decimal string.
paddingType of padding: Type 0 is no padding. Type 1 is prepending with spaces, and sign counts into padding size. Type 2 is prepending with leading zeroes. In this type padlen specifies number digits displayed. One more character is always printed as sign (' ', '+' or '-').
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
plusSet to 1 if you want to display plus sign on positive numbers.
ERR_OUT_OF_RANGEpadlen > 4096
ERR_INVALID_MODEpadding > 2, or plus > 1
+extconv.id_dec+stream.writestreamHandle of stream to write to.
valuelowLow order dword of value to write.
valuehighHigh order dword of value to write.
paddingType of padding: Type 0 is no padding. Type 1 is prepending with spaces, and sign counts into padding size. Type 2 is prepending with leading zeroes. In this type padlen specifies number digits displayed. One more character is always printed as sign (' ', '+' or '-').
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
plusSet to 1 if you want to display plus sign on positive numbers.
ERR_OUT_OF_RANGEpadlen > 4096
ERR_INVALID_MODEpadding > 2, or plus > 1
+extconv.iq_dec+stream.writeProcedures for writing hexadecimal numbers to streams.
streamHandle of stream to write to.
valuelowLow order dword of value to write.
valuehighHigh order dword of value to write.
Writes signed byte (8 bit) to stream as ASCII hexadecimal string. This is simpler version of procedure, for extended version see text.extwrite.b_hex . For unsigned version, see text.write.b_hex .
Writes signed word (16 bit) to stream as ASCII hexadecimal string. This is simpler version of procedure, for extended version see text.extwrite.iw_hex . For unsigned version, see text.write.w_hex .
Writes signed dword (32 bit) to stream as ASCII hexadecimal string. This is simpler version of procedure, for extended version see text.extwrite.id_hex . For unsigned version, see text.write.d_hex .
Writes signed qword (64 bit) to stream as ASCII hexadecimal string. This is simpler version of procedure, for extended version see text.extwrite.iq_hex . For unsigned version, see text.write.q_hex .
streamHandle of stream to write to.
valueValue to write as hexadecimal string. Only low order byte of this dword is used, rest is ignored.
paddingType of padding: type 0 is no padding, type 1 is prepending with spaces, type 2 is prepending with leading zeroes.
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
streamHandle of stream to write to.
valueValue to write as hexadecimal string. Only low order word of this dword is used, rest is ignored.
paddingType of padding: type 0 is no padding, type 1 is prepending with spaces, type 2 is prepending with leading zeroes.
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
streamHandle of stream to write to.
valueValue to write as hexadecimal string.
paddingType of padding: type 0 is no padding, type 1 is prepending with spaces, type 2 is prepending with leading zeroes.
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
streamHandle of stream to write to.
valuelowLow order dword of value to write.
valuehighHigh order dword of value to write.
paddingType of padding: type 0 is no padding, type 1 is prepending with spaces, type 2 is prepending with leading zeroes.
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
streamHandle of stream to write to.
valueValue to write as hexadecimal string. Only low order byte of this dword is used, rest is ignored.
paddingType of padding: Type 0 is no padding. Type 1 is prepending with spaces, and sign counts into padding size. Type 2 is prepending with leading zeroes. In this type padlen specifies number digits displayed. One more character is always printed as sign (' ', '+' or '-').
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
plusSet to 1 if you want to display plus sign on positive numbers.
ERR_OUT_OF_RANGEpadlen > 4096
ERR_INVALID_MODEpadding > 2, or plus > 1
+text.extwrite.id_hexstreamHandle of stream to write to.
valueValue to write as hexadecimal string. Only low order word of this dword is used, rest is ignored.
paddingType of padding: Type 0 is no padding. Type 1 is prepending with spaces, and sign counts into padding size. Type 2 is prepending with leading zeroes. In this type padlen specifies number digits displayed. One more character is always printed as sign (' ', '+' or '-').
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
plusSet to 1 if you want to display plus sign on positive numbers.
ERR_OUT_OF_RANGEpadlen > 4096
ERR_INVALID_MODEpadding > 2, or plus > 1
+text.extwrite.id_hexstreamHandle of stream to write to.
valueValue to write as hexadecimal string.
paddingType of padding: Type 0 is no padding. Type 1 is prepending with spaces, and sign counts into padding size. Type 2 is prepending with leading zeroes. In this type padlen specifies number digits displayed. One more character is always printed as sign (' ', '+' or '-').
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
plusSet to 1 if you want to display plus sign on positive numbers.
ERR_OUT_OF_RANGEpadlen > 4096
ERR_INVALID_MODEpadding > 2, or plus > 1
+extconv.id_hex+stream.writestreamHandle of stream to write to.
valuelowLow order dword of value to write.
valuehighHigh order dword of value to write.
paddingType of padding: Type 0 is no padding. Type 1 is prepending with spaces, and sign counts into padding size. Type 2 is prepending with leading zeroes. In this type padlen specifies number digits displayed. One more character is always printed as sign (' ', '+' or '-').
padlenLength to which should output be padded. If output is already longer than this value before padding, then output is not padded. Ignored if padding = 0.
plusSet to 1 if you want to display plus sign on positive numbers.
ERR_OUT_OF_RANGEpadlen > 4096
ERR_INVALID_MODEpadding > 2, or plus > 1
+extconv.iq_hex+stream.writeWrites null-terminated ASCII string to stream . This function should be only used with constant string argument. Use text.fetch.str for non-constant strings.
streamHandle of stream to write to. For standard streams, you can use stdout.write or stderr.write .
stringPointer to string.
Writes formatted output to stream. That means, displays format string with special % values substituted by converted values of additional arguments.
streamStream to write to. For standard streams, you can use stdout.write or stderr.write .
formatFormat string. See output format string for more information.
<arguments>Remaining arguments depend on format string. Arguments are pushed on stack normally like with any other procedure. All arguments are removed from stack by this procedure, no extra code needed.
Writes string to stream . If string is guaranteed to be null terminated, you can use text.write instead.
streamHandle of stream to write to. For standard streams, you can use stdout.write.str or stderr.write.str .
stringPointer to string.
buflenLength of string buffer.
Procedures for reading ASCII text from streams.
Procedures for reading decimal numbers from streams.
Reads unsigned decimal byte from stream. This is simple version, for more options see text.extread.dec_b . Reads decimal digit characters ('0'-'9') until it reaches non-digit, EOF, or until resulting value overflows.
Reads unsigned decimal word from stream. This is simple version, for more options see text.extread.dec_w . Reads decimal digit characters ('0'-'9') until it reaches non-digit, EOF, or until resulting value overflows.
Reads unsigned decimal dword from stream. This is simple version, for more options see text.extread.dec_d . Reads decimal digit characters ('0'-'9') until it reaches non-digit, EOF, or until resulting value overflows.
Reads unsigned decimal qword from stream. This is simple version, for more options see text.extread.dec_q . Reads decimal digit characters ('0'-'9') until it reaches non-digit, EOF, or until resulting value overflows.
ERR_HANDLE_EOFEOF reached.
ERR_OUT_OF_RANGEvalue > 18446744073709551615. In this case all digit characters remain on stream.
ERR_NOT_DECIMALFirst character is not decimal digit. Character remains on stream.
+text.extread.dec_qReads signed decimal byte from stream. This is simple version, for more options see text.extread.dec_ib . Reads optional sign ('-' or '+') and decimal digit characters ('0'-'9') until it reaches non-digit, EOF, or until resulting value overflows.
Reads signed decimal word from stream. This is simple version, for more options see text.extread.dec_iw . Reads optional sign ('-' or '+') and decimal digit characters ('0'-'9') until it reaches non-digit, EOF, or until resulting value overflows.
Reads signed decimal dword from stream. This is simple version, for more options see text.extread.dec_id . Reads optional sign ('-' or '+') and decimal digit characters ('0'-'9') until it reaches non-digit, EOF, or until resulting value overflows.
Reads signed decimal qword from stream. This is simple version, for more options see text.extread.dec_iq . Reads optional sign ('-' or '+') and decimal digit characters ('0'-'9') until it reaches non-digit, EOF, or until resulting value overflows.
ERR_HANDLE_EOFEOF reached.
ERR_OUT_OF_RANGEvalue < -9223372036854775808 or value > 9223372036854775807. In this case sign character and all digit characters remain on stream.
ERR_NOT_DECIMALFirst character (after sign) is not decimal digit. Character remains on stream.
+text.extread.dec_iqReads unsigned decimal byte from stream. This is extended version, for simpler usage see text.read.dec_b . Reads decimal digit characters ('0'-'9') until it reaches non-digit, EOF, or until resulting value overflows.
streamHandle of stream from which to read.
maxlenMaximum number of digits to read. 0 if not specified.
skipblIf 1, procedure first skips initial blank characters (space, tab, EOL). These characters don't count into maxlen size.
lenPointer to dword variable, that will be set to number of digits read. Ignored if 0. When skipbl=1, skipped initial blank characters don't count.
ERR_HANDLE_EOFEOF reached. len is set to 0.
ERR_OUT_OF_RANGEvalue > 255. In this case all digit characters remain on stream. len contains number of characters readen until overflow.
ERR_NOT_DECIMALFirst character is not decimal digit. Character remains on stream. len is set to 0.
ERR_ZERO_VALUEmaxlen=0. len is set to 0.
ERR_INVALID_MODEskipbl > 1. len is set to 0.
Reads unsigned decimal word from stream. This is extended version, for simpler usage see text.read.dec_w . Reads decimal digit characters ('0'-'9') until it reaches non-digit, EOF, or until resulting value overflows.
streamHandle of stream from which to read.
maxlenMaximum number of digits to read. 0 if not specified.
skipblIf 1, procedure first skips initial blank characters (space, tab, EOL). These characters don't count into maxlen size.
lenPointer to dword variable, that will be set to number of digits read. Ignored if 0. When skipbl=1, skipped initial blank characters don't count.
ERR_HANDLE_EOFEOF reached. len is set to 0.
ERR_OUT_OF_RANGEvalue > 65535. In this case all digit characters remain on stream. len contains number of characters readen until overflow.
ERR_NOT_DECIMALFirst character is not decimal digit. Character remains on stream. len is set to 0.
ERR_ZERO_VALUEmaxlen=0. len is set to 0.
ERR_INVALID_MODEskipbl > 1. len is set to 0.
Reads unsigned decimal dword from stream. This is extended version, for simpler usage see text.read.dec_d . Reads decimal digit characters ('0'-'9') until it reaches non-digit, EOF, or until resulting value overflows.
streamHandle of stream from which to read.
maxlenMaximum number of digits to read. 0 if not specified.
skipblIf 1, procedure first skips initial blank characters (space, tab, EOL). These characters don't count into maxlen size.
lenPointer to dword variable, that will be set to number of digits read. Ignored if 0. When skipbl=1, skipped initial blank characters don't count.
ERR_HANDLE_EOFEOF reached. len is set to 0.
ERR_OUT_OF_RANGEvalue > 4294967295. In this case all digit characters remain on stream. len contains number of characters readen until overflow.
ERR_NOT_DECIMALFirst character is not decimal digit. Character remains on stream. len is set to 0.
ERR_ZERO_VALUEmaxlen=0. len is set to 0.
ERR_INVALID_MODEskipbl > 1. len is set to 0.
Reads unsigned decimal qword from stream. This is extended version, for simpler usage see text.read.dec_q . Reads decimal digit characters ('0'-'9') until it reaches non-digit, EOF, or until resulting value overflows.
streamHandle of stream from which to read.
maxlenMaximum number of digits to read. 0 if not specified.
skipblIf 1, procedure first skips initial blank characters (space, tab, EOL). These characters don't count into maxlen size.
lenPointer to dword variable, that will be set to number of digits read. Ignored if 0. When skipbl=1, skipped initial blank characters don't count.
ERR_HANDLE_EOFEOF reached. len is set to 0.
ERR_OUT_OF_RANGEvalue > 18446744073709551615. In this case all digit characters remain on stream. len contains number of characters readen until overflow.
ERR_NOT_DECIMALFirst character is not decimal digit. Character remains on stream. len is set to 0.
ERR_ZERO_VALUEmaxlen=0. len is set to 0.
ERR_INVALID_MODEskipbl > 1. len is set to 0.
+text.skip.chars+stream.peek.byte+stream.peek+stream.skipReads signed decimal byte from stream. This is extended version, for simpler usage see text.read.dec_ib . Reads decimal digit characters ('0'-'9') until it reaches non-digit, EOF, or until resulting value overflows.
streamHandle of stream from which to read.
maxlenMaximum number of characters to read, including sign. 0 if not specified.
skipblIf 1, procedure first skips initial blank characters (space, tab, EOL). These characters don't count into maxlen size. These characters do not remain on stream in case of error.
allowplusIf 1, plus sign "+" is accepted.
lenPointer to dword variable, that will be set to number of digits read. Ignored if 0. When skipbl=1, skipped initial blank characters don't count.
ERR_HANDLE_EOFEOF reached. len is set to 0.
ERR_OUT_OF_RANGEvalue < -128 or value > 127. In this case sign character and all digit characters remain on stream. len contains number of characters readen until overflow.
ERR_NOT_DECIMALFirst character (after sign) is not a decimal digit. Characters remains on stream. len is set to 0.
ERR_ZERO_VALUEmaxlen=0. len is set to 0.
ERR_INVALID_MODEskipbl > 1. len is set to 0.
Reads signed decimal word from stream. This is extended version, for simpler usage see text.read.dec_iw . Reads decimal digit characters ('0'-'9') until it reaches non-digit, EOF, or until resulting value overflows.
streamHandle of stream from which to read.
maxlenMaximum number of characters to read, including sign. 0 if not specified.
skipblIf 1, procedure first skips initial blank characters (space, tab, EOL). These characters don't count into maxlen size. These characters do not remain on stream in case of error.
allowplusIf 1, plus sign "+" is accepted.
lenPointer to dword variable, that will be set to number of digits read. Ignored if 0. When skipbl=1, skipped initial blank characters don't count.
ERR_HANDLE_EOFEOF reached. len is set to 0.
ERR_OUT_OF_RANGEvalue < -32768 or value > 32767. In this case sign character and all digit characters remain on stream. len contains number of characters readen until overflow.
ERR_NOT_DECIMALFirst character (after sign) is not a decimal digit. Characters remains on stream. len is set to 0.
ERR_ZERO_VALUEmaxlen=0. len is set to 0.
ERR_INVALID_MODEskipbl > 1. len is set to 0.
Reads signed decimal dword from stream. This is extended version, for simpler usage see text.read.dec_id . Reads decimal digit characters ('0'-'9') until it reaches non-digit, EOF, or until resulting value overflows.
streamHandle of stream from which to read.
maxlenMaximum number of characters to read, including sign. 0 if not specified.
skipblIf 1, procedure first skips initial blank characters (space, tab, EOL). These characters don't count into maxlen size. These characters do not remain on stream in case of error.
allowplusIf 1, plus sign "+" is accepted.
lenPointer to dword variable, that will be set to number of digits read. Ignored if 0. When skipbl=1, skipped initial blank characters don't count.
ERR_HANDLE_EOFEOF reached. len is set to 0.
ERR_OUT_OF_RANGEvalue < -2147483648 or value > 2147483647. In this case sign character and all digit characters remain on stream. len contains number of characters readen until overflow.
ERR_NOT_DECIMALFirst character (after sign) is not a decimal digit. Characters remains on stream. len is set to 0.
ERR_ZERO_VALUEmaxlen=0. len is set to 0.
ERR_INVALID_MODEskipbl > 1. len is set to 0.
Reads signed decimal qword from stream. This is extended version, for simpler usage see text.read.dec_iq . Reads decimal digit characters ('0'-'9') until it reaches non-digit, EOF, or until resulting value overflows.
streamHandle of stream from which to read.
maxlenMaximum number of characters to read, including sign. 0 if not specified.
skipblIf 1, procedure first skips initial blank characters (space, tab, EOL). These characters don't count into maxlen size. These characters do not remain on stream in case of error.
allowplusIf 1, plus sign "+" is accepted.
lenPointer to dword variable, that will be set to number of digits read. Ignored if 0. When skipbl=1, skipped initial blank characters don't count.
ERR_HANDLE_EOFEOF reached. len is set to 0.
ERR_OUT_OF_RANGEvalue < -9223372036854775808 or value > 9223372036854775807. In this case sign character and all digit characters remain on stream. len contains number of characters readen until overflow.
ERR_NOT_DECIMALFirst character (after sign) is not a decimal digit. Characters remains on stream. len is set to 0.
ERR_ZERO_VALUEmaxlen=0. len is set to 0.
ERR_INVALID_MODEskipbl > 1. len is set to 0.
+text.skip.chars+stream.peek.byte+stream.peek+stream.skipProcedures for reading hexadecimal numbers from streams.
Reads unsigned hexadecimal byte from stream. This is simple version, for more options see text.extread.hex_b . Reads hexadecimal digit characters ('0'-'9','a'-'z','A'-'Z') until it reaches non-digit, EOF, or until resulting value overflows.
Reads unsigned hexadecimal word from stream. This is simple version, for more options see text.extread.hex_w . Reads hexadecimal digit characters ('0'-'9','a'-'z','A'-'Z') until it reaches non-digit, EOF, or until resulting value overflows.
Reads unsigned hexadecimal dword from stream. This is simple version, for more options see text.extread.hex_d . Reads hexadecimal digit characters ('0'-'9','a'-'z','A'-'Z') until it reaches non-digit, EOF, or until resulting value overflows.
Reads unsigned hexadecimal qword from stream. This is simple version, for more options see text.extread.hex_q . Reads hexadecimal digit characters ('0'-'9','a'-'z','A'-'Z') until it reaches non-digit, EOF, or until resulting value overflows.
ERR_HANDLE_EOFEOF reached.
ERR_OUT_OF_RANGEvalue > FFFFFFFFFFFFFFFF. In this case all digit characters remain on stream.
ERR_NOT_HEXADECIMALFirst character is not a hexadecimal digit. Character remains on stream.
+text.extread.hex_qReads signed hexadecimal byte from stream. This is simple version, for more options see text.extread.hex_ib . Reads optional sign ('-' or '+') and hexadecimal digit characters ('0'-'9','a'-'f','A'-'F') until it reaches non-digit, EOF, or until resulting value overflows.
Reads signed hexadecimal word from stream. This is simple version, for more options see text.extread.hex_iw . Reads optional sign ('-' or '+') and hexadecimal digit characters ('0'-'9','a'-'f','A'-'F') until it reaches non-digit, EOF, or until resulting value overflows.
Reads signed hexadecimal dword from stream. This is simple version, for more options see text.extread.hex_id . Reads optional sign ('-' or '+') and hexadecimal digit characters ('0'-'9','a'-'f','A'-'F') until it reaches non-digit, EOF, or until resulting value overflows.
Reads signed hexadecimal qword from stream. This is simple version, for more options see text.extread.hex_iq . Reads optional sign ('-' or '+') and hexadecimal digit characters ('0'-'9','a'-'f','A'-'F') until it reaches non-digit, EOF, or until resulting value overflows.
ERR_HANDLE_EOFEOF reached.
ERR_OUT_OF_RANGEvalue < -8000000000000000 or value > 7FFFFFFFFFFFFFFF. In this case sign character and all digit characters remain on stream.
ERR_NOT_HEXADECIMALFirst character (after sign) is not hexadecimal digit. Character remains on stream.
+text.extread.hex_iqReads unsigned hexadecimal byte from stream. This is extended version, for simpler usage see text.read.hex_b . Reads hexadecimal digit characters ('0'-'9','a'-'f','A'-'F') until it reaches non-digit, EOF, or until resulting value overflows.
streamHandle of stream from which to read.
maxlenMaximum number of digits to read. 0 if not specified.
skipblIf 1, procedure first skips initial blank characters (space, tab, EOL). These characters don't count into maxlen size.
lenPointer to dword variable, that will be set to number of digits read. Ignored if 0. When skipbl=1, skipped initial blank characters don't count.
ERR_HANDLE_EOFEOF reached. len is set to 0.
ERR_OUT_OF_RANGEvalue > FF. In this case all digit characters remain on stream. len contains number of characters readen until overflow.
ERR_NOT_HEXADECIMALFirst character is not hexadecimal digit. Character remains on stream. len is set to 0.
ERR_ZERO_VALUEmaxlen=0. len is set to 0.
ERR_INVALID_MODEskipbl > 1. len is set to 0.
Reads unsigned hexadecimal word from stream. This is extended version, for simpler usage see text.read.hex_w . Reads hexadecimal digit characters ('0'-'9','a'-'f','A'-'F') until it reaches non-digit, EOF, or until resulting value overflows.
streamHandle of stream from which to read.
maxlenMaximum number of digits to read. 0 if not specified.
skipblIf 1, procedure first skips initial blank characters (space, tab, EOL). These characters don't count into maxlen size.
lenPointer to dword variable, that will be set to number of digits read. Ignored if 0. When skipbl=1, skipped initial blank characters don't count.
ERR_HANDLE_EOFEOF reached. len is set to 0.
ERR_OUT_OF_RANGEvalue > FFFF. In this case all digit characters remain on stream. len contains number of characters readen until overflow.
ERR_NOT_HEXADECIMALFirst character is not hexadecimal digit. Character remains on stream. len is set to 0.
ERR_ZERO_VALUEmaxlen=0. len is set to 0.
ERR_INVALID_MODEskipbl > 1. len is set to 0.
Reads unsigned hexadecimal dword from stream. This is extended version, for simpler usage see text.read.hex_d . Reads hexadecimal digit characters ('0'-'9','a'-'f','A'-'F') until it reaches non-digit, EOF, or until resulting value overflows.
streamHandle of stream from which to read.
maxlenMaximum number of digits to read. 0 if not specified.
skipblIf 1, procedure first skips initial blank characters (space, tab, EOL). These characters don't count into maxlen size.
lenPointer to dword variable, that will be set to number of digits read. Ignored if 0. When skipbl=1, skipped initial blank characters don't count.
ERR_HANDLE_EOFEOF reached. len is set to 0.
ERR_OUT_OF_RANGEvalue > FFFFFFFF. In this case all digit characters remain on stream. len contains number of characters readen until overflow.
ERR_NOT_HEXADECIMALFirst character is not hexadecimal digit. Character remains on stream. len is set to 0.
ERR_ZERO_VALUEmaxlen=0. len is set to 0.
ERR_INVALID_MODEskipbl > 1. len is set to 0.
Reads unsigned hexadecimal qword from stream. This is extended version, for simpler usage see text.read.hex_d . Reads hexadecimal digit characters ('0'-'9','a'-'f','A'-'F') until it reaches non-digit, EOF, or until resulting value overflows.
streamHandle of stream from which to read.
maxlenMaximum number of digits to read. 0 if not specified.
skipblIf 1, procedure first skips initial blank characters (space, tab, EOL). These characters don't count into maxlen size.
lenPointer to dword variable, that will be set to number of digits read. Ignored if 0. When skipbl=1, skipped initial blank characters don't count.
ERR_HANDLE_EOFEOF reached. len is set to 0.
ERR_OUT_OF_RANGEvalue > FFFFFFFFFFFFFFFF. In this case all digit characters remain on stream. len contains number of characters readen until overflow.
ERR_NOT_HEXADECIMALFirst character is not hexadecimal digit. Character remains on stream. len is set to 0.
ERR_ZERO_VALUEmaxlen=0. len is set to 0.
ERR_INVALID_MODEskipbl > 1. len is set to 0.
+text.skip.chars+stream.peek.byte+stream.peek+stream.skipReads signed hexadecimal byte from stream. This is extended version, for simpler usage see text.read.hex_ib . Reads hexadecimal digit characters ('0'-'9','a'-'f','A'-'F') until it reaches non-digit, EOF, or until resulting value overflows.
streamHandle of stream from which to read.
maxlenMaximum number of characters to read, including sign. 0 if not specified.
skipblIf 1, procedure first skips initial blank characters (space, tab, EOL). These characters don't count into maxlen size. These characters do not remain on stream in case of error.
allowplusIf 1, plus sign "+" is accepted.
lenPointer to dword variable, that will be set to number of digits read. Ignored if 0. When skipbl=1, skipped initial blank characters don't count.
ERR_HANDLE_EOFEOF reached. len is set to 0.
ERR_OUT_OF_RANGEvalue < -80 or value > 7F. In this case sign character and all digit characters remain on stream. len contains number of characters readen until overflow.
ERR_NOT_HEXADECIMALFirst character (after sign) is not a hexadecimal digit. Characters remains on stream. len is set to 0.
ERR_ZERO_VALUEmaxlen=0. len is set to 0.
ERR_INVALID_MODEskipbl > 1. len is set to 0.
Reads signed hexadecimal word from stream. This is extended version, for simpler usage see text.read.hex_iw . Reads hexadecimal digit characters ('0'-'9','a'-'f','A'-'F') until it reaches non-digit, EOF, or until resulting value overflows.
streamHandle of stream from which to read.
maxlenMaximum number of characters to read, including sign. 0 if not specified.
skipblIf 1, procedure first skips initial blank characters (space, tab, EOL). These characters don't count into maxlen size. These characters do not remain on stream in case of error.
allowplusIf 1, plus sign "+" is accepted.
lenPointer to dword variable, that will be set to number of digits read. Ignored if 0. When skipbl=1, skipped initial blank characters don't count.
ERR_HANDLE_EOFEOF reached. len is set to 0.
ERR_OUT_OF_RANGEvalue < -8000 or value > 7FFF. In this case sign character and all digit characters remain on stream. len contains number of characters readen until overflow.
ERR_NOT_HEXADECIMALFirst character (after sign) is not a hexadecimal digit. Characters remains on stream. len is set to 0.
ERR_ZERO_VALUEmaxlen=0. len is set to 0.
ERR_INVALID_MODEskipbl > 1. len is set to 0.
Reads signed hexadecimal dword from stream. This is extended version, for simpler usage see text.read.hex_id . Reads hexadecimal digit characters ('0'-'9','a'-'f','A'-'F') until it reaches non-digit, EOF, or until resulting value overflows.
streamHandle of stream from which to read.
maxlenMaximum number of characters to read, including sign. 0 if not specified.
skipblIf 1, procedure first skips initial blank characters (space, tab, EOL). These characters don't count into maxlen size. These characters do not remain on stream in case of error.
allowplusIf 1, plus sign "+" is accepted.
lenPointer to dword variable, that will be set to number of digits read. Ignored if 0. When skipbl=1, skipped initial blank characters don't count.
ERR_HANDLE_EOFEOF reached. len is set to 0.
ERR_OUT_OF_RANGEvalue < -80000000 or value > 7FFFFFFF. In this case sign character and all digit characters remain on stream. len contains number of characters readen until overflow.
ERR_NOT_HEXADECIMALFirst character (after sign) is not a hexadecimal digit. Characters remains on stream. len is set to 0.
ERR_ZERO_VALUEmaxlen=0. len is set to 0.
ERR_INVALID_MODEskipbl > 1. len is set to 0.
Reads signed hexadecimal qword from stream. This is extended version, for simpler usage see text.read.hex_iq . Reads hexadecimal digit characters ('0'-'9','a'-'f','A'-'F') until it reaches non-digit, EOF, or until resulting value overflows.
streamHandle of stream from which to read.
maxlenMaximum number of characters to read, including sign. 0 if not specified.
skipblIf 1, procedure first skips initial blank characters (space, tab, EOL). These characters don't count into maxlen size. These characters do not remain on stream in case of error.
allowplusIf 1, plus sign "+" is accepted.
lenPointer to dword variable, that will be set to number of digits read. Ignored if 0. When skipbl=1, skipped initial blank characters don't count.
ERR_HANDLE_EOFEOF reached. len is set to 0.
ERR_OUT_OF_RANGEvalue < -8000000000000000 or value > 7FFFFFFFFFFFFFFF. In this case sign character and all digit characters remain on stream. len contains number of characters readen until overflow.
ERR_NOT_HEXADECIMALFirst character (after sign) is not a hexadecimal digit. Characters remains on stream. len is set to 0.
ERR_ZERO_VALUEmaxlen=0. len is set to 0.
ERR_INVALID_MODEskipbl > 1. len is set to 0.
+text.skip.chars+stream.peek.byte+stream.peek+stream.skipReads one line of text from stream to buffer. This is simpler version of procedure, for extended version see text.extread.line .
streamStream to read characters from.
bufferPointer to destination buffer, where the characters will be stored.
buflenLength of destination buffer.
CF=1 on error, otherwise EAX = number of characters readen, and ZF=1 if EAX=0 (no characters readen).
ERR_ZERO_SIZEbuflen=0.
ERR_BUFFER_FULLDestiantion buffer is full. Only buflen characters readen, and string in destination buffer is NOT zero-terminated.
ERR_HANDLE_EOFEOF reached without reading anything.
+text.extread.lineReads from stream to buffer all characters which are in given character list. This is simpler version of procedure, for extended version see text.extread.chars .
streamStream to read characters from.
bufferPointer to destination buffer, where the characters will be stored.
buflenLength of destination buffer.
charlistNull-terminated string containing list of characters to read.
CF=1 on error, otherwise EAX = number of characters readen, and ZF=1 if EAX=0 (no characters readen).
ERR_ZERO_SIZEbuflen=0.
ERR_BUFFER_FULLDestiantion buffer is full. Only buflen characters readen, and string in destination buffer is NOT zero-terminated.
ERR_HANDLE_EOFEOF reached without reading anything.
+text.extread.charsReads all characters from stream to buffer, until it hits character from given list of characters. This is simpler version of procedure, for extended version see text.extread.until .
streamStream to read characters from.
bufferPointer to destination buffer, where the characters will be stored.
buflenLength of destination buffer.
charlistNull-terminated string containing list of characters which end reading.
CF=1 on error, otherwise EAX = number of characters readen, and ZF=1 if EAX=0 (no characters readen).
ERR_ZERO_SIZEbuflen=0.
ERR_BUFFER_FULLDestiantion buffer is full. Only buflen characters readen, and string in destination buffer is NOT zero-terminated.
ERR_HANDLE_EOFEOF reached without reading anything.
+text.extread.untilReads specified ASCII string off the stream. If there is another string on stream, then nothing is read and ZF=1 is returned. This procedure should be only used with constant string argument. Use text.fetch.str for non-constant strings.
Reads specified ASCII character off the stream. If there is another character on stream, then nothing is read and ZF=1 is returned.
Reads specified ASCII string off the stream. If there is another string on stream, then nothing is read and ZF=1 is returned. If string is guaranteed to be null terminated, you can use text.fetch instead.
Skips all characters which are in given character list from stream. This is simpler version of procedure, for extended version see text.extskip.chars .
streamStream to skip characters from.
charlistNull-terminated string containing list of characters to read.
Skips all characters from stream, until it reaches character from given character list. This is simpler version of procedure, for extended version see text.extskip.until .
streamStream to skip characters from.
charlistNull-terminated string containing list of characters which not to skip.
Reads one line of text from stream to buffer. This is extended version of procedure, for simpler version see text.read.line .
streamStream to read characters from.
bufferPointer to destination buffer, where the characters will be stored.
buflenLength of destination buffer.
maxlenMaximum number of characters to read. Ignored if 0.
lenPointer to dword variable, which on return holds number of characters readen. This is same value as one returned in EAX, and is only useful on ERR_BUFFER_FULL. Ignored if 0.
CF=1 on error, otherwise EAX = number of characters readen, and ZF=1 if EAX=0 (no characters readen).
ERR_ZERO_SIZEbuflen=0. len is set to 0.
ERR_BUFFER_FULLDestiantion buffer is full. Only buflen characters readen, and string in destination buffer is NOT zero-terminated. len is set to buflen.
ERR_HANDLE_EOFEOF reached without reading anything. len is set to 0.
+text.extread.until+text.fetch.charReads from stream to buffer all characters which are in given character list. This is extended version of procedure, for simpler version see text.read.chars .
streamStream to read characters from.
bufferPointer to destination buffer, where the characters will be stored.
buflenLength of destination buffer.
charlistNull-terminated string containing list of characters to read.
maxlenMaximum number of characters to read. Ignored if 0.
lenPointer to dword variable, which on return holds number of characters readen. This is same value as one returned in EAX, and is only useful on ERR_BUFFER_FULL. Ignored if 0.
CF=1 on error, otherwise EAX = number of characters readen, and ZF=1 if EAX=0 (no characters readen).
ERR_ZERO_SIZEbuflen=0. len is set to 0.
ERR_BUFFER_FULLDestiantion buffer is full. Only buflen characters readen, and string in destination buffer is NOT zero-terminated. len is set to buflen.
ERR_HANDLE_EOFEOF reached without reading anything. len is set to 0.
+stream.peek.byte+str.poschar+stream.skipReads all characters from stream to buffer, until it hits character from given list of characters. This is extended version of procedure, for simpler version see text.read.until .
streamStream to read characters from.
bufferPointer to destination buffer, where the characters will be stored.
buflenLength of destination buffer.
charlistNull-terminated string containing list of characters which end reading.
maxlenMaximum number of characters to read. Ignored if 0.
lenPointer to dword variable, which on return holds number of characters readen. This is same value as one returned in EAX, and is only useful on ERR_BUFFER_FULL. Ignored if 0.
CF=1 on error, otherwise EAX = number of characters readen, and ZF=1 if EAX=0 (no characters readen).
ERR_ZERO_SIZEbuflen=0. len is set to 0.
ERR_BUFFER_FULLDestiantion buffer is full. Only buflen characters readen, and string in destination buffer is NOT zero-terminated. len is set to buflen.
ERR_HANDLE_EOFEOF reached without reading anything. len is set to 0.
+stream.peek.byte+str.poschar+stream.skipSkips all characters which are in given character list from stream. This is extended version of procedure, for simpler version see text.skip.chars .
streamStream to skip characters from.
charlistNull-terminated string containing list of characters to read.
maxlenMaximum number of characters to skip. Ignored if 0.
Skips all characters from stream, until it reaches character from given character list. This is extended version of procedure, for simpler version see text.skip.until .
streamStream to skip characters from.
charlistNull-terminated string containing list of characters which not to skip.
maxlenMaximum number of characters to skip. Ignored if 0.
Outpu Format String is string used in formatted text output functions to specify format of output. Best known example is printf function in C language. In FASMLIB, it is used in text.write.format.
For those unfamiliar with it, format string is just printed to output as-is, except when it contains special marker, usually started with "%" character. This marker is replaced by other string value in output. String by which marker is replaced is specified by type character following marker.
There can be modifiers between "%" and type character, which specify how to display value. For example "%d" displays decimal value, and "%8d" displays decimal value padded to 8 characters.
FASMLIB has it's own format string. Altough it's pretty unpopular to break compatibility with C format strings, these just aren't suitable for usage in assembly language.
FASMLIB format strings is printed as-is, except case when one of two special characters are found:
Backslash is used as escape character. It ensures that character following it is printed as-is. This is only useful to display "%" character. Backslash cannot be last character in string.
Percent sign is used to specify that value of variable is displayed. It is followed by optional modifiers, and type character. Allowed modifiers depend on type.
This is list of FASMLIB type characters:
Prints single character. Argument is dword, but only low-order byte of it is used.
Can be prefixed by "P". Then, argument is pointer to character which is printed. This is useful if pushing character extended to dword is problem.
Prints zero-terminated string. Argument is pointer to string.
Do not use if you aren't sure string is properly zero-terminated. If you aren't sure that string is zero terminated, use "S" instead, and specify buffer size.
Can be prefixed by decimal number, which sets padding length. Then, if string is shorter than padding length, after string is printed, additional spaces are printed to print given number of characters. This is useful to format output to columns.
Examples:
Prints zero-terminated string from buffer of given size. If string isn't zero-terminated within buffer, then only part that is in buffer is printed. This takes two arguments, first is pointer to string, and second is size of string buffer.
If you are sure string is properly zero-terminated, you can use "s" type character instead.
Can be prefixed by decimal number, which sets padding length. Then, if string is shorter than padding length, after string is printed, additional spaces are printed to print given number of characters. This is useful to format output to columns.
Examples:
Prints hexadecimal number. Argument is number to print.
Can be prefixed by decimal number, which sets padding length. Then, if number is shorter than padding length, it is padded with spaces. Number is aligned to right in the padding area. If padding length starts with "0", number is padded with "0" characters instead of spaces.
Optional "P" character may follow to specify argument is pointer to value, instead of value itself. This is useful mainly for non-dword sizes, which are harder to push.
Optional "B", "W", or "Q" can follow to override size of argument. "B" specifies byte, "W" specifies word, and "Q" specifies qword. Both byte and word must be still pushed as dwords, but only low-order portion of dword is taken as actual value. Qword must be pushed as two dwords (if not pointed, using "P"). Size override "D" (for dword) is allowed, but has no effect, it is default option.
Size overrides can be combined with "P", meaning argument is pointer to data of specified size.
Optional "i" character may follow to specify number should be printed as signed.
Examples:
Prints decimal number. Argument is number to print.
Can be prefixed by decimal number, which sets padding length. Then, if number is shorter than padding length, it is padded with spaces. Number is aligned to right in the padding area. If padding length starts with "0", number is padded with "0" characters instead of spaces.
Optional "P" character may follow to specify argument is pointer to value, instead of value itself. This is useful mainly for non-dword sizes, which are harder to push.
Optional "i" character may follow to specify number should be printed as signed. If number is padded, positive numbers are padded by one additional space.
Optional "B", "W", or "Q" can follow to override size of argument. "B" specifies byte, "W" specifies word, and "Q" specifies qword. Both byte and word must be still pushed as dwords, but only low-order portion of dword is taken as actual value. Qword must be pushed as two dwords (if not pointed, using "P"). Size override "D" (for dword) is allowed, but has no effect, it is default option.
Size overrides can be combined with "P", meaning argument is pointer to data of specified size.
Examples:
When FASMLIB is included directly by sources, all it's internal features can be used by project that includes FASMLIB.
This chapter describes those features.
FASMLIB contains set of macros that collect data definitions from various places in source code, and then place them in one place (usually data segment).
There are two of these macros: idata and udata.
idata is used for initialized data. Initialized daat are those whose value is set at compile time.
udata is used for uninitialized data. Value of uninitialized data is unknown when program starts, and so they don't have to be present in executable.
You define these data, just like you would define any macro body:
idata {
mystring db "my string",0
mylabel dd x+5
}
udata {
buffer rb 100
}
Even though udata blocks do allow having initialized data in them, value of data may not be initialized to desired value:
udata {
variable dd 100 ;whooops
}
To actually define all data collected with idata and udata, you use macros IncludeIData and IncludeUData, respectively. These macros must be used AFTER all idata and udata definitions.
IncludeIData must be used in writeable readable place, usually somewhere in data section.
IncludeUData must be used in writeable readable place too, but should be placed after all initialized data definitions. That way, uninitialized data won't waste space in executable. Best place is usually end of data section.
Data blocks are defined in reversed order as they appear in source, and every block is aligned to 4 bytes.
idata and udata blocks beheave like any macro definitions. That means, that if you want to use them inside another macro definition, you must escape { and } symbols:
macro MyMacro {
idata \{
string db 'blah',0
\}
}
idata and udata blocks are moved to IncludeIData and IncludeUData positions during preprocessing stage. That means you cannot enclose them assembly-time conditions:
if 0
idata {
string db 'blah',0 ;data is defined anyway
}
end if
proper way to do this is to place if inside idata block, so it is moved together with data:
idata {
if 0
string db 'blah',0 ;data won't be defined
end if
}
Do not use labels local to namespace defined outside of block. It won't work:
namespace:
idata {
.a dd 0 ;error
}
You can use labels local to namespace defined inside block though:
idata {
namespace:
.a dd 0 ;okay
}
idata and udata are just usual macro definitions, so you can use all macrofeatures inside them. But rather don't do it unless you are sure about what you are doing:
idata {
local length ; <-- macrofeature
pascal_style_string db length
db "this is a veeeery long string and i am lazy to count it's size"
length = $-pascal_style_string-1
}
FASMLIB provides macro libcall for HLL-style calling of it's procedures. It can be used for calling other FASMLIB-style procedures too.
First, required, argument of libcall is name of procedure to call.
libcall fasmlib.init
Rest of arguments are pushed to stack in reversed order, so they act as arguments for called procedure.
Those arguments can be value pushable by "push dword" (label, number, memory-addressed dword, ...), or one of following:
If argument is in form qword value, qword [value], or qword ptr value, then two pushes are used to push value.
If argument is in form addr value, and value cannot be directly pushed (like ebp+8), then argument is loaded to register and pushed. In FASMLIB implementation (unlike many others) used register is preserved, so you can use constructs like this:
libcall proc1, eax, edx, addr local_variable
If argument is quoted string, or it is comma-separated list in brackets, argument is declared as zero-terminated string and its offset is pushed. String is declared in idata block, not directly in code.
libcall stdout.write, "Hello World" libcall str.copy, buffer, BUFFER_SIZE, <"Hello World", 13, 10>, -1 libcall stdout.write, <10,"Usage:",10,"app.exe param1 param2",10>
It isn't possible to push string consisting of single byte, given by it's ASCII value, like this:
libcall stdout.write, <10> ;move to next line
This code will push dword value 10, instead of pushing offset of string that contains character 10. There must always be at least two values in brackets, for argument to be treated as string. Simple workaround:
libcall stdout.write, <"",10> ;move to next line
If argument is in form <libcall ...>, it is nested call. This call is done before pushing value of argument, and return value from call is pushed as argument. For example, following code:
libcall proc1, 1, <libcall proc2, 2>, 3
becomes:
push 3 ;argument 3 for proc1 push 2 ;argument 1 for proc2 call proc2 push eax ;argument 2 for proc1 push 1 ;argument 1 for proc1 call proc1
Additionally, because all FASMLIB procedures return error in CF, this macro allows checking errors on all nested calls with single jc, like this:
libcall proc1, 1, <libcall proc2, 2>, 3 jc .error ;this checks both error from proc1 and proc2
generated code looks like this:
push dword 3 ;for proc1 push dword 2 ;for proc2 call proc2 jnc ..noerr lea esp,[esp+4] ;restore stack jmp ..ret ..noerr: push eax ;for proc1 push dword 1 ;for proc1 call proc1 ..ret:
Sometimes you need to know, if symbol is already defined previously in sources. Doing this in FASM is little tricky. There is "defined" operator, but it checks entire source, not only previous part of source. For example consider following code:
if defined a display 'defined' ;this one will get assembled else display 'not defined' end if a:
That also means following code can't be used:
if ~defined a a: end if
this code is logical paradox (if 'a' is not defined, then 'a' is defined), and it's behavior cannot be clearly defined.
That's why there is ifndef macro. It checks whether symbol is defined previously in sources:
a: ifndef a ;false db 'a not defined' end if ifndef b ;true db 'b not defined' end if b:
Following construct is allowed aswell:
ifndef a a: end if
Argument can be any expression acceptable to defined operator, not just single symbol, see FASM manual for more info.
ifndef (a+b/c)
FASM has display directive to display compile-time output. Unfortunatelly, it is pretty hard to display values of numeric constant using it.
For that purpose, FASMLIB provides disp macro. It provides simple formatted compile-time output.
disp takes at least one argument. If argument is string literal, it is printed as-in.
If argument is in form dec value, then value is displayed as decimal number.
If argument is in form hex value, then value is displayed as hexadecimal number.
disp automatically ends line after printing all arguments.
Example of using disp:
disp 'x=', dec x disp 'value of ABC is ', dec abc, ' (0x', hex ABC, ')'
FASM provides predefined constant %t, which is timedate stamp of compilation time. Turning timedate stamp to real time and date can be problematic tough.
For that reason, FASMLIB provides macro which loads current time and date into symbolic and numeric constants.
Following numeric constants are defined: SECOND (0-59), MINUTE (0-59), HOUR (0-23), DAY (1-31), MONTH (1-12), YEAR.
There are also two symbolic constants defined, to be used with db directive. TIME is day time in format hh:mm:ss. DATE is date in ISO format yyyy-mm-dd.
These symbolic constants are NOT strings. Getting string from %t is unfortunately not possible in FASM. They are just comma-separated byte values, which will compose string when used with db or du.
Condition branch instruction (conditional jumps, je, jna, etc..) can be prefix with CS or DS prefix. These prefixes have special meaning for CPU's branch predicting. Jump prefixed with CS is likely not to be taken, and jump prefixed with DS is likely to be taken. These prefixes are called branch hints.
FASM allows to use form cs jcc somewhere and ds jcc somewhere (where jcc is conditional jump), but this form is not very readable, and you have to remember which prefix has which effect.
For that reason, FASMLIB overloads all conditional jump instructions (jc, jnc, jp, jnp, je, jz, ja, jb, jae, jbe, jg, jl, jge, jle, jne, jnz, jna, jnb, jnae, jnbe, jng, jnl, jnge, jnle, jo, jno) with macro that allows following form:
jcc taken somewhere jcc untaken somewhere
Few examples:
jc untaken error jnz taken loop_again
Interrupting FASM compilation is not as easy as it may seem. It is possible to interrupt compilation during preprocessing, during assembling pass, or during final pass.
FASMLIB provides three pseudo-directives to stop compilation: __preprocess_error, __pass_error, and __assembly_error.
You can place string literal with description of problem into same line behind these pseudo-opcode. It will display in error message then as part of instruction.
This chapter describes FASMLIB file layout. All paths are relative to FASMLIB directory.
src/You can source code of FASMLIB here. There is a ".inc" file and a subdirectory for each module. These subdirectories contain platform-independent part of code.
src/_win32/, src/_linux/These directories contain platform-specific part of code.
doc/You can find TFM and tutorial here.
bin/This directory contains FASMLIB compiled to binary object forms. You can link these to your project.
include/fasm/, include/masm/, include/nasm/These directories contain includes to use FASMLIB from various assemblers. Includes in NASM directory also work in YASM.
examples/fasm/, examples/masm/, examples/nasm/These directories contain examples of fasmlib usage. They may contain subdirectories "win32" and "linux" for platform-specific examples, and subdirectory "portable" for portable examples.
Thanks goes to:
FASMLIB was written mostly under Windows XP, using FASMW editor/compiler, debugged with OllyDbg. Linux version was tested and debugged mostly with strace on Gentoo linux.
FASMLIB project still needs lot of work. Any experienced assembly coder, and everyone who can help will be greatly appreaciated.
Please contact me if you are willing to help.
What I need most:
For now, sole author of FASMLIB is me, Martin Mocko aka. vid. I am 21 years old, and I live in Slovak Republic.
If you have any questions, ideas, bugreports, complaints or anything regarding this library, send them to fasmlib@x86asm.net.
If you want to discuss some FASMLIB issue publicly, please notify me about it with e-mail. I will happily join the discussion.
Any feedback is welcomed.