<article>
<title>cc65 function reference
-<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
-<date>2014-05-26
+<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
+<url url="mailto:greg.king5@verizon.net" name="Greg King">
+<date>2017-09-02
<abstract>
cc65 is a C compiler for 6502 based systems. This function reference describes
<tag/Declaration/Describes the needed header files and declaration of the
function.
<tag/Description/Description of the function.
-<tag/Limits/Limits.
+<tag/Notes/Notes on the function.
<tag/Availability/The availability of the function.
<tag/See also/Other related functions.
<tag/Example/A piece of actual code using the function.
<!-- <item><ref id="_getcolor" name="_getcolor"> -->
<!-- <item><ref id="_getdefdev" name="_getdefdev"> -->
<!-- <item><ref id="_graphics" name="_graphics"> -->
+<item><ref id="_is_cmdline_dos" name="_is_cmdline_dos">
<!-- <item><ref id="_rest_vecs" name="_rest_vecs"> -->
<!-- <item><ref id="_save_vecs" name="_save_vecs"> -->
<!-- <item><ref id="_scroll" name="_scroll"> -->
<item><ref id="cbm_k_open" name="cbm_k_open">
<item><ref id="cbm_k_readst" name="cbm_k_readst">
<item><ref id="cbm_k_save" name="cbm_k_save">
+<item><ref id="cbm_k_scnkey" name="cbm_k_scnkey">
<item><ref id="cbm_k_setlfs" name="cbm_k_setlfs">
<item><ref id="cbm_k_setnam" name="cbm_k_setnam">
+<item><ref id="cbm_k_talk" name="cbm_k_talk">
+<item><ref id="cbm_k_udtim" name="cbm_k_udtim">
<item><ref id="cbm_k_unlsn" name="cbm_k_unlsn">
<!-- <item><ref id="cbm_load" name="cbm_load"> -->
<!-- <item><ref id="cbm_open" name="cbm_open"> -->
<!-- <item><ref id="cbm_save" name="cbm_save"> -->
<!-- <item><ref id="cbm_write" name="cbm_write"> -->
<!-- <item><ref id="get_tv" name="get_tv"> -->
+<item><ref id="kbrepeat" name="kbrepeat">
</itemize>
(incomplete)
<sect1><tt/cc65.h/<label id="cc65.h"><p>
-<!-- <itemize> -->
+<itemize>
<!-- <item><ref id="cc65_cos" name="cc65_cos"> -->
<!-- <item><ref id="cc65_idiv32by16r16" name="cc65_idiv32by16r16"> -->
<!-- <item><ref id="cc65_imul16x16r32" name="cc65_imul16x16r32"> -->
<!-- <item><ref id="cc65_umul16x16r32" name="cc65_umul16x16r32"> -->
<!-- <item><ref id="cc65_umul16x8r32" name="cc65_umul16x8r32"> -->
<!-- <item><ref id="cc65_umul8x8r16" name="cc65_umul8x8r16"> -->
-<!-- </itemize> -->
+<item><ref id="doesclrscrafterexit" name="doesclrscrafterexit">
+</itemize>
(incomplete)
</itemize>
+<sect1><tt/gamate.h/<label id="gamate.h"><p>
+
+<!-- <itemize> -->
+<!-- <item><ref id="get_tv" name="get_tv"> -->
+<!-- <item><ref id="waitvblank" name="waitvblank"> -->
+<!-- </itemize> -->
+
+(incomplete)
+
+
<sect1><tt/geos.h/<label id="geos.h"><p>
(incomplete)
(incomplete)
+<sect1><tt/lz4.h/<label id="lz4.h"><p>
+
+<itemize>
+<item><ref id="decompress_lz4" name="decompress_lz4">
+</itemize>
+
+
<sect1><tt/modload.h/<label id="modload.h"><p>
<itemize>
<!-- <itemize> -->
<!-- <item><ref id="get_tv" name="get_tv"> -->
-<!-- <item><ref id="waitvblank" name="waitvblank"> -->
+<!-- <item><ref id="waitvsync" name="waitvsync"> -->
<!-- </itemize> -->
(incomplete)
It does not declare any functions.
+<sect1><tt/pce.h/<label id="pce.h"><p>
+
+<!-- <itemize> -->
+<!-- <item><ref id="get_tv" name="get_tv"> -->
+<!-- <item><ref id="waitvblank" name="waitvblank"> -->
+<!-- </itemize> -->
+
+(incomplete)
+
+
<sect1><tt/peekpoke.h/<label id="peekpoke.h"><p>
<itemize>
</itemize>
+<sect1><tt/pen.h/<label id="pen.h"><p>
+
+<!-- <itemize> -->
+<!-- <item><ref id="pen_adjust" name="pen_adjust"> -->
+<!-- <item><ref id="pen_calibrate" name="pen_calibrate"> -->
+<!-- </itemize> -->
+
+(incomplete)
+
+
<sect1><tt/pet.h/<label id="pet.h"><p>
(incomplete)
<tag/Notes/<itemize>
<item>The minimum blocksize that can be added is 6 bytes; the function will
ignore smaller blocks.
+<item>The function is available only as a fastcall function; so, it may be used
+only in the presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
<tag/Notes/<itemize>
<item>Passing a pointer to a block that was is not the result of one of the
allocation functions, or that has been free'd will give unpredicable results.
+<item>The function is available only as a fastcall function; so, it may be used
+only in the presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
<descrip>
<tag/Function/Return the total available space on the heap.
<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/
-<tag/Declaration/<tt/size_t __fastcall__ _heapmemavail (void);/
+<tag/Declaration/<tt/size_t _heapmemavail (void);/
<tag/Description/The function returns the total number of bytes available on
the heap.
<tag/Notes/<itemize>
</quote>
+<sect1>_is_cmdline_dos<label id="_is_cmdline_dos"><p>
+
+<quote>
+<descrip>
+<tag/Function/Determines whether the underlying DOS supports command line arguments.
+<tag/Header/<tt/<ref id="atari.h" name="atari.h">/
+<tag/Declaration/<tt/unsigned char _is_cmdline_dos (void);/
+<tag/Description/The function returns 0 if the DOS doesn't support command line arguments.
+It returns 1 if it does.
+<tag/Availability/cc65 (<tt/atari/ and <tt/atarixl/ platforms)
+</descrip>
+</quote>
+
+
<sect1>_poserror<label id="_poserror"><p>
<quote>
<tag/Header/<tt/<ref id="atmos.h" name="atmos.h">/
<tag/Declaration/<tt/void __fastcall__ atmos_load(const char* name);/
<tag/Description/<tt/atmos_load/ reads a memory block from tape.
+<tag/Notes/<itemize>
+<item>The function is available only as a fastcall function; so, it may be used
+only in the presence of a prototype.
+</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="atmos_save" name="atmos_save">
<tag/Header/<tt/<ref id="atmos.h" name="atmos.h">/
<tag/Declaration/<tt/void __fastcall__ atmos_save(const char* name, const void* start, const void* end);/
<tag/Description/<tt/atmos_save/ writes a memory block to tape.
+<tag/Notes/<itemize>
+<item>The function is available only as a fastcall function; so, it may be used
+only in the presence of a prototype.
+</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="atmos_load" name="atmos_load">
<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/
<tag/Declaration/<tt/void* __fastcall__ bsearch (const void* key,
const void* base, size_t n, size_t size,
-int (*cmp) (const void*, const void*));/
+int __fastcall__ (* cmp) (const void*, const void*));/
<tag/Description/<tt/bsearch/ searches a sorted array for a member that
matches the one pointed to by <tt/key/. <tt/base/ is the address of the array,
<tt/n/ is the number of elements, <tt/size/ the size of an element and <tt/cmp/
return one of the members.
<item>The function is only available as fastcall function, so it may only
be used in presence of a prototype.
+<item>The function to which <tt/cmp/ points must have the <tt/fastcall/ calling
+convention.
</itemize>
<tag/Availability/ISO 9899
<tag/See also/
</quote>
+<sect1>cbm_k_scnkey<label id="cbm_k_scnkey"><p>
+
+<quote>
+<descrip>
+<tag/Function/Scan the keyboard matrix.
+<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
+<tag/Declaration/<tt/void cbm_k_scnkey (void);/
+<tag/Description/This function looks at the switches in the keyboard, to see
+if any of them are being pressed. If they are, then code numbers for them are
+stored in RAM. Other functions use those numbers to input text. Normally,
+the keyboard is scanned by the Kernal's Interrupt Service Routine. But, if
+you divert the "Jiffy interrupt" to a C-code ISR, then that ISR must call this
+function, in order to provide input from the keyboard.
+<tag/Availability/cc65
+<tag/See also/
+<ref id="cbm_k_getin" name="cbm_k_getin">,
+<ref id="cbm_k_udtim" name="cbm_k_udtim">,
+<ref id="cgetc" name="cgetc">,
+<!-- <ref id="getc" name="getc"> -->
+<!-- <ref id="getchar" name="getchar"> -->
+<tag/Example/None.
+</descrip>
+</quote>
+
+
<sect1>cbm_k_setlfs<label id="cbm_k_setlfs"><p>
<quote>
</quote>
+<sect1>cbm_k_udtim<label id="cbm_k_udtim"><p>
+
+<quote>
+<descrip>
+<tag/Function/Update the Jiffy clock.
+<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
+<tag/Declaration/<tt/void cbm_k_udtim (void);/
+<tag/Description/This function adds one count to the Jiffy clock. That clock
+counts sixtieths of a second. It is used by the library's <tt/clock()/
+function. Normally, the Jiffy clock is updated by the Kernal's Interrupt
+Service Routine. But, if you divert the "Jiffy interrupt" to a C-code ISR,
+then that ISR must call this function, in order to keep the clock valid.
+<tag/Availability/cc65
+<tag/See also/
+<ref id="cbm_k_scnkey" name="cbm_k_scnkey">,
+<ref id="clock" name="clock">
+<tag/Example/None.
+</descrip>
+</quote>
+
+
<sect1>cbm_k_unlsn<label id="cbm_k_unlsn"><p>
<quote>
<tag/Header/<tt/<ref id="conio.h" name="conio.h">/
<tag/Declaration/<tt/char cgetc (void);/
<tag/Description/The function reads a character from the keyboard. If there is
-no character available, <tt/cgetc/ waits until the user presses a key. If the
+no character available, <tt/cgetc()/ waits until the user presses a key. If the
cursor is enabled by use of the <tt/cursor/ function, a blinking cursor is
displayed while waiting.
<tag/Notes/<itemize>
-<item>If the system supports a keyboard buffer, <tt/cgetc/ will fetch a key
-from this buffer and wait only if the buffer is empty.
+<item>If the system supports a keyboard buffer, <tt/cgetc()/ will fetch a key
+from that buffer; and, wait only if the buffer is empty.
+<item>The keyboard must be scanned periodically, in order for this function to
+see anything that you type. (See the description of <tt/cbm_k_scnkey()/.)
</itemize>
<tag/Availability/cc65
<tag/See also/
+<ref id="cbm_k_scnkey" name="cbm_k_scnkey">,
<ref id="cursor" name="cursor">,
<ref id="kbhit" name="kbhit">
<tag/Example/None.
<tag/Header/<tt/<ref id="time.h" name="time.h">/
<tag/Declaration/<tt/clock_t clock (void);/
<tag/Description/The <tt/clock/ function returns an approximaton of processor
-time used by the program. The time is returned in implementation defined
+time used by the program. The time is returned in implementation-defined
units. It can be converted to seconds by dividing by the value of the macro
<tt/CLOCKS_PER_SEC/.
<tag/Notes/<itemize>
-<item>Since the machines, cc65 generated programs run on, cannot run multiple
-processes, the function will actually return the time since some
-implementation defined point in the past.
+<item>Since the machines that cc65-generated programs run on cannot run multiple
+processes, the function actually will return the time since some
+implementation-defined point in the past.
+<item>The Jiffy clock must be "running", in order for this function to return
+changing values. (See the description of <tt/cbm_k_udtim()/.)
</itemize>
<tag/Availability/ISO 9899
<tag/See also/
+<ref id="cbm_k_udtim" name="cbm_k_udtim">,
<ref id="time" name="time">
<tag/Example/None.
</descrip>
</quote>
+<sect1>decompress_lz4<label id="decompress_lz4"><p>
+
+<quote>
+<descrip>
+<tag/Function/Uncompress a LZ4-compressed buffer.
+<tag/Header/<tt/<ref id="lz4.h" name="lz4.h">/
+<tag/Declaration/<tt/void decompress_lz4 (const unsigned char* src, unsigned char* const dst, const unsigned short uncompressed_size);/
+<tag/Description/<tt/decompress_lz4/ uncompresses a LZ4-compressed buffer.
+<tag/Notes/<itemize>
+<item>Use LZ4_compress_HC with compression level 16 for best compression.
+</itemize>
+<tag/Availability/cc65
+<tag/Example/None.
+</descrip>
+</quote>
+
+
<sect1>div<label id="div"><p>
<quote>
</quote>
+<sect1>doesclrscrafterexit<label id="doesclrscrafterexit"><p>
+
+<quote>
+<descrip>
+<tag/Function/Determines whether the screen is going to be cleared after program exit.
+<tag/Header/<tt/<ref id="cc65.h" name="cc65.h">/
+<tag/Declaration/<tt/unsigned char doesclrscrafterexit (void);/
+<tag/Description/The function returns zero if the screen won't be cleared immediately after
+program termination. It returns a non-zero value if it will.
+<tag/Notes/<itemize>
+<item>Some systems, maybe depending on configuration, immediately clear the screen
+after a program exits. Therefore it might be difficult to read
+the last messages printed by the program prior to its exit. This function can be used
+to decide if a delay or wait for a key press should be executed when then program
+exits.
+</itemize>
+<tag/Availability/cc65
+<tag/Example/<verb>
+/* Hello World */
+#include <stdio.h>
+#include <unistd.h>
+#include <cc65.h>
+int main(void)
+{
+ printf("Hello World\n");
+ if (doesclrscrafterexit())
+ sleep(5);
+ return 0;
+}
+</verb>
+</descrip>
+</quote>
+
+
<sect1>em_commit<label id="em_commit"><p>
<quote>
<item>When compiling without <tt/-Os/, the function is only available as
fastcall function, so it may only be used in presence of a prototype.
</itemize>
-<tag/Availability/cc65
+<tag/Availability/ISO 9899
<tag/See also/
<ref id="isalnum" name="isalnum">,
<ref id="isalpha" name="isalpha">,
<quote>
<descrip>
-<tag/Function/Check if a given character is a a white-space character.
+<tag/Function/Check if a given character is a white-space character.
<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/
<tag/Declaration/<tt/int __fastcall__ isspace (int c);/
<tag/Description/The function returns a non zero value if the given argument
</quote>
+<sect1>kbrepeat<label id="kbrepeat"><p>
+
+<quote>
+<descrip>
+<tag/Function/Set the keyboard repeat mode.
+<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
+<tag/Declaration/<tt/unsigned char __fastcall__ kbrepeat (unsigned char mode);/
+<tag/Description/This function changes which keys have automatic repeat when
+being held down for a certain time. Possible values are <tt/KBREPEAT_CURSOR/
+(repeat only cursor-related keys), <tt/KBREPEAT_NONE/ (no repeat for any
+keys), and <tt/KBREPEAT_ALL/ (repeat all keys). The old mode is returned, so
+it can be restored later.
+<tag/Notes/<itemize>
+<item>The function is available only as a fastcall function; so, it may be used
+only in the presence of a prototype.
+</itemize>
+<tag/Availability/cc65
+<tag/Example/None.
+</descrip>
+</quote>
+
+
<sect1>labs<label id="labs"><p>
<quote>
<tag/Notes/<itemize>
<item>The pointer passed as parameter is the pointer to the module memory,
not the pointer to the control structure.
+<item>The function is available only as a fastcall function; so, it may be used
+only in the presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
<descrip>
<tag/Function/Load a relocatable module.
<tag/Header/<tt/<ref id="modload.h" name="modload.h">/
-<tag/Declaration/<tt/unsigned char mod_load (struct mod_ctrl* ctrl);/
+<tag/Declaration/<tt/unsigned char __fastcall__ mod_load (struct mod_ctrl* ctrl);/
<tag/Description/The function will load a code module into memory and relocate
it. The function will return an error code. If <tt/MLOAD_OK/ is returned, the
outgoing fields in the passed <tt/mod_ctrl/ struct contain information about
<tag/Notes/<itemize>
<item>The <htmlurl url="ld65.html" name="ld65"> linker is needed to create
relocatable o65 modules for use with this function.
+<item>The function is available only as a fastcall function; so, it may be used
+only in the presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
<descrip>
<tag/Function/Unload a mouse driver.
<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/
-<tag/Declaration/<tt/unsigned char __fastcall__ mouse_unload (void);/
+<tag/Declaration/<tt/unsigned char mouse_unload (void);/
<tag/Description/The function unloads a loaded mouse driver and frees all
memory allocated for the driver.
<tag/Notes/<itemize>
<tag/Function/Sort an array.
<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/
<tag/Declaration/<tt/void __fastcall__ qsort (void* base, size_t count,
-size_t size, int (*compare) (const void*, const void*));/
+size_t size, int __fastcall__ (* compare) (const void*, const void*));/
<tag/Description/<tt/qsort/ sorts an array according to a given compare
function <tt/compare/. <tt/base/ is the address of the array, <tt/count/
is the number of elements, <tt/size/ the size of an element and <tt/compare/
the function is undefined.
<item>The function is only available as fastcall function, so it may only
be used in presence of a prototype.
+<item>The function to which <tt/compare/ points must have the <tt/fastcall/
+calling convention.
</itemize>
<tag/Availability/ISO 9899
<tag/See also/
<tag/Description/<tt/reset_brk/ resets the break vector to the value it had
before a call to <tt/set_brk/.
<tag/Notes/<itemize>
-<item>Since <tt/<ref id="set_brk" name="set_brk">/ installs an exit handler,
-it is not strictly necessary to call this function as part of the cleanup when
-the program ends.
+<item>The break vector is reset on program termination, so it's not strictly
+necessary to call this function as a part of your clean-up when exitting the program.
</itemize>
<tag/Availability/cc65
<tag/See also/
<tag/Declaration/<tt/void reset_irq (void);/
<tag/Description/<tt/reset_irq/ resets the C level interrupt request vector.
<tag/Notes/<itemize>
-<item>The original IRQ vector is restored on program termination even without
-calling this function.
+<item>The interrupt vector is reset on program termination, so it's not strictly
+necessary to call this function as a part of your clean-up when exitting the program.
</itemize>
<tag/Availability/cc65
<tag/See also/
<item>The <tt/brk_pc/ variable points to the <tt/BRK/ instruction. If you want
the continue with the interrupted code, you have to adjust <tt/brk_pc/,
otherwise the <tt/BRK/ instruction will get executed over and over again.
-<item>Since <tt/set_brk/ installs an exit handler, it is not strictly necessary
-to call <tt/<ref id="reset_brk" name="reset_brk">/ as part of the cleanup when
-the program terminates.
+<item>The break vector is reset on program termination, so it's not strictly
+necessary to call <tt/<ref id="reset_brk" name="reset_brk">/ as a part of your
+clean-up when exitting the program.
</itemize>
<tag/Availability/cc65
<tag/See also/
was interrupted. Be careful however not to call C library functions, and do not
enable stack checks for the handler function or any other function called from
it.
-<item>The interrupt vector is reset on function termination, so it's not
-strictly necessary to call <tt/<ref id="reset_irq" name="reset_irq">/ as part
-of the cleanup when the program terminates.
+<item>The interrupt vector is reset on program termination, so it's not strictly
+necessary to call <tt/<ref id="reset_irq" name="reset_irq">/ as a part of your
+clean-up when exitting the program.
</itemize>
<tag/Availability/cc65
<tag/See also/
name="tgi_init">, so if a driver is linked statically to an application,
switching into and out of graphics mode will not restore the original aspect
ratio.
+<item>The function is available only as a fastcall function; so, it may be used
+only in the presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
projects / cc65 / blobdiff