cc65 function reference

Ullrich von Bassewitz,
Greg King

2017-09-02
cc65 is a C compiler for 6502 based systems. This function reference describes the C functions available in the standard library.

1. Introduction

2. Functions by header file

3. Alphabetical function reference


1. Introduction

cc65 is a C compiler for 6502 based systems. It implements a subset of the ISO C standard plus additional functions specially crafted for 6502 systems or just some of the supported machines. This function refrence describes the available functions together with any limitations.

For an overview about the available libraries, their purpose, and any differences to the ISO standard, please have a look at the cc65 Library Overview.

Note: Standard C functions are listed here, but not described in detail. Since these functions behave identical on all standard compliant systems, they are described in any book covering standard C.

Each entry for a function contains a detailed description

Function

Summary of what function does.

Header

The header file that contains the declaration.

Declaration

Describes the needed header files and declaration of the function.

Description

Description of the function.

Notes

Notes on the function.

Availability

The availability of the function.

See also

Other related functions.

Example

A piece of actual code using the function.

2. Functions by header file

2.1 6502.h

2.2 apple2.h

2.3 apple2enh.h

2.4 assert.h

2.5 atari.h

(incomplete)

2.6 atmos.h

(incomplete)

2.7 c128.h

2.8 c16.h

(incomplete)

2.9 c64.h

2.10 cbm.h

(incomplete)

2.11 cbm510.h

2.12 cbm610.h

2.13 cc65.h

(incomplete)

2.14 conio.h

2.15 ctype.h

2.16 dbg.h

(incomplete)

2.17 dio.h

Low-level disk I/O API.

2.18 dirent.h

(incomplete)

2.19 em.h

2.20 errno.h

(incomplete)

2.21 fcntl.h

2.22 gamate.h

(incomplete)

2.23 geos.h

(incomplete)

2.24 joystick.h

2.25 locale.h

2.26 lynx.h

(incomplete)

2.27 lz4.h

2.28 modload.h

2.29 mouse.h

2.30 nes.h

(incomplete)

2.31 o65.h

The o65.h header file contains structure and constant definitions that may be used when dealing with files in the o65 format. It does not declare any functions.

2.32 pce.h

(incomplete)

2.33 peekpoke.h

2.34 pen.h

(incomplete)

2.35 pet.h

(incomplete)

2.36 plus4.h

(incomplete)

2.37 serial.h

The serial.h header file contains definitions for initializing serial communication.

2.38 setjmp.h

2.39 signal.h

2.40 stdarg.h

(incomplete)

2.41 stdbool.h

(incomplete)

2.42 stddef.h

2.43 stdio.h

(incomplete)

2.44 stdlib.h

(incomplete)

2.45 string.h

(incomplete)

2.46 tgi.h

2.47 time.h

(incomplete)

2.48 unistd.h

(incomplete)

2.49 vic20.h

(incomplete)

2.50 zlib.h

(incomplete)

3. Alphabetical function reference

3.1 _DE_ISDIR

Function

Determine if a directory entry specifies a directory.

Header

dirent.h

Declaration

int _DE_ISDIR(unsigned char type);

Description

The function is called with the type of a directory entry taken from a struct dirent and returns true if the entry designates a directory.

Notes

  • The function is actually a macro.

Availability

cc65

See also

_DE_ISLBL, _DE_ISLNK, _DE_ISREG

Example

None.

3.2 _DE_ISLBL

Function

Determine if a directory entry specifies a disk label.

Header

dirent.h

Declaration

int _DE_ISLBL(unsigned char type);

Description

The function is called with the type of a directory entry taken from a struct dirent and returns true if the entry designates a disk label.

Notes

  • The function is actually a macro.

Availability

cc65

See also

_DE_ISDIR, _DE_ISLNK, _DE_ISREG

Example

None.

3.3 _DE_ISLNK

Function

Determine if a directory entry specifies a link.

Header

dirent.h

Declaration

int _DE_ISLNK(unsigned char type);

Description

The function is called with the type of a directory entry taken from a struct dirent and returns true if the entry designates a link.

Notes

  • The function is actually a macro.

Availability

cc65

See also

_DE_ISDIR, _DE_ISLBL, _DE_ISREG

Example

None.

3.4 _DE_ISREG

Function

Determine if a directory entry specifies a regular file.

Header

dirent.h

Declaration

int _DE_ISREG(unsigned char type);

Description

The function is called with the type of a directory entry taken from a struct dirent and returns true if the entry designates a regular file.

Notes

  • The function is actually a macro.
  • A "regular file" means anything with data in it. This might still mean that special processing is needed, when accessing the file. Relative files of the CBM systems are classified as being "regular" files, for example.

Availability

cc65

See also

_DE_ISDIR, _DE_ISLBL, _DE_ISLNK

Example

None.

3.5 _heapadd

Function

Add a block to the heap.

Header

stdlib.h

Declaration

void __fastcall__ _heapadd (void* mem, size_t size);

Description

The function adds a block of raw memory to the heap.

Notes

  • The minimum blocksize that can be added is 6 bytes; the function will ignore smaller blocks.
  • The function is available only as a fastcall function; so, it may be used only in the presence of a prototype.

Availability

cc65

See also

_heapblocksize, _heapmaxavail, _heapmemavail, calloc, free, malloc, realloc

Example

None.

3.6 _heapblocksize

Function

Return the size of an allocated block.

Header

stdlib.h

Declaration

size_t __fastcall__ _heapblocksize (const void* block);

Description

The function returns the size of a block that must have previously been allocated by malloc, calloc or realloc.

Notes

  • 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.
  • The function is available only as a fastcall function; so, it may be used only in the presence of a prototype.

Availability

cc65

See also

_heapadd, _heapmaxavail, _heapmemavail, calloc, free, malloc, realloc

Example

None.

3.7 _heapmaxavail

Function

Return the largest block that is available on the heap.

Header

stdlib.h

Declaration

size_t _heapmaxavail (void);

Description

The function returns the size of the largest block that may be allocated from the heap using malloc.

Availability

cc65

See also

_heapadd, _heapblocksize, _heapmemavail, calloc, free, malloc, realloc

Example

None.

3.8 _heapmemavail

Function

Return the total available space on the heap.

Header

stdlib.h

Declaration

size_t _heapmemavail (void);

Description

The function returns the total number of bytes available on the heap.

Notes

  • This function is of less use than usually assumed, since the returned heap space may be available but not in one block. So even if this function says that several times more heap space is available than needed, malloc may still return NULL.

Availability

cc65

See also

_heapadd, _heapblocksize, _heapmaxavail, calloc, free, malloc, realloc

Example

None.

3.9 _is_cmdline_dos

Function

Determines whether the underlying DOS supports command line arguments.

Header

atari.h

Declaration

unsigned char _is_cmdline_dos (void);

Description

The function returns 0 if the DOS doesn't support command line arguments. It returns 1 if it does.

Availability

cc65 (atari and atarixl platforms)

3.10 _poserror

Function

Print an error message for the error in _oserror.

Header

stdio.h

Declaration

void __fastcall__ _poserror (const char* msg);

Description

_poserror prints an error message to stderr. If msg is not NULL and not an empty string, it is printed followed by a colon and a blank. Then the error message for the current contents of _oserror are printed followed by a newline. The message output is the same as returned by _stroserror with an argument of _oserror.

Notes

  • Since operating system specific error code are - you guessed it - operating system specific, the value in _oserror and the message that is printed depends on the cc65 target.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

_stroserror, perror

Example

None.

3.11 _randomize

Function

Initialize the pseudo random number generator.

Header

stdlib.h

Declaration

void _randomize (void);

Description

The function initializes the random number generator with a seed derived from fast changing hardware events, so the seed itself can be considered random to a certain degree.

Notes

  • The randomness of the seed depends on the machine hardware.

Availability

cc65

See also

rand, srand

Example

None.

3.12 _stroserror

Function

Return a string describing an OS specific error code.

Header

string.h

Declaration

const char* __fastcall__ _stroserror (unsigned char errcode);

Description

_stroserror will return a string describing the given operating system specific error code.

Notes

  • Since operating system specific error code are - you guessed it - operating system specific, the parameter and the string returned depend on the cc65 target.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

strerror

Example

None.

3.13 _swap

Function

Swap the contents of memory areas.

Header

stdlib.h

Declaration

void __fastcall__ _swap (void* p, void* q, size_t size);

Description

_swap will swap (exchange) the contents of the two memory areas pointed to by p and q. Both memory areas are assumed to be size bytes in size.

Notes

  • The memory areas may not overlap, otherwise the results are undefined.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

memcpy, memmove

Example

None.

3.14 _sys

Function

Call a subroutine passing register values.

Header

6502.h

Declaration

void __fastcall__ _sys (struct regs* r);

Description

The function will call the subroutine at the address specified in the pc member of the passed regs structure. All registers and the CPU flags are set to the values given in the regs structure. On return from the subroutine, the new values of the registers and flags are stored back overwriting the old values.

Notes

  • Bits 4 and 5 of the flags value in the regs structure are ignored when calling the subroutine (they are unchanged from their current values).
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

Example

None.

3.15 BRK

Function

Insert a 6502 BRK instrunction into the code.

Header

6502.h

Declaration

void BRK (void);

Description

The function will insert a 6502 BRK instruction into the code which may be used to trigger a debugger.

Notes

  • The function is actually a macro.
  • The inserted instruction may lead to unexpected results if no debugger is present.

Availability

cc65

See also

CLI, SEI

Example

None.

3.16 CLI

Function

Insert a 6502 CLI instrunction into the code.

Header

6502.h

Declaration

void CLI (void);

Description

The function will insert a 6502 CLI instruction into the code, so interrupts are enabled. Enabling interrupts has no effects if they are already enabled (the default).

Notes

  • The function is actually a macro.
  • Disabling interrupts may lead to unexpected results.

Availability

cc65

See also

BRK, SEI

Example

None.

3.17 PEEK

Function

Read a byte from memory.

Header

peekpoke.h

Declaration

unsigned char PEEK (unsigned addr);

Description

The function will read the absolute memory given by addr and return the value read.

Notes

  • The function is actually a macro.
  • This function depends highly on the platform and environment.

Availability

cc65

See also

PEEKW, POKE

Example

None.

3.18 PEEKW

Function

Read a word (two bytes) from memory.

Header

peekpoke.h

Declaration

unsigned PEEKW (unsigned addr);

Description

The function will read the absolute memory given by addr and return the value read. The byte read from the higher address is the high byte of the return value.

Notes

  • The function is actually a macro.
  • This function depends highly on the platform and environment.
  • The order in which the two bytes are read is unspecified and may depend of the address expression used.

Availability

cc65

See also

PEEK, POKE

Example

None.

3.19 POKE

Function

Write a byte to memory.

Header

peekpoke.h

Declaration

void POKE (unsigned addr, unsigned char val);

Description

The function writes the value val to the absolute memory address given by addr.

Notes

  • The function is actually a macro.
  • This function depends highly on the platform and environment.
  • Careless use will cause the program to act strange or may crash the machine.

Availability

cc65

See also

PEEK, POKEW

Example

None.

3.20 POKEW

Function

Write a word (two bytes) to memory.

Header

peekpoke.h

Declaration

void POKEW (unsigned addr, unsigned val);

Description

The function writes the value val to the absolute memory address given by addr. The low byte of val is written to the addr, the high byte is written to addr+1.

Notes

  • The function is actually a macro.
  • This function depends highly on the platform and environment.
  • Careless use will cause the program to act strange or may crash the machine.
  • The order in which the two bytes are written is unspecified and may depend of the address expression used.

Availability

cc65

See also

PEEK, POKE

Example

None.

3.21 SEI

Function

Insert a 6502 SEI instrunction into the code.

Header

6502.h

Declaration

void SEI (void);

Description

The function will insert a 6502 SEI instruction into the code, so interrupts are disabled. Note that non maskable interrupts cannot be disabled.

Notes

  • The function is actually a macro.
  • Disabling interrupts may lead to unexpected results.

Availability

cc65

See also

BRK, CLI

Example

None.

3.22 abort

Function

Terminates a program abnormally.

Header

stdlib.h

Declaration

void abort (void);

Description

abort raises SIGABRT, writes a termination message on stderr, then terminates the program with an exit code of 3.

Availability

ISO 9899

See also

assert, exit, raise

Example

None.

3.23 abs

Function

Returns the absolute value of an integer.

Header

stdlib.h

Declaration

int __fastcall__ abs (int v);

Description

abs returns the absolute value of the argument passed to the function.

Notes

  • The return value is undefined if INT_MIN is passed to the function.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

labs

Example

None.

3.24 assert

Function

Test a condition and possibly abort.

Header

assert.h

Declaration

void assert (int cond);

Description

assert is a macro that expands to a id statement. If the condition evaluates t zero (false), assert prints a message on stderr and aborts the program.

Notes

  • The function is actually a macro.

Availability

ISO 9899

See also

abort, exit

Example

None.

3.25 atexit

Function

Register an exit function.

Header

stdlib.h

Declaration

int __fastcall__ atexit (void (*exitfunc) (void));

Description

atexit registers the function pointed to by exitfunc as an exit function. Exit functions are called when the program terminates, they are called in LIFO order (the last function registered is called first). atexit returns zero on success and a nonzero value on failure.

Notes

  • A maximum of 5 exit functions can be registered.
  • There is no way to unregister an exit function.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

abort, exit

Example

None.

3.26 atmos_load

Function

Load Atmos tape.

Header

atmos.h

Declaration

void __fastcall__ atmos_load(const char* name);

Description

atmos_load reads a memory block from tape.

Notes

  • The function is available only as a fastcall function; so, it may be used only in the presence of a prototype.

Availability

cc65

See also

atmos_save

Example

None.

3.27 atmos_save

Function

Save Atmos tape.

Header

atmos.h

Declaration

void __fastcall__ atmos_save(const char* name, const void* start, const void* end);

Description

atmos_save writes a memory block to tape.

Notes

  • The function is available only as a fastcall function; so, it may be used only in the presence of a prototype.

Availability

cc65

See also

atmos_load

Example

atmos_save("hires", 0xa000, 0xc000);

3.28 atoi

Function

Convert a string to an integer.

Header

stdlib.h

Declaration

int __fastcall__ atoi (const char* s);

Description

atoi converts the given string into an integer. Conversion stops as soon as any invalid character is encountered.

Notes

  • There is no way to detect any conversion errors.
  • The function does not check for an numerical overflow when converting.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

atol, itoa, ltoa, ultoa, utoa

Example

None.

3.29 atol

Function

Convert a string to a long integer.

Header

stdlib.h

Declaration

long __fastcall__ atol (const char* s);

Description

atol converts the given string into a long integer. Conversion stops as soon as any invalid character is encountered.

Notes

  • There is no way to detect any conversion errors.
  • The function does not check for an numerical overflow when converting.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

atoi, itoa, ltoa, ultoa, utoa

Example

None.

3.30 bgcolor

Function

Set the background text color.

Header

conio.h

Declaration

unsigned char __fastcall__ bgcolor (unsigned char color);

Description

The function will set a new background color and return the old (current) one. The background color is valid for the whole text output area of the screen, not just for new text.

Notes

  • Background colors are system dependent. The function may have no effect on systems where the background color cannot be changed.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

bordercolor, textcolor

Example

None.

3.31 bordercolor

Function

Set the border (frame) color.

Header

conio.h

Declaration

unsigned char __fastcall__ bordercolor (unsigned char color);

Description

The function will set a new border color. It returns the old (current) border color.

Notes

  • Border colors are system dependent. The function may have no effect on systems where the border color cannot be changed.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

bgcolor, textcolor

Example

None.

3.32 bsearch

Function

Do a binary search in a sorted array.

Header

stdlib.h

Declaration

void* __fastcall__ bsearch (const void* key, const void* base, size_t n, size_t size, int __fastcall__ (* cmp) (const void*, const void*));

Description

bsearch searches a sorted array for a member that matches the one pointed to by key. base is the address of the array, n is the number of elements, size the size of an element and cmp the function used to compare the members against the key. The function returns a pointer to the member found, or NULL if there was no match.

Notes

  • The contents of the array must be sorted in ascending order according to the compare function given.
  • If there are multiple members that match the key, the function will return one of the members.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function to which cmp points must have the fastcall calling convention.

Availability

ISO 9899

See also

qsort

Example

None.

3.33 bzero

Function

Fill a memory area with zeroes.

Header

string.h

Declaration

void __fastcall__ bzero (void* p, size_t count);

Description

bzero fills the memory area pointed to by p with zero.

Notes

  • The function is non standard and therefore only available in non ANSI mode. You should use memset instead.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

_swap, memcpy, memmove, memset,

Example

None.

3.34 c64mode

Function

Switch the C128 into C64 compatible mode.

Header

c128.h

Declaration

void c64mode (void);

Description

The function will cause the machine to reboot into C64 mode.

Notes

  • The function is specific to the C128.
  • The function will not return to the caller.

Availability

C128

Example

None.

3.35 calloc

Function

Allocate and clear memory.

Header

stdlib.h

Declaration

void* __fastcall__ calloc (size_t n, size_t size);

Description

calloc allocates memory for an array of n elements of size size, clears the whole block with binary zeroes and returns a pointer to it. On error (not enough memory available), calloc returns NULL.

Notes

  • Clearing the memory may not have the expected effect on all platforms: pointers in the block may not be NULL and floating point variables may not be zero (0.0). In other words: The "clearing" effect of this function should be used with care for portable programs.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

_heapadd, _heapblocksize, _heapmaxavail, _heapmemavail, free, malloc, realloc

Example

None.

3.36 cbm_k_acptr

Function

Input byte from serial bus

Header

cbm.h

Declaration

unsigned char cbm_k_acptr (void);

Description

The function returns a byte of data, which it gets from the current TALKer on the serial bus. In order to receive the data, the device must have previously been sent a command to TALK and a secondary address if it needs one.

Notes

Availability

cc65

See also

cbm_k_talk,

Example

None.

3.37 cbm_k_basin

Function

Input a Character from the Current Device

Header

cbm.h

Declaration

unsigned char cbm_k_basin (void);

Description

The function returns a character from the current input device. Device must first have been OPENed and then designated as the input channel by the CHKIN routine. When this function is called, the next byte of data available from the device is returned. Exception is the routine for the keyboard device (which is the default input device).

Notes

Availability

cc65

See also

cbm_k_open, cbm_k_chkin

Example

None.

3.38 cbm_k_bsout

Function

Output a byte

Header

cbm.h

Declaration

void __fastcall__ cbm_k_bsout (unsigned char C);

Description

Function sends the character to the current output device. Unless a device has been OPENed and designated as the current output channel using the CHKOUT routine, the character is printed to the screen, which is the default output device. If the cassette is the current device, outputting a byte will only add it to the buffer. No actual transmission of data will occur until the 192-byte buffer is full.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cbm_k_open, cbm_k_chkout

Example

None.

3.39 cbm_k_chkin

Function

Designate a Logical File As the Current Input Channel

Header

cbm.h

Declaration

unsigned char __fastcall__ cbm_k_chkin (unsigned char FN);

Description

If you wish to get data from any device other than the keyboard, this function must be called after OPENing the device, before you can get a data byte with the cbm_k_basin or cbm_k_getin routine. When called, the routine will designate the logical file whose file number was supplied as the current file, its device as the current device, and its secondary address as the current secondary address. If the device on the channel is a serial device, which requires a TALK command and sometimes a secondary address, function will send them over the serial bus.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cbm_k_open, cbm_k_basin, cbm_k_getin

Example

None.

3.40 cbm_k_ciout

Function

Transmit a byte over the serial bus

Header

cbm.h

Declaration

void __fastcall__ cbm_k_ciout (unsigned char C);

Description

Purpose of this function is to send a byte of data over the serial bus. In order for the data to be received, the serial device must have first been commanded to LISTEN and been given a secondary address if necessary. This routine always buffers the current character, and defers sending it until the next byte is buffered. When the UNLISTEN command is sent, the last byte will be sent with an End or Identify (EOI).

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cbm_k_listen, cbm_k_unlsn

Example

None.

3.41 cbm_k_ckout

Function

Designate a Logical File As the Current Output Channel

Header

cbm.h

Declaration

unsigned char __fastcall__ cbm_k_ckout (unsigned char FN);

Description

If you wish to output data to any device other than the screen, this routine must be called after OPENing the device, and before you output a data byte with the cbm_k_bsout() function. When called, the function will designate the logical file whose file number was supplied as the current file, its device as the current device, and its secondary address as the current secondary address. If the device on the channel uses the serial bus, and therefore requires a LISTEN command and possibly a secondary address, this information will be sent on the bus.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cbm_k_bsout, cbm_k_listen

Example

None.

3.42 cbm_k_clall

Function

Close All Logical I/O Files

Header

cbm.h

Declaration

void cbm_k_clall (void);

Description

It closes all open files, by resetting the index into open files to zero and restores the default I/O devices.

Notes

Availability

cc65

See also

cbm_k_open, cbm_k_close

Example

None.

3.43 cbm_k_close

Function

Close a Logical I/O File

Header

cbm.h

Declaration

void __fastcall__ cbm_k_close (unsigned char FN);

Description

It is used to close a logical file after all I/O operations involving that file have been completed.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cbm_k_open, cbm_k_clall

Example

None.

3.44 cbm_k_clrch

Function

Restore Current Input and Output Devices to the Default Devices

Header

cbm.h

Declaration

void cbm_k_clrch (void);

Description

It sets the current input device to the keyboard, and the current output device to the screen. Also, if the current input device was formerly a serial device, the routine sends it an UNTALK command on the serial bus, and if a serial device was formerly the current output device, the routine sends it an UNLISTEN command.

Notes

Availability

cc65

See also

cbm_k_chkin, cbm_k_ckout

Example

None.

3.45 cbm_k_getin

Function

Get One Byte from the Input Device

Header

cbm.h

Declaration

unsigned char cbm_k_getin (void);

Description

Function gets a character from the current input device.

Notes

Availability

cc65

See also

cbm_k_basin

Example

None.

3.46 cbm_k_iobase

Function

Return Base Address of Memory-Mapped I/O Devices

Header

cbm.h

Declaration

unsigned cbm_k_iobase (void);

Description

This function returns the address of the memory section where the memory mapped I/O devices are located. This address can then be used with an offset to access the memory mapped I/O devices in the Commodore 64. The offset is the number of locations from the beginning of the page on which the I/O register you want is located. This function exists to provide compatibility between the Commodore 64, VIC-20, and future models of the Commodore 64. If the I/O locations for a program are set by a call to this function, they should still remain compatible with future versions of the Commodore 64, the KERNAL and BASIC.

Notes

Availability

cc65

See also
Example

None.

3.47 cbm_k_listen

Function

Command a device on the serial bus to LISTEN

Header

cbm.h

Declaration

void __fastcall__ cbm_k_listen (unsigned char dev);

Description

This function will command a device on the serial bus to receive data. The KERNAL routine will OR the supplied device number bit by bit to convert it to a listen address, then transmits this data as a command on the serial bus. The specified device will then go into listen mode, and be ready to accept information.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cbm_k_unlsn,

Example

None.

3.48 cbm_k_load

Function

Load RAM from a Device

Header

cbm.h

Declaration

unsigned int __fastcall__ cbm_k_load(unsigned char flag, unsigned addr);

Description

This function LOADs data bytes from any input device directly into the memory. It can also be used for a verify operation, comparing data from a device with the data already in memory, while leaving the data stored in RAM unchanged. The flag must be set to 0 for a LOAD operation, or 1 for a verify, If the input device is OPENed with a secondary address (SA) of 0 the header information from the device is ignored. In this case, the starting address for the load must be supplied. If the device is addressed with a secondary address of 1, then the data is loaded into memory starting at the location specified by the header. Function returns the address of the highest RAM location loaded. Before this function can be called, the KERNAL SETLFS, and SETNAM routines must be called.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cbm_k_save, cbm_k_setlfs, cbm_k_setnam

Example

None.

3.49 cbm_k_open

Function

Open a Logical I/O File

Header

cbm.h

Declaration

unsigned char cbm_k_open (void);

Description

This function assigns a logical file to a device, so that it can be used for Input/Output operations. In order to specify the logical file number, the device number, and the secondary address if any, the cbm_k_setlfs() function must first be called. Likewise, in order to designate the filename, the cbm_k_setnam() function must be used first. After these two functions are called, cbm_k_open() is then called.

Notes

Availability

cc65

See also

cbm_k_close, cbm_k_setlfs, cbm_k_setnam

Example

None.

3.50 cbm_k_readst

Function

Read status word

Header

cbm.h

Declaration

unsigned char cbm_k_readst (void);

Description

This function returns the current status of the I/O devices. It is usually called after new communication to an I/O device and gives information about device status, or errors that have occurred during the I/O operation.

Notes

Availability

cc65

See also
Example

None.

3.51 cbm_k_save

Function

Save RAM to a Device

Header

cbm.h

Declaration

unsigned char __fastcall__ cbm_k_save(unsigned int start, unsigned int end)

Description

This function saves a section of memory. The cbm_k_setlfs() and cbm_k_setnam() functions must be used before calling this function. However, a file name is not required to SAVE to device 1 (the Datassette(TM) recorder). Any attempt to save to other devices without using a file name results in an error. NOTE: Device 0 (the keyboard), device 2 (RS-232), and device 3 (the screen) cannot be SAVEd to. If the attempt is made, an error occurs, and the SAVE is stopped.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cbm_k_load, cbm_k_setlfs, cbm_k_setnam

Example

None.

3.52 cbm_k_scnkey

Function

Scan the keyboard matrix.

Header

cbm.h

Declaration

void cbm_k_scnkey (void);

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.

Availability

cc65

See also

cbm_k_getin, cbm_k_udtim, cgetc,

Example

None.

3.53 cbm_k_setlfs

Function

Set up a logical file

Header

cbm.h

Declaration

void __fastcall__ cbm_k_setlfs (unsigned char LFN, unsigned char DEV, unsigned char SA);

Description

This functions sets up the logical file by setting its number, device address, and secondary address.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cbm_k_setnam

Example

None.

3.54 cbm_k_setnam

Function

Set Filename Parameters

Header

cbm.h

Declaration

void __fastcall__ cbm_k_setnam (const char* Name);

Description

This function is used to set up the file name for the OPEN, SAVE, or LOAD operations.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cbm_k_open, cbm_k_load, cbm_k_save

Example

None.

3.55 cbm_k_talk

Function

Commands device to TALK

Header

cbm.h

Declaration

void __fastcall__ cbm_k_talk (unsigned char dev);

Description

When called, it ORs the device number with the TALK code (64, $40) and sends it on the serial bus. This commands the device to TALK.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cbm_k_acptr

Example

None.

3.56 cbm_k_udtim

Function

Update the Jiffy clock.

Header

cbm.h

Declaration

void cbm_k_udtim (void);

Description

This function adds one count to the Jiffy clock. That clock counts sixtieths of a second. It is used by the library's 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.

Availability

cc65

See also

cbm_k_scnkey, clock

Example

None.

3.57 cbm_k_unlsn

Function

Send an UNLISTEN command

Header

cbm.h

Declaration

void cbm_k_unlsn (void);

Description

This function commands all devices on the serial bus to stop receiving data from the host computer (i.e., UNLISTEN). Calling this function results in an UNLISTEN command being transmitted on the serial bus. Only devices previously commanded to LISTEN are affected. This function is normally used after the host computer is finished sending data to external devices. Sending the UNLISTEN commands the listening devices to get off the serial bus so it can be used for other purposes.

Notes

Availability

cc65

See also

cbm_k_listen

Example

None.

3.58 cclear

Function

Clear part of a line (write a given number of spaces).

Header

conio.h

Declaration

void __fastcall__ cclear (unsigned char length);

Description

The function clears part of a line by writing length spaces in the current text color.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cclearxy, clrscr

Example

None.

3.59 cclearxy

Function

Clear part of a line (write a given number of spaces) starting at a specific screen position.

Header

conio.h

Declaration

void __fastcall__ cclearxy (unsigned char x, unsigned char y, unsigned char length);

Description

The function moves the cursor to a specific position, and will then clear part of the line by writing length spaces in the current text color.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cclear, clrscr

Example

None.

3.60 cgetc

Function

Read a character from the keyboard.

Header

conio.h

Declaration

char cgetc (void);

Description

The function reads a character from the keyboard. If there is no character available, cgetc() waits until the user presses a key. If the cursor is enabled by use of the cursor function, a blinking cursor is displayed while waiting.

Notes

  • If the system supports a keyboard buffer, cgetc() will fetch a key from that buffer; and, wait only if the buffer is empty.
  • The keyboard must be scanned periodically, in order for this function to see anything that you type. (See the description of cbm_k_scnkey().)

Availability

cc65

See also

cbm_k_scnkey, cursor, kbhit

Example

None.

3.61 chline

Function

Output a horizontal line in text mode.

Header

conio.h

Declaration

void __fastcall__ chline (unsigned char length);

Description

The function outputs a horizontal line with the given length starting at the current cursor position.

Notes

  • The character used to draw the horizontal line is system dependent. If available, a line drawing character is used. Drawing a line that is partially off screen leads to undefined behaviour.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

chlinexy, cvline, cvlinexy

Example

None.

3.62 chlinexy

Function

Output a horizontal line at a given position in text mode.

Header

conio.h

Declaration

void __fastcall__ chlinexy (unsigned char x, unsigned char y, unsigned char length);

Description

The function outputs a horizontal line with the given length starting at a given position.

Notes

  • The character used to draw the horizontal line is system dependent. If available, a line drawing character is used. Drawing a line that is partially off screen leads to undefined behaviour.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

chline, cvline, cvlinexy

Example

None.

3.63 clearerr

Function

Clear error and end-of-file status of a stream.

Header

stdio.h

Declaration

void __fastcall__ clearerr (FILE* f);

Description

clearerr clears the error and end-of-file status indicators for the stream f.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

feof, ferror

Example

None.

3.64 clock

Function

Determine the processor time used.

Header

time.h

Declaration

clock_t clock (void);

Description

The clock function returns an approximaton of processor 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 CLOCKS_PER_SEC.

Notes

  • 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.
  • The Jiffy clock must be "running", in order for this function to return changing values. (See the description of cbm_k_udtim().)

Availability

ISO 9899

See also

cbm_k_udtim, time

Example

None.

3.65 clrscr

Function

Clear the text screen.

Header

conio.h

Declaration

void clrscr (void);

Description

The function clears the text screen and moves the cursor to the upper left corner.

Availability

cc65

See also

cclear, cclearxy

Example

None.

3.66 close

Function

Close a file descriptor.

Header

fcntl.h

Declaration

int __fastcall__ close (int fd);

Description

The function closes the given file descriptor. It returns zero on success and -1 on error. If an error occurs, the cause can be determined by reading the errno variable.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

POSIX 1003.1

See also

creat, open

Example

None.

3.67 closedir

Function

Close a directory.

Header

dirent.h

Declaration

int __fastcall__ closedir (DIR* dir);

Description

The function closes the given directory descriptor. It returns zero on success and -1 on error. If an error occurs, the cause can be determined by reading the errno variable.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

POSIX 1003.1

See also

opendir, readdir

Example

None.

3.68 creat

Function

Create a file.

Header

fcntl.h

Declaration

int __fastcall__ creat (const char* name, unsigned mode);

Description

creat creates a new file and returns the file descriptor associated with it. On error, -1 is returned and an error code is stored in errno.

Notes

  • creat is identical to calling open with flags equal to O_WRONLY | O_CREAT | O_TRUNC.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

POSIX 1003.1

See also

close, open

Example

None.

3.69 cprintf

Function

Formatted output to the console.

Header

conio.h

Declaration

int cprintf (const char* format, ...);

Description

The arguments are converted to text where necessary and formatted according to the format string given. The resulting string is output to the console. cprintf supports the same format specifiers as printf.

Notes

  • Like all other conio output functions, cprintf distinguishes between \r and \n.

Availability

cc65

See also

cputc, cputcxy, cputs, cputsxy, vcprintf

Example

None.

3.70 cputc

Function

Output a character directly to the console.

Header

conio.h

Declaration

void __fastcall__ cputc (char c);

Description

Output one character to the console at the current cursor position.

Notes

  • Like all other conio output functions, cputc distinguishes between \r and \n.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cprintf, cputcxy, cputs, cputsxy, vcprintf

Example

None.

3.71 cputcxy

Function

Output a character at a specific screen position.

Header

conio.h

Declaration

void __fastcall__ cputcxy (unsigned char x, unsigned char y, char c);

Description

cputcxy moves the cursor to the given x/y position on the screen and outputs one character.

Notes

  • Like all other conio output functions, cputcxy distinguishes between \r and \n.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cprintf, cputc, cputs, cputsxy, vcprintf

Example

None.

3.72 cputs

Function

Output a string directly to the console.

Header

conio.h

Declaration

void __fastcall__ cputs (const char* s);

Description

The function outputs the given string on the console at the current cursor position.

Notes

  • Like all other conio output functions, cputs distinguishes between \r and \n.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cprintf, cputc, cputcxy, cputsxy, vcprintf

Example

None.

3.73 cputsxy

Function

Output a string to the console at a given position.

Header

conio.h

Declaration

void __fastcall__ cputsxy (unsigned char x, unsigned char y, const char* s);

Description

cputsxy moves the cursor to the given x/y position, and outputs the string s.

Notes

  • Like all other conio output functions, cputsxy distinguishes between \r and \n.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cprintf, cputc, cputcxy, cputs, vcprintf

Example

None.

3.74 cursor

Function

Enable/disable a blinking cursor when waiting for keyboard input.

Header

conio.h

Declaration

unsigned char __fastcall__ cursor (unsigned char onoff);

Description

If the argument to the function is non zero, a blinking cursor will be enabled when the cgetc function waits for input from the keyboard. If the argument is zero, cgetc will wait without a blinking cursor.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cgetc, kbhit

Example

None.

3.75 cvline

Function

Output a vertical line in text mode.

Header

conio.h

Declaration

void __fastcall__ cvline (unsigned char length);

Description

The function outputs a vertical line with the given length starting at the current cursor position.

Notes

  • The character used to draw the vertical line is system dependent. If available, a line drawing character is used. Drawing a line that is partially off screen leads to undefined behaviour.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

chline, chlinexy, cvlinexy

Example

None.

3.76 cvlinexy

Function

Output a vertical line at a given position in text mode.

Header

conio.h

Declaration

void __fastcall__ cvlinexy (unsigned char x, unsigned char y, unsigned char length);

Description

The function outputs a vertical line with the given length starting at a given position.

Notes

  • The character used to draw the vertical line is system dependent. If available, a line drawing character is used. Drawing a line that is partially off screen leads to undefined behaviour.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

chline, chlinexy, cvline

Example

None.

3.77 decompress_lz4

Function

Uncompress a LZ4-compressed buffer.

Header

lz4.h

Declaration

void decompress_lz4 (const unsigned char* src, unsigned char* const dst, const unsigned short uncompressed_size);

Description

decompress_lz4 uncompresses a LZ4-compressed buffer.

Notes

  • Use LZ4_compress_HC with compression level 16 for best compression.

Availability

cc65

Example

None.

3.78 div

Function

Divide two ints and return quotient and remainder.

Header

stdlib.h

Declaration

div_t __fastcall__ div (int numer, int denom);

Description

div divides numer by denom and returns the quotient and remainder in a div_t structure.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

ldiv

Example

None.

3.79 doesclrscrafterexit

Function

Determines whether the screen is going to be cleared after program exit.

Header

cc65.h

Declaration

unsigned char doesclrscrafterexit (void);

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.

Notes

  • 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.

Availability

cc65

Example

/* Hello World */
#include <stdio.h>
#include <unistd.h>
#include <cc65.h>
int main(void)
{
    printf("Hello World\n");
    if (doesclrscrafterexit())
        sleep(5);
    return 0;
}

3.80 em_commit

Function

Commit changes into extended memory.

Header

em.h

Declaration

void em_commit (void);

Description

Commit changes in the memory window to extended storage. If the contents of the memory window have been changed, these changes may be lost if em_map, em_use, em_copyfrom or em_copyto are called without calling em_commit first.

Notes

  • Calling em_commit does not necessarily mean that changes to the memory window are discarded, it does just mean that the drivers is allowed to discard it.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function produces undefined results if no extended memory driver is loaded.

Availability

cc65

See also

em_load_driver, em_map, em_use

Example

None.

3.81 em_copyfrom

Function

Copy from extended into normal memory.

Header

em.h

Declaration

void __fastcall__ em_copyfrom (const struct em_copy* copy_data);

Description

Copy data from extended memory into linear memory. Source and target addresses as well as the number of bytes to transfer are specified in the em_copy structure that is passed as a parameter.

Notes

  • Calling em_copyfrom will invalidate the memory window, so if you made any changes to the data in the window, call em_commit first, or the changes are lost.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function produces undefined results if no extended memory driver is loaded.

Availability

cc65

See also

em_commit, em_copyto, em_load_driver

Example

None.

3.82 em_copyto

Function

Copy from normal into extended memory.

Header

em.h

Declaration

void __fastcall__ em_copyto (const struct em_copy* copy_data);

Description

Copy data from linear into extended memory. Source and target addresses as well as the number of bytes to transfer are specified in the em_copy structure that is passed as a parameter.

Notes

  • Calling em_copyto will invalidate the memory window, so if you made any changes to the data in the window, call em_commit first, or the changes are lost.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function produces undefined results if no extended memory driver is loaded.

Availability

cc65

See also

em_commit, em_copyfrom, em_load_driver

Example

None.

3.83 em_install

Function

Install an already loaded extended memory driver.

Header

em.h

Declaration

unsigned char _fastcall__ em_install (void* driver);

Description

The function installs an already loaded extended memory driver and returns an error code. The function may be used to install a driver linked statically to the program.

Notes

  • Not all drivers are able to detect if the supported hardware is really present.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

em_load_driver, em_uninstall, em_unload

Example

None.

3.84 em_load_driver

Function

Load and initialize an extended memory driver.

Header

em.h

Declaration

void __fastcall__ em_load_driver (const char* name);

Description

Load an extended memory driver into memory and initialize it. The function returns an error code that tells if all this has been successful.

Notes

  • Not all drivers are able to detect if the supported hardware is really present.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The driver is loaded by name, so currently you must know the type of extended memory that should be supported. There is no autodetect capability.

Availability

cc65

See also

em_unload

Example

None.

3.85 em_map

Function

Make a page of extended memory accessible.

Header

em.h

Declaration

void* __fastcall__ em_map (unsigned page);

Description

The function maps one page of extended memory into linear memory and returns a pointer to the page frame. Depending on the hardware and driver, the data is either mapped into the address space or transfered into a buffer. If you don't need the actual contents of the page (for example because you're going to overwrite it completely), it is better to call em_use instead. em_use will not transfer the data if it is possible to avoid that.

Notes

  • Calling em_map will invalidate the memory window, so if you made any changes to the data in the window, call em_commit first, or the changes are lost.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function produces undefined results if no extended memory driver is loaded.

Availability

cc65

See also

em_commit, em_load_driver, em_use

Example

None.

3.86 em_pagecount

Function

Return the number of available extended memory pages.

Header

em.h

Declaration

unsigned em_pagecount (void);

Description

The function returns the size of the extended memory supported by the driver in 256 byte pages.

Notes

  • The function returns zero if no extended memory driver is loaded.
  • The function may return zero if the supported hardware was not detected.

Availability

cc65

See also

em_load_driver

Example

None.

3.87 em_uninstall

Function

Uninstall an already loaded extended memory driver.

Header

em.h

Declaration

unsigned char em_uninstall (void);

Description

The function uninstalls an already loaded extended memory driver but doesn't remove it from memory.

Notes

  • If the driver has been loaded using em_load_driver, em_unload should be used instead of em_uninstall so the driver is also removed from memory.

Availability

cc65

See also

em_install, em_load_driver, em_unload

Example

None.

3.88 em_unload

Function

Unload an extended memory driver.

Header

em.h

Declaration

unsigned char em_unload (void);

Description

The function unloads a loaded extended memory driver and frees all memory allocated for the driver.

Notes

  • The function does nothing if no driver is loaded.

Availability

cc65

See also

em_load_driver

Example

None.

3.89 em_use

Function

Prepare an extended memory page for use.

Header

em.h

Declaration

void* __fastcall__ em_use (unsigned page);

Description

The function maps one page of extended memory into linear memory and returns a pointer to the page frame. This function is similar to em_map, but will not transfer data into the actual memory window in the assumption that the existing data is wrong or will get overwritten.

Notes

  • Calling em_use will invalidate the memory window, so if you made any changes to the data in the window, call em_commit first, or the changes are lost.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function produces undefined results if no extended memory driver is loaded.

Availability

cc65

See also

em_commit, em_load_driver, em_map

Example

None.

3.90 exit

Function

Terminate the program.

Header

stdlib.h

Declaration

void __fastcall__ exit (int status);

Description

exit terminates the program. The argument specifies the return code of the program. Before termination, all files are closed, buffered output is written and any functions registered with atexit are called. Common values for status are EXIT_SUCCESS and EXIT_FAILURE which are also defined in stdlib.h.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • It depends on the host machine if the program return code can be evaluated or is ignored.

Availability

ISO 9899

See also

abort, exit

Example

None.

3.91 exec

Function

Execute a program file.

Header

unistd.h

Declaration

int __fastcall__ exec (const char* progname, const char* cmdline);

Description

exec replaces the currently running program by a new one. Calling exec() is identical to calling exit(), then loading and starting the program named in the first argument, passing the command line specified as second argument. Instead of an empty string, a NULL pointer may be passed as second parameter. On success, the function does not return. On failure, -1 is returned and errno contains an error code.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • On most platforms, the function needs to copy a small stub loader to some memory area outside the program space. This may collide with other programs. See the platform specific docs on this.
  • Because it is necessary to terminate the running program before the memory can be reused to load the new one, there is a high chance that the function may not be able to return on errors.
  • The command line is passed to the new program in the same way as cc65 programs expect the command line. If the new program is not a cc65 generated program, it may not be able to read it.

Availability

cc65

See also

exit

Example

None.

3.92 fast

Function

Switch the C128 into 2MHz mode.

Header

c128.h

Declaration

void fast (void);

Description

The function will switch the clock of the C128 to 2MHz. This will nearly double the speed compared to slow mode.

Notes

  • The function is specific to the C128.
  • 2MHz clock will not work in 40 column mode.

Availability

C128

See also

slow, toggle_videomode, videomode

Example

None.

3.93 feof

Function

Return the end-of-file indicator of a stream.

Header

stdio.h

Declaration

int __fastcall__ feof (FILE* f);

Description

feof tests the end-of-file indicator ofthe stream f, and returns a non zero value if it is set.

Notes

  • The indicator is set only after a read past the end of a file is attempted.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

clearerr, ferror

Example

None.

3.94 ferror

Function

Return the error indicator of a stream.

Header

stdio.h

Declaration

int __fastcall__ ferror (FILE* f);

Description

ferror tests the error indicator of the stream f, and returns a non zero value if it is set.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

clearerr, feof

Example

None.

3.95 fileno

Function

Return the file handle used by a stream.

Header

stdio.h

Declaration

int __fastcall__ fileno (FILE* f);

Description

The fileno function returns the file handle used internally by a C stream. This file handle (an integer) can be used as a handle for the POSIX input/output functions.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • Mixing C file I/O functions and POSIX file I/O functions for the same file may have unpredictable results.

Availability

POSIX 1003.1

See also

creat, open

Example

None.

3.96 free

Function

Free a block of dynamic memory.

Header

stdlib.h

Declaration

void __fastcall__ free (void* block);

Description

Free a block of dynamic memory previously allocated with malloc, calloc or realloc. As an exception, if the passed pointer is NULL, no action is performed.

Notes

  • Passing an already free'd block to free again will cause undefined behaviour and may crash your program.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

_heapadd, _heapblocksize, _heapmaxavail, _heapmemavail, calloc, malloc, realloc

Example

None.

3.97 get_ostype

Function

The function returns the operating system, the program runs on.

Header

apple2.h, atari.h, c64.h

Declaration

unsigned char get_ostype (void);

Description

get_ostype is machine dependent and does not exist for all supported targets. If it exists, it returns a number that identifies the operating system or machine type, the program runs on. The machine dependent header files define constants that can be used to check the return code.

Notes

  • The function does not exist on all platforms.
  • The return codes are platform dependent.

Availability

cc65 (not all platforms)

Example

None.

3.98 getcpu

Function

Determine on which CPU the program is running.

Header

6502.h

Declaration

unsigned char getcpu (void);

Description

The function checks on which CPU the code is running. It returns one of the constants

  • CPU_6502
  • CPU_65C02
  • CPU_65816

Notes

  • Other, more exotic CPU types are not disinguished.

Availability

cc65

Example

None.

3.99 getenv

Function

Return a value from the environment.

Header

stdlib.h

Declaration

char* __fastcall__ getenv (const char* name);

Description

The function searches the environment for an entry that matches name and returns its value. The environment consists of a list of strings in the form name=value. If there is no match, getenv returns NULL.

Notes

  • What exactly is stored in the environment depends on the machine the program is running on.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

Example

None.

3.100 getopt

Function

Parse command line options.

Header

unistd.h

Declaration

int __fastcall__ getopt (int argc, char* const* argv, const char* optstring);

Description

The function parses command line arguments, argc and argv are the argument count and array passed to main. optstring is a string that contains command line option characters. If a character in optstring is followed by a colon, the option requires an argument. An option on the command line is recognized if it is one of the option characters preceeded by a '-'. getopt must be called repeatedly. It will return each option character found on the command line and EOF (-1) if there is no other option. An option argument is placed in optarg, the index of the next element on the command line to be processed is placed in optind.

Notes

  • The implementation will not reorder options. A non option on the command line will terminate option processing. All remaining arguments are not recognized as options, even if the start with a '-' character.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

POSIX.2

Example

None.

3.101 gotox

Function

Move the text mode cursor to a new X position.

Header

conio.h

Declaration

void __fastcall__ gotox (unsigned char x);

Description

The function moves the text mode cursor to the specified X position while leaving the Y position untouched. The leftmost position on the screen has the coordinate 0.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • Invalid values for the X position (out of screen coordinates) may lead to undefined behaviour.

Availability

cc65

See also

gotoy, gotoxy, wherex, wherey

Example

None.

3.102 gotoxy

Function

Move the text mode cursor to a new position.

Header

conio.h

Declaration

void __fastcall__ gotoxy (unsigned char x, unsigned char y);

Description

The function moves the text mode cursor to the specified position. The leftmost position on the screen has the X coordinate 0, the topmost line has the Y coordinate 0.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • Invalid values for any of both coordinates (out of screen positions) may lead to undefined behaviour.

Availability

cc65

See also

gotox, gotoy, wherex, wherey

Example

None.

3.103 gotoy

Function

Move the text mode cursor to a new Y position.

Header

conio.h

Declaration

void __fastcall__ gotoy (unsigned char x);

Description

The function moves the text mode cursor to the specified Y position while leaving the X position untouched. The uppermost position on the screen has the coordinate 0.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • Invalid values for the Y position (out of screen coordinates) may lead to undefined behaviour.

Availability

cc65

See also

gotox, gotoxy, wherex, wherey

Example

None.

3.104 isalnum

Function

Check if a given character is a letter or digit.

Header

ctype.h

Declaration

int __fastcall__ isalnum (int c);

Description

The function returns a non zero value if the given argument is a letter or digit. The return value is zero if the character is anything else.

Notes

  • When compiling with -Os the function is actually a macro. The inline sequence generated by the macro will not work correctly for values outside the range 0..255. Note: The constant EOF is not part of this range. The non inline function may be accessed by #undef'ing the macro.
  • When compiling without -Os, the function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit

Example

None.

3.105 isalpha

Function

Check if a given character is a letter.

Header

ctype.h

Declaration

int __fastcall__ isalpha (int c);

Description

The function returns a non zero value if the given argument is a letter. The return value is zero if the character is anything else.

Notes

  • When compiling with -Os the function is actually a macro. The inline sequence generated by the macro will not work correctly for values outside the range 0..255. Note: The constant EOF is not part of this range. The non inline function may be accessed by #undef'ing the macro.
  • When compiling without -Os, the function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

isalnum, isascii, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit

Example

None.

3.106 isascii

Function

Check if a given character is in the ASCII (0..127) range.

Header

ctype.h

Declaration

int __fastcall__ isascii (int c);

Description

The function returns a non zero value if the given argument is in the range 0..127 (the range of valid ASCII characters) and zero if not.

Notes

  • When compiling with -Os the function is actually a macro. The inline sequence generated by the macro will not work correctly for values outside the range 0..255. Note: The constant EOF is not part of this range. The non inline function may be accessed by #undef'ing the macro.
  • When compiling without -Os, the function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit

Example

None.

3.107 isblank

Function

Check if a given character is a space or tab.

Header

ctype.h

Declaration

int __fastcall__ isblank (int c);

Description

The function returns a non zero value if the given argument is a space or tab character. The return value is zero if the character is anything else.

Notes

  • When compiling with -Os the function is actually a macro. The inline sequence generated by the macro will not work correctly for values outside the range 0..255. Note: The constant EOF is not part of this range. The non inline function may be accessed by #undef'ing the macro.
  • When compiling without -Os, the function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

isalnum, isalpha, isascii, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit

Example

None.

3.108 iscntrl

Function

Check if a given character is a control character.

Header

ctype.h

Declaration

int __fastcall__ iscntrl (int c);

Description

The function returns a non zero value if the given argument is a control character. The return value is zero if the character is anything else.

Notes

  • When compiling with -Os the function is actually a macro. The inline sequence generated by the macro will not work correctly for values outside the range 0..255. Note: The constant EOF is not part of this range. The non inline function may be accessed by #undef'ing the macro.
  • When compiling without -Os, the function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

isalnum, isalpha, isascii, isblank, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit

Example

None.

3.109 isdigit

Function

Check if a given character is a digit.

Header

ctype.h

Declaration

int __fastcall__ isdigit (int c);

Description

The function returns a non zero value if the given argument is a digit. The return value is zero if the character is anything else.

Notes

  • When compiling with -Os the function is actually a macro. The inline sequence generated by the macro will not work correctly for values outside the range 0..255. Note: The constant EOF is not part of this range. The non inline function may be accessed by #undef'ing the macro.
  • When compiling without -Os, the function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

isalnum, isalpha, isascii, isblank, iscntrl, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit

Example

None.

3.110 isgraph

Function

Check if a given character is a printable character (except space).

Header

ctype.h

Declaration

int __fastcall__ isgraph (int c);

Description

The function returns a non zero value if the given argument is a printable character with the exception of space. The return value is zero if the character is anything else.

Notes

  • When compiling with -Os the function is actually a macro. The inline sequence generated by the macro will not work correctly for values outside the range 0..255. Note: The constant EOF is not part of this range. The non inline function may be accessed by #undef'ing the macro.
  • When compiling without -Os, the function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

isalnum, isalpha, isascii, isblank, iscntrl, isdigit, islower, isprint, ispunct, isspace, isupper, isxdigit

Example

None.

3.111 islower

Function

Check if a given character is a lower case letter.

Header

ctype.h

Declaration

int __fastcall__ islower (int c);

Description

The function returns a non zero value if the given argument is a lower case letter. The return value is zero if the character is anything else.

Notes

  • When compiling with -Os the function is actually a macro. The inline sequence generated by the macro will not work correctly for values outside the range 0..255. Note: The constant EOF is not part of this range. The non inline function may be accessed by #undef'ing the macro.
  • When compiling without -Os, the function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, isprint, ispunct, isspace, isupper, isxdigit

Example

None.

3.112 isprint

Function

Check if a given character is a printable character.

Header

ctype.h

Declaration

int __fastcall__ isprint (int c);

Description

The function returns a non zero value if the given argument is a printable character (this includes the space character). The return value is zero if the character is anything else.

Notes

  • When compiling with -Os the function is actually a macro. The inline sequence generated by the macro will not work correctly for values outside the range 0..255. Note: The constant EOF is not part of this range. The non inline function may be accessed by #undef'ing the macro.
  • When compiling without -Os, the function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, ispunct, isspace, isupper, isxdigit

Example

None.

3.113 ispunct

Function

Check if a given character is a printable character but not a space or an alphanumeric character.

Header

ctype.h

Declaration

int __fastcall__ ispunct (int c);

Description

The function returns a non zero value if the given argument is a printable character, but not a space or anything alphanumeric. The return value is zero if the character is anything else.

Notes

  • When compiling with -Os the function is actually a macro. The inline sequence generated by the macro will not work correctly for values outside the range 0..255. Note: The constant EOF is not part of this range. The non inline function may be accessed by #undef'ing the macro.
  • When compiling without -Os, the function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, isprint, isspace, isupper, isxdigit

Example

None.

3.114 isspace

Function

Check if a given character is a white-space character.

Header

ctype.h

Declaration

int __fastcall__ isspace (int c);

Description

The function returns a non zero value if the given argument is a white space character. The return value is zero if the character is anything else. The standard white space characters are: space, formfeed ('\f'), newline ('\n'), carriage return ('\r'), horizontal tab ('\t'), and vertical tab ('\v').

Notes

  • When compiling with -Os the function is actually a macro. The inline sequence generated by the macro will not work correctly for values outside the range 0..255. Note: The constant EOF is not part of this range. The non inline function may be accessed by #undef'ing the macro.
  • When compiling without -Os, the function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isupper, isxdigit

Example

None.

3.115 isupper

Function

Check if a given character is an upper case letter.

Header

ctype.h

Declaration

int __fastcall__ isupper (int c);

Description

The function returns a non zero value if the given argument is an upper case letter. The return value is zero if the character is anything else.

Notes

  • When compiling with -Os the function is actually a macro. The inline sequence generated by the macro will not work correctly for values outside the range 0..255. Note: The constant EOF is not part of this range. The non inline function may be accessed by #undef'ing the macro.
  • When compiling without -Os, the function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isxdigit

Example

None.

3.116 isxdigit

Function

Check if a given character is a hexadecimal digit.

Header

ctype.h

Declaration

int __fastcall__ isxdigit (int c);

Description

The function returns a non zero value if the given argument is a hexadecimal digit (0..9, a..f and A..F). The return value is zero if the character is anything else.

Notes

  • When compiling with -Os the function is actually a macro. The inline sequence generated by the macro will not work correctly for values outside the range 0..255. Note: The constant EOF is not part of this range. The non inline function may be accessed by #undef'ing the macro.
  • When compiling without -Os, the function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper

Example

None.

3.117 itoa

Function

Convert an integer into a string.

Header

stdlib.h

Declaration

char* __fastcall__ itoa (int val, char* buf, int radix);

Description

itoa converts the integer val into a string using radix as the base.

Notes

  • There are no provisions to prevent a buffer overflow.
  • If val contains INT_MIN, the behaviour is undefined.
  • The function is non standard, so it is not available in strict ANSI mode. You should probably use sprintf instead.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

atoi, atol, ltoa, ultoa, utoa

Example

None.

3.118 joy_count

Function

Return the number of joysticks supported by the current driver.

Header

joystick.h

Declaration

unsigned char joy_count (void);

Description

The function returns a the number of joysticks supported by the current joystick driver.

Notes

  • A joystick driver must be loaded using joy_load_driver before calling this function.
  • The function returns the number of joysticks supported by the driver. There's no way to check for the number of actually connected joysticks.

Availability

cc65

See also

joy_load_driver, joy_read

Example

None.

3.119 joy_install

Function

Install an already loaded driver and return an error code.

Header

joystick.h

Declaration

unsigned char __fastcall__ joy_install (void* driver);

Description

The function installs a driver that was already loaded into memory (or linked statically to the program). It returns an error code (JOY_ERR_OK in case of success).

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

joy_load_driver, joy_uninstall, joy_unload

Example

None.

3.120 joy_load_driver

Function

Load a driver from disk and install it.

Header

joystick.h

Declaration

unsigned char __fastcall__ joy_load_driver (const char* driver);

Description

The function loads a driver with the given name from disk and installs it. An error code is returned, which is JOY_ERR_OK if the driver was successfully loaded and installed.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

joy_install, joy_uninstall, joy_unload

Example

None.

3.121 joy_read

Function

Read the status of a joystick.

Header

joystick.h

Declaration

unsigned char __fastcall__ joy_read (unsigned char joystick);

Description

The function reads the status bits for a joystick. The number of the joystick is passed as parameter. The result may be examined by using one of the JOY_xxx macros from joystick.h.

Notes

  • A joystick driver must be loaded using joy_load_driver before calling this function.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

joy_count, joy_load_driver, joy_unload

Example

None.

3.122 joy_uninstall

Function

Uninstall the current joystick driver.

Header

joystick.h

Declaration

unsigned char joy_uninstall (void);

Description

The function uninstalls the currently installed joystick driver. It does not remove the driver from memory. The function returns an error code, which is JOY_ERR_OK if the driver was successfully uninstalled.

Notes

  • A joystick driver must be installed using joy_install before calling this function.

Availability

cc65

See also

joy_install, joy_load_driver, joy_unload

Example

None.

3.123 joy_unload

Function

Uninstall, then unload the current joystick driver.

Header

joystick.h

Declaration

unsigned char joy_unload (void);

Description

The function uninstalls the currently installed joystick driver and removes it from memory. An error code is returned, which is JOY_ERR_OK if the driver was successfully uninstalled.

Notes

  • A joystick driver must be loaded using joy_load_driver before calling this function.

Availability

cc65

See also

joy_load_driver

Example

None.

3.124 kbhit

Function

Check if there's a key waiting in the keyboard buffer.

Header

conio.h

Declaration

unsigned char kbhit (void);

Description

The function returns a value of zero if there is no character waiting to be read from the keyboard. It returns non zero otherwise.

Notes

  • If the system does not support a keyboard buffer (most systems do), the function is rather useless.

Availability

cc65

See also

cgetc, cursor

Example

None.

3.125 kbrepeat

Function

Set the keyboard repeat mode.

Header

cbm.h

Declaration

unsigned char __fastcall__ kbrepeat (unsigned char mode);

Description

This function changes which keys have automatic repeat when being held down for a certain time. Possible values are KBREPEAT_CURSOR (repeat only cursor-related keys), KBREPEAT_NONE (no repeat for any keys), and KBREPEAT_ALL (repeat all keys). The old mode is returned, so it can be restored later.

Notes

  • The function is available only as a fastcall function; so, it may be used only in the presence of a prototype.

Availability

cc65

Example

None.

3.126 labs

Function

Returns the absolute value of a long integer.

Header

stdlib.h

Declaration

long __fastcall__ labs (long v);

Description

labs returns the absolute value of the argument passed to the function.

Notes

  • The return value is undefined if LONG_MIN is passed to the function.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

abs

Example

None.

3.127 ltoa

Function

Convert a long integer into a string.

Header

stdlib.h

Declaration

char* __fastcall__ ltoa (long val, char* buf, int radix);

Description

itoa converts the long integer val into a string using radix as the base.

Notes

  • There are no provisions to prevent a buffer overflow.
  • If val contains LONG_MIN, the behaviour is undefined.
  • The function is non standard, so it is not available in strict ANSI mode. You should probably use sprintf instead.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

atoi, atol, itoa, ultoa, utoa

Example

None.

3.128 localeconv

Function

Returns a pointer to the current locale structure.

Header

locale.h

Declaration

struct lconv* localeconv (void);

Description

localeconv returns a pointer to the current locale structure.

Notes

  • cc65 supports only the "C" locale, so even after setting a new locale using setlocale, the structure returned will always be the same.

Availability

ISO 9899

See also

setlocale

Example

None.

3.129 longjmp

Function

Non local goto.

Header

setjmp.h

Declaration

void __fastcall__ longjmp (jmp_buf buf, int retval);

Description

The longjmp function restores a program context from the data in buf, which must have been set by a preceeding call to setjmp. Program execution continues as if the call to setjmp has just returned the value retval.

Notes

  • If the parameter retval is zero, the function will behave as if it was called with a value of one.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

setjmp

Example

None.

3.130 malloc

Function

Allocate dynamic memory.

Header

stdlib.h

Declaration

void* __fastcall__ malloc (size_t size);

Description

malloc allocates size bytes on the heap and returns a pointer to the allocated memory block. On error (not enough memory available), malloc returns NULL.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

_heapadd, _heapblocksize, _heapmaxavail, _heapmemavail, calloc, free, realloc, strdup

Example

None.

3.131 memchr

Function

Search for a character in a block of raw memory.

Header

string.h

Declaration

void* __fastcall__ strchr (const void* mem, int c, size_t count);

Description

The memchr function locates the first occurrence of c (converted to a char) in the block of raw memory string pointed to by mem that is of size count. Upon completion, the function returns a pointer to the character found, or a null pointer if the character was not found.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

strchr

Example

None.

3.132 memcmp

Function

Compare two memory areas.

Header

string.h

Declaration

int __fastcall__ memcmp (const void* p1, const void* p2, size_t count);

Description

memcmp compares count bytes from the memory area pointed to by p1 into the memory area pointed to by p2. It returns a value that is less than zero if p1 is less than p2, zero if p1 is the same as p2, and a value greater than zero if p1 is greater than p2.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

strcmp, memmove, memset

Example

None.

3.133 memcpy

Function

Copy a memory area.

Header

string.h

Declaration

void* __fastcall__ memcpy (void* dest, const void* src, size_t count);

Description

memcpy copies count bytes from the memory area pointed to by src into the memory area pointed to by dest. It returns dest.

Notes

  • The result is undefined if the memory areas do overlap. Use memmove to copy overlapping memory areas.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

_swap, memmove, memset

Example

None.

3.134 memmove

Function

Copy a memory area.

Header

string.h

Declaration

void* __fastcall__ memmove (void* dest, const void* src, size_t count);

Description

memmove copies count bytes from the memory area pointed to by src into the memory area pointed to by dest. It returns dest.

Notes

  • While memmove allows the memory areas to overlap, it has some additional overhead compared to memcpy.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

_swap, memcpy, memset

Example

None.

3.135 memset

Function

Fill a memory area.

Header

string.h

Declaration

void* __fastcall__ memset (void* p, int val, size_t count);

Description

memset fills the memory area pointed to by p with the value val. The function returns p.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

_swap, bzero, memcpy, memmove

Example

None.

3.136 mod_free

Function

Free a relocatable module.

Header

modload.h

Declaration

void __fastcall__ mod_free (void* module);

Description

The function will free a module loaded into memory by use of the mod_load function.

Notes

  • The pointer passed as parameter is the pointer to the module memory, not the pointer to the control structure.
  • The function is available only as a fastcall function; so, it may be used only in the presence of a prototype.

Availability

cc65

See also

mod_load

Example

None.

3.137 mod_load

Function

Load a relocatable module.

Header

modload.h

Declaration

unsigned char __fastcall__ mod_load (struct mod_ctrl* ctrl);

Description

The function will load a code module into memory and relocate it. The function will return an error code. If MLOAD_OK is returned, the outgoing fields in the passed mod_ctrl struct contain information about the module just loaded. Possible error codes are:

  • MLOAD_OK - Module load successful
  • MLOAD_ERR_READ - Read error
  • MLOAD_ERR_HDR - Header error
  • MLOAD_ERR_OS - Wrong operating system
  • MLOAD_ERR_FMT - Data format error
  • MLOAD_ERR_MEM - Not enough memory

Notes

  • The ld65 linker is needed to create relocatable o65 modules for use with this function.
  • The function is available only as a fastcall function; so, it may be used only in the presence of a prototype.

Availability

cc65

See also

mod_free

Example

None.

3.138 mouse_setbox

Function

Specify a bounding box for the mouse cursor.

Header

mouse.h

Declaration

void __fastcall__ mouse_setbox (const struct mouse_box* box);

Description

The function allows to set a bounding box for mouse movement.

Notes

  • The function does not check if the mouse cursor is currently within the given rectangle. Placing the mouse cursor within the bounding box is the responsibility of the programmer.
  • While the bounding box may be larger than the actual screen size, the standard mouse cursor draw routines may fail to set the cursor to coordinates outside of the screen area. Depending on the platform, you may have to supply your own mouse cursor routines.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

mouse_getbox, mouse_move

Example

None.

3.139 mouse_getbox

Function

Return the current bounding box for the mouse cursor.

Header

mouse.h

Declaration

void __fastcall__ mouse_getbox (struct mouse_box* box);

Description

The function queries the current bounding box for mouse movement.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

mouse_move, mouse_setbox

Example

None.

3.140 mouse_buttons

Function

Return a bit mask encoding the state of the mouse buttons.

Header

mouse.h

Declaration

unsigned char mouse_buttons (void);

Description

The function returns a bit mask that encodes the state of the mouse buttons. You may use the MOUSE_BTN_XXX flags to decode the function return value.

Availability

cc65

See also

mouse_info, mouse_pos

Example

None.

3.141 mouse_geterrormsg

Function

Return a readable error message for an error code.

Header

mouse.h

Declaration

const char* __fastcall__ mouse_geterrormsg (unsigned char code);

Description

The function returns an error message (in english) for the error code passed parameter.

Notes

  • The function will return "Unknown error" for invalid error codes.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

mouse_load_driver, mouse_uninstall, mouse_unload

Example

None.

3.142 mouse_hide

Function

Hide the mouse pointer.

Header

mouse.h

Declaration

void mouse_hide (void);

Description

The function hides the mouse pointer. It manages a counter that is shared between mouse_show and mouse_hide so that every call call to mouse_hide must be followed by a call to mouse_show to make the mouse cursor visible.

Availability

cc65

See also

mouse_show

Example

None.

3.143 mouse_info

Function

Return the state of the mouse buttons and the position of the mouse.

Header

mouse.h

Declaration

void __fastcall__ mouse_info (struct mouse_info* info);

Description

The function returns the state of the mouse buttons and the position of the mouse in the mouse_info structure passed as parameter.

Notes

  • The mouse_info struct is a superset of the mouse_pos struct, so if you just need the mouse position, call mouse_pos instead.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

mouse_buttons, mouse_pos

Example

None.

3.144 mouse_install

Function

Install an already loaded mouse driver.

Header

mouse.h

Declaration

unsigned char __fastcall__ mouse_install (const struct mouse_callbacks* c, void* driver);

Description

The function installs an already loaded mouse driver and returns an error code. The mouse_callbacks structure passed as first parameter contains pointers to routines needed to move or hide/show the mouse pointer. Defaults for these routines are supplied by the library, so if you can live with these defaults (which are platform specific), just pass a pointer to mouse_def_callbacks. The function may be used to install a driver linked statically to the program.

Notes

  • Not all drivers are able to detect if the supported hardware is really present.
  • After installing a driver, the mouse cursor is hidden.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

mouse_load_driver, mouse_uninstall, mouse_unload

Example

None.

3.145 mouse_ioctl

Function

Call the driver specific ioctl function.

Header

mouse.h

Declaration

unsigned char __fastcall__ mouse_ioctl (unsigned char code, void* data);

Description

The function calls the IOCTL entry in the mouse driver, which is driver specific. The code parameter will choose between different IOCTL functions, and the data depends on code. The function returns an error code. The purpose of this function is to allow for driver specific extensions. See the documentation for a specific mouse driver for supported ioctl calls.

Notes

  • Calling this function is non portable, because each driver may implement different ioctl calls (or none at all).
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

Example

None.

3.146 mouse_load_driver

Function

Load and initialize a mouse driver.

Header

mouse.h

Declaration

unsigned char __fastcall__ mouse_load_driver (const struct mouse_callbacks* c, const char* driver);

Description

Load a mouse driver into memory and initialize it. The function returns an error code that tells if the call has been successful. The mouse_callbacks structure passed as first parameter contains pointers to routines needed to move or hide/show the mouse pointer. Defaults for these routines are supplied by the library, so if you can live with these defaults (which are platform specific), just pass a pointer to mouse_def_callbacks.

Notes

  • The driver is loaded by name, so currently you must know the type of mouse that should be supported. There is no autodetect capability.
  • Not all drivers are able to detect if the supported hardware is really present.
  • After installing a driver, the mouse cursor is hidden.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

mouse_install, mouse_uninstall, mouse_unload

Example

None.

3.147 mouse_move

Function

Move the mouse cursor to a specific position.

Header

mouse.h

Declaration

void __fastcall__ mouse_move (int x, int y);

Description

The function updates the mouse position. If the mouse cursor is visible, it is shown at the new position.

Notes

  • The function does not check if the new position is within the bounding box specified with mouse_setbox.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

mouse_getbox, mouse_setbox

Example

None.

3.148 mouse_pos

Function

Return the position of the mouse.

Header

mouse.h

Declaration

void __fastcall__ mouse_pos (struct mouse_pos* pos);

Description

The function returns the position of the mouse in the mouse_pos structure passed as parameter.

Notes

  • The mouse_pos struct is a subset of the mouse_info struct, so if you do also need the mouse buttons, call mouse_info instead.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

mouse_buttons, mouse_info

Example

None.

3.149 mouse_show

Function

Show the mouse pointer.

Header

mouse.h

Declaration

void mouse_show (void);

Description

The function shows the mouse pointer. It manages a counter that is shared between mouse_hide and mouse_show. The mouse cursor is visible if there was one more call to mouse_show than to mouse_hide.

Availability

cc65

See also

mouse_hide

Example

None.

3.150 mouse_uninstall

Function

Uninstall an already loaded mouse driver.

Header

mouse.h

Declaration

unsigned char mouse_uninstall (void);

Description

The function uninstalls an already loaded mouse driver but don't removes it from memory.

Notes

  • If the driver has been loaded using mouse_load_driver, mouse_unload should be used instead of mouse_uninstall so the driver is also removed from memory.

Availability

cc65

See also

mouse_install, mouse_load_driver, mouse_unload

Example

None.

3.151 mouse_unload

Function

Unload a mouse driver.

Header

mouse.h

Declaration

unsigned char mouse_unload (void);

Description

The function unloads a loaded mouse driver and frees all memory allocated for the driver.

Notes

  • The function does nothing if no driver is loaded.

Availability

cc65

See also

mouse_install, mouse_load_driver, mouse_uninstall

Example

None.

3.152 offsetof

Function

Calculate the offset of a struct or union member.

Header

stddef.h

Declaration

size_t offsetof (type, member);

Description

offsetof calculates the address offset of a struct or union member.

Notes

  • The function is actually a macro.

Availability

ISO 9899

Example

None.

3.153 open

Function

Open and possibly create a file.

Header

fcntl.h

Declaration

int open (const char* name, int flags, ...);

Description

open opens a file and returns the file descriptor associated with it. On error, -1 is returned and an error code is stored in errno. Several flags may be passed to open that change the behaviour.

Notes

  • POSIX specifies an additional mode argument that may be passed to open, which is used as the permission mask when a new file is created. While cc65 allows to pass this argument, it is ignored.

Availability

POSIX 1003.1

See also

close, creat

Example

None.

3.154 opendir

Function

Open a directory.

Header

dirent.h

Declaration

DIR* __fastcall__ opendir (const char* name);

Description

opendir opens a directory and returns the direcory descriptor associated with it. On error, NULL is returned and an error code is stored in errno.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

POSIX 1003.1

See also

closedir, readdir

Example

None.

3.155 peekbsys

Function

Read one byte from a location in the system bank.

Header

cbm610.h, cbm510.h

Declaration

unsigned char __fastcall__ peekbsys (unsigned addr);

Description

peekbsys reads one byte from the given address in the system bank (bank 15) of the CBM PET-II machines and returns it.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • This function may be a macro depending on the compiler options. The actual function is accessible by #undef'ing the macro.

Availability

cc65

See also

PEEK, PEEKW, peekwsys, pokebsys, pokewsys

Example

None.

3.156 peekwsys

Function

Read one word from a location in the system bank.

Header

cbm610.h, cbm510.h

Declaration

unsigned __fastcall__ peekwsys (unsigned addr);

Description

peekwsys reads one word from the given address in the system bank (bank 15) of the CBM PET-II machines and returns it. Following the usual 6502 conventions, the low byte is read from addr, and the high byte is read from addr+1.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The order in which the two bytes are read is undefined.

Availability

cc65

See also

PEEK, PEEKW, peekbsys, pokebsys, pokewsys

Example

None.

3.157 perror

Function

Print an error message for the error in errno.

Header

stdio.h

Declaration

void __fastcall__ perror (const char* s);

Description

perror prints an error message to stderr. If s is not NULL and not an empty string, it is printed followed by a colon and a blank. Then the error message for the current contents of errno is printed followed by a newline. The message output is the same as returned by strerror with an argument of errno.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

_poserror, strerror

Example

None.

3.158 pokebsys

Function

Write one byte to a location in the system bank.

Header

cbm610.h, cbm510.h

Declaration

void __fastcall__ pokebsys (unsigned addr, unsigned char val);

Description

pokebsys writes one byte to the given address in the system bank (bank 15) of the CBM PET-II machines.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

POKE, POKEW, peekbsys, peekwsys, pokewsys

Example

None.

3.159 pokewsys

Function

Write one word to a location in the system bank.

Header

cbm610.h, cbm510.h

Declaration

void __fastcall__ pokewsys (unsigned addr, unsigned val);

Description

pokewsys writes one word to the given address in the system bank (bank 15) of the CBM PET-II machines. Following the usual 6502 conventions, the low byte of val is written to addr, and the high byte is written to addr+1.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The order in which the two bytes are written is undefined.

Availability

cc65

See also

POKE, POKEW, peekbsys, peekwsys, pokebsys

Example

None.

3.160 qsort

Function

Sort an array.

Header

stdlib.h

Declaration

void __fastcall__ qsort (void* base, size_t count, size_t size, int __fastcall__ (* compare) (const void*, const void*));

Description

qsort sorts an array according to a given compare function compare. base is the address of the array, count is the number of elements, size the size of an element and compare the function used to compare the members.

Notes

  • If there are multiple members with the same key, the order after calling the function is undefined.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function to which compare points must have the fastcall calling convention.

Availability

ISO 9899

See also

bsearch

Example

None.

3.161 raise

Function

Send a signal to the executing program.

Header

signal.h

Declaration

int __fastcall__ raise (int sig);

Description

raise sends the given signal to the program. If the program has installed a signal handler for the signal, this signal handler will be executed. If no handler has been installed, the default action for the raised signal will be taken. The function returns zero on success, nonzero otherwise.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

abort, signal

Example

None.

3.162 rand

Function

Return a pseudo random number.

Header

stdlib.h

Declaration

int rand (void);

Description

The function returns a pseudo random number between 0 and RAND_MAX (exclusive).

Notes

  • Without using srand, always the same flow of numbers is generated.
  • On startup, the function behaves as if srand had been used with an argument of 1.

Availability

ISO 9899

See also

_randomize, srand

Example

None.

3.163 readdir

Function

Read a directory.

Header

dirent.h

Declaration

struct dirent* __fastcall__ readdir (DIR* dir);

Description

readdir reads the next directory entry from the directory stream pointed to by dir. It stores the data in a dirent structure and returns a pointer to it. If the end of directory is reached, or an error occurs, NULL is returned. In case of errors, an error code is stored into errno.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The returned pointer may point to a statically allocated instance of struct dirent, so it may get overwritten by subsequent calls to readdir.
  • On several platforms, namely the CBMs and the Atari, the disk drives get confused when opening/closing files between directory reads. So for example a program that reads the list of files on a disk, and after each call to readdir, opens the file to process it, will fail.
    Possible solutions are reading the directory into memory before processing the file list, or to reset the directory by seeking to the correct position after opening/closing a file:
            seekdir (DIR, telldir (DIR));
    
    Platforms known to work without problems are: Apple.

Availability

POSIX 1003.1

See also

closedir, opendir

Example

None.

3.164 realloc

Function

Change the size of an allocated memory block.

Header

stdlib.h

Declaration

void* __fastcall__ realloc (void* block, size_t size);

Description

realloc changes the size of the memory block pointed to by block to size bytes. If block is NULL, realloc behaves as if malloc had been called. If size is zero, realloc behaves as if free had been called. On error (not enough memory available), realloc returns NULL.

Notes

  • The part of the memory block that is returned will have its contents unchanged.
  • This function is somewhat dangerous to use. Be careful to save the pointer you're passing somewhere else, otherwise
            ptr = realloc (ptr, size);
    
    will loose your only copy of ptr if realloc returns NULL.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

_heapadd, _heapblocksize, _heapmaxavail, _heapmemavail, calloc, free, realloc

Example

None.

3.165 remove

Function

Delete a file.

Header

stdio.h

Declaration

int __fastcall__ remove (const char* name);

Description

remove deletes the file with the given name. On success, zero is returned. On error, -1 is returned and errno is set to an error code describing the reason for the failure.

Notes

  • This function is not available on all cc65 targets (depends on the availability of file I/O).
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

rename, unlink

Example

#include <stdio.h>

#define FILENAME "helloworld"

if (remove (FILENAME) == 0) {
    printf ("We deleted %s successfully\n", FILENAME);
} else {
    printf ("There was a problem deleting %s\n", FILENAME);
}

3.166 rename

Function

Rename a file.

Header

stdio.h

Declaration

int __fastcall__ rename (const char* oldname, const char* newname);

Description

rename renames a file (gives it a new name). On success, zero is returned. On error, -1 is returned and errno is set to an error code describing the reason for the failure.

Notes

  • This function is not available on all cc65 targets (depends on the capabilities of the storage devices).
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

remove

Example

#include <stdio.h>

#define OLDNAME "textfile.txt"
#define NEWNAME "textfile.bak"

if (rename (OLDNAME, NEWNAME) == 0) {
    printf ("Renamed %s to %s\n", OLDNAME, NEWNAME);
} else {
    printf ("Error renaming %s to %s\n", OLDNAME, NEWNAME);
}

3.167 reset_brk

Function

Resets the break vector to its original value.

Header

6502.h

Declaration

void reset_brk (void);

Description

reset_brk resets the break vector to the value it had before a call to set_brk.

Notes

  • 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.

Availability

cc65

See also

reset_irq, set_brk, set_irq

Example

None.

3.168 reset_irq

Function

Resets the C level interrupt request vector.

Header

6502.h

Declaration

void reset_irq (void);

Description

reset_irq resets the C level interrupt request vector.

Notes

  • 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.

Availability

cc65

See also

reset_brk, set_brk, set_irq

Example

None.

3.169 revers

Function

Control revers character display.

Header

conio.h

Declaration

unsigned char __fastcall__ revers (unsigned char onoff);

Description

If the argument is non zero, the function enables reverse character display. If the argument is zero, reverse character display is switched off. The old value of the setting is returned.

Notes

  • The function may not be supported by the hardware, in which case the call is ignored.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

textcolor

Example

None.

3.170 rewinddir

Function

Reset a directory stream.

Header

dirent.h

Declaration

void __fastcall__ rewinddir (DIR* dir);

Description

rewinddir sets the position of the directory stream pointed to by dir to the start of the directory.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

POSIX 1003.1

See also

seekdir, telldir

Example

None.

3.171 screensize

Function

Return the dimensions of the text mode screen.

Header

conio.h

Declaration

void __fastcall__ screensize (unsigned char* x, unsigned char* y);

Description

The function returns the dimensions of the text mode screen.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

gotox, gotoxy, gotoy, wherex, wherey

Example

None.

3.172 seekdir

Function

Set the position of a directory stream.

Header

dirent.h

Declaration

void __fastcall__ seekdir (DIR* dir, long offset);

Description

seekdir sets the position of the directory stream pointed to by dir to the value given in offset, which should be a value returned by telldir.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

POSIX 1003.1

See also

rewinddir, telldir

Example

None.

3.173 ser_close

Function

Close the port and disable interrupts

Header

serial.h

Declaration

unsigned char ser_close (void);

Description

Close the port by clearing buffers and disable interrupts.

Availability

cc65

See also

Other serial functions.

Example

#include <serial.h>

static void initialize(){
  struct ser_params params = {
    SER_BAUD_9600,
    SER_BITS_8,
    SER_STOP_1,
    SER_PAR_MARK,
    SER_HS_NONE
  };
  ser_install(lynx_comlynx); // This will activate the ComLynx
  CLI();
  ser_open(&params);
}

3.174 ser_get

Function

Read a character from serial port.

Header

serial.h

Declaration

unsigned char __fastcall__ ser_get (char* b);

Description

Get a character from the serial port. If no characters are available, the function will return SER_ERR_NO_DATA, so this is not a fatal error.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other serial functions.

Example

Wait for a character to be available from a serial port.

char ch;
while (ser_get(&ch) == SER_ERR_NO_DATA)
  ;

3.175 ser_install

Function

Install an already loaded driver and return an error code.

Header

serial.h

Declaration

unsigned char __fastcall__ ser_install (void* driver);

Description

The function installs a driver that was already loaded into memory (or linked statically to the program). It returns an error code (SER_ERR_OK in case of success).

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

ser_load_driver, ser_uninstall, ser_unload

Example

ser_install(lynx_comlynx); //Include the driver statically instead of loading it.

3.176 ser_ioctl

Function

Platform dependent code extensions.

Header

serial.h

Declaration

unsigned __fastcall__ ser_ioctl (unsigned char code, void* data);

Description

Some platforms have extra serial functions that are not supported by standard serial driver functions. You can extend the driver to support this extra functionality bt using ser_ioctl functions.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • These functions are not easily portable to other cc65 platforms.

Availability

cc65

See also

Other serial functions.

Example

None

3.177 ser_load_driver

Function

Load and install a serial driver.

Header

serial.h

Declaration

unsigned char __fastcall__ ser_load_driver (const char *name);

Description

Load and install the driver by name. Will just load the driver and check if loading was successful.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other serial functions.

Example

None.

3.178 ser_open

Function

Open the port by setting the port parameters and enable interrupts

Header

serial.h

Declaration

unsigned char __fastcall__ ser_open (const struct ser_params* params);

Description

Open the port by setting the port parameters and enable interrupts.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other serial functions.

Example

#include <serial.h>

static void initialize(){
  struct ser_params params = {
    SER_BAUD_9600,
    SER_BITS_8,
    SER_STOP_1,
    SER_PAR_MARK,
    SER_HS_NONE
  };
  ser_install(lynx_comlynx); // This will activate the ComLynx
  CLI();
  ser_open(&params);
}

3.179 ser_put

Function

Write a character to a serial port.

Header

serial.h

Declaration

unsigned char __fastcall__ ser_put (char b);

Description

Send a character via the serial port. There is a transmit buffer, but transmitting is not done via interrupt. The function returns SER_ERR_OVERFLOW if there is no space left in the transmit buffer.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other serial functions.

Example

ser_put('A');

3.180 ser_status

Function

Return the serial port status.

Header

serial.h

Declaration

unsigned char __fastcall__ ser_status (unsigned char* status);

Description

Return the serial port status.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other serial functions.

Example

None

3.181 ser_uninstall

Function

Uninstall the currently loaded driver but do not unload it.

Header

serial.h

Declaration

unsigned char ser_uninstall (void);

Description

Uninstall the currently loaded driver but do not unload it.

Availability

cc65

See also

Other serial functions.

Example

None.

3.182 ser_unload

Function

Uninstall, then unload the currently loaded driver.

Header

serial.h

Declaration

unsigned char ser_unload (void);

Description

Uninstall, then unload the currently loaded driver.

Availability

cc65

See also

Other serial functions.

Example

None.

3.183 set_brk

Function

Set the break vector to a user function.

Header

6502.h

Declaration

void __fastcall__ set_brk (brk_handler func);

Description

set_brk allows a user program to handle breaks within the program code by letting the vector point to a user written C function. The runtime library installs a small stub that saves the registers into global variables that may be accessed (and changed) by the break handler.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The stub saves the zero page registers used by the C runtime and switches to a small break handler stack. This means that it is safe to execute C code, even if C code was interrupted. Be careful however not to use too many local variables, and do not enable stack checks for the handler function or any other function called from it.
  • The brk_pc variable points to the BRK instruction. If you want the continue with the interrupted code, you have to adjust brk_pc, otherwise the BRK instruction will get executed over and over again.
  • The break vector is reset on program termination, so it's not strictly necessary to call reset_brk as a part of your clean-up when exitting the program.

Availability

cc65

See also

reset_brk

Example

None.

3.184 set_irq

Function

Set the C level interrupt request vector to the given address.

Header

6502.h

Declaration

void __fastcall__ set_irq (irq_handler f, void *stack_addr, size_t stack_size);

Description

set_irq allows a user program to handle interrupt requests (IRQs) within the program code by letting the vector point to a user written C function. The runtime library installs a small stub that saves the zero page registers used by the C runtime before calling the handler function and restores them after the handler function returns. Additionally the stub temporarily switches the C runtime stack to the stack area provided as parameter. If the handler function was set up to handle a "private", "exclusive" interrupt request source it must return the value IRQ_HANDLED if and only if it has verified that the current interrupt request actually stems from that source. In all other cases it must return the value IRQ_NOT_HANDLED.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The stub saves the registers and zero page locations used by the C runtime and switches to the provided stack area. As a consequence, there is some runtime overhead, but it it is safe to execute C code, even if other C code 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.
  • The interrupt vector is reset on program termination, so it's not strictly necessary to call reset_irq as a part of your clean-up when exitting the program.

Availability

cc65

See also

reset_brk, reset_irq, set_brk

Example

None.

3.185 setjmp

Function

Save the context for use with longjmp.

Header

setjmp.h

Declaration

int __fastcall__ setjmp (jmp_buf buf);

Description

The setjmp function saves the current context in buf for subsequent use by the longjmp function and returns zero.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • setjmp is actually a macro as required by the ISO standard.
  • setjmp will not save the signal context.

Availability

ISO 9899

See also

longjmp

Example

None.

3.186 setlocale

Function

Selects a locale.

Header

locale.h

Declaration

char* __fastcall__ setlocale (int category, const char* locale);

Description

setlocale sets or queries the program's locale.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • cc65 supports only the "C" locale, so calling this function to set a different locale has no effect.

Availability

ISO 9899

See also

localeconv, strcoll strxfrm

Example

None.

3.187 signal

Function

Install a signal handler.

Header

signal.h

Declaration

__sigfunc __fastcall__ signal (int sig, __sigfunc func);

Description

signal installs a handler for the given signal. The handler may either be a user supplied function, or one of the predefined signal handlers SIG_IGN or SIG_DFL. The function returns the previous value if the signal , or the special function vector SIG_ERR in case of an error.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

abort, raise

Example

None.

3.188 sleep

Function

Sleep for a specified amount of time.

Header

unistd.h

Declaration

void __fastcall__ sleep (unsigned seconds);

Description

The function will return after the specified number of seconds have elapsed.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

POSIX 1003.1

Example

None.

3.189 slow

Function

Switch the C128 into 1MHz mode.

Header

c128.h

Declaration

void slow (void);

Description

The function will switch the clock of the C128 to 1MHz. This will halve the speed compared to fast mode.

Notes

  • The function is specific to the C128.

Availability

C128

See also

fast, toggle_videomode, videomode

Example

None.

3.190 srand

Function

Initialize the pseudo random number generator.

Header

stdlib.h

Declaration

void __fastcall__ srand (unsigned seed);

Description

The function initializes the random number generator using the given seed. On program startup, the generator behaves as if srand has been called with an argument of 1.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

_randomize, rand

Example

None.

3.191 strcasecmp

Function

Compare two strings case insensitive.

Header

string.h

Declaration

int __fastcall__ strcasecmp (const char* s1, const char* s2);

Description

The strcasecmp function compares the two strings passed as parameters without case sensitivity. It returns a value that is less than zero if s1 is less than s2, zero if s1 is the same as s2, and a value greater than zero if s1 is greater than s2.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function is not available in strict ANSI mode.

Availability

cc65

See also

strcmp, strcoll, stricmp, strncmp, strxfrm

Example

None.

3.192 strcat

Function

Concatentate two strings.

Header

string.h

Declaration

char* __fastcall__ strcat (char* s1, const char* s2);

Description

The strcat function appends a copy of the string pointed to by s2 (including the terminating null byte) to the end of the string pointed to by s1. The initial byte of s2 overwrites the null byte at the end of s1.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • If copying takes place between objects that overlap, the behaviour is undefined.

Availability

ISO 9899

See also

strcpy, strncat, strncpy

Example

None.

3.193 strchr

Function

Search for a character in a string.

Header

string.h

Declaration

char* __fastcall__ strchr (const char* s, int c);

Description

The strchr function locates the first occurrence of c (converted to a char) in the string pointed to by s. The terminating null byte is considered to be part of the string. Upon completion, the function returns a pointer to the byte, or a null pointer if the byte was not found.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

memchr, strrchr

Example

None.

3.194 strcmp

Function

Compare two strings.

Header

string.h

Declaration

int __fastcall__ strcmp (const char* s1, const char* s2);

Description

The strcmp function compares the two strings passed as parameters. It returns a value that is less than zero if s1 is less than s2, zero if s1 is the same as s2, and a value greater than zero if s1 is greater than s2.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

strcasecmp, strcoll, stricmp, strncmp strxfrm

Example

None.

3.195 strcoll

Function

Compare two strings.

Header

string.h

Declaration

int __fastcall__ strcoll (const char* s1, const char* s2);

Description

The strcoll function compares the two strings passed as parameters, according to the collating sequence set by setlocale. It returns a value that is less than zero if s1 is less than s2, zero if s1 is the same as s2, and a value greater than zero if s1 is greater than s2.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

setlocale, strcasecmp, strcmp, stricmp, strncmp, strxfrm

Example

None.

3.196 strcpy

Function

Copy a string.

Header

string.h

Declaration

char* __fastcall__ strcpy (char* s1, const char* s2);

Description

The strcpy function copies the string pointed to by s2 (including the terminating null byte) into the array pointed to by s1. The function will always return s1.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • If copying takes place between objects that overlap, the behaviour is undefined.

Availability

ISO 9899

See also

strcat, strncat, strncpy

Example

#include <string.h>

static char hello[14];

strcpy (hello, "Hello world!\n");

3.197 strcspn

Function

Compute the length of a substring.

Header

string.h

Declaration

size_t __fastcall__ strcspn (const char* s, const char* set);

Description

The strcspn function computes and returns the length of the substring pointed to by s which does not consist of characters contained in the string set.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

strqtok, strspn, strstr, strtok

Example

None.

3.198 strdup

Function

Allocate a copy of a string on the heap.

Header

string.h

Declaration

char* __fastcall__ strdup (const char* s);

Description

strdup allocates a memory block on the heap, big enough to hold a copy of s including the terminating zero. If the allocation fails, NULL is returned, otherwise s is copied into the allocated memory block, and a pointer to the block is returned.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • It is up to the caller to free the allocated memory block.

Availability

ISO 9899

See also

free, malloc

Example

None.

3.199 strerror

Function

Return a string describing an error code.

Header

string.h

Declaration

char* __fastcall__ strerror (int errcode);

Description

The strerror function returns a string describing the given error code. If an invalid error code is passed, the string "Unknown error" is returned, and errno is set to EINVAL. In all other cases, errno is left untouched.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • While the return type of the function is a char*, the returned string must not be modified by the caller!

Availability

ISO 9899

See also

_stroserror

Example

None.

3.200 stricmp

Function

Compare two strings case insensitive.

Header

string.h

Declaration

int __fastcall__ stricmp (const char* s1, const char* s2);

Description

The stricmp function compares the two strings passed as parameters without case sensitivity. It returns a value that is less than zero if s1 is less than s2, zero if s1 is the same as s2, and a value greater than zero if s1 is greater than s2.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function is not available in strict ANSI mode.

Availability

cc65

See also

strcasecmp, strcmp, strcoll, strncmp, strxfrm

Example

None.

3.201 strlen

Function

Return the length of a string.

Header

string.h

Declaration

size_t __fastcall__ strlen (const char* s);

Description

The strlen function computes the number of bytes in the string to which s points, not including the terminating null byte.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • When compiling with -Os (inline known standard functions), the function does not work correctly for strings with more than 255 characters.

Availability

ISO 9899

See also

strcpy

Example

None.

3.202 strlower

Function

Make a string lower case.

Header

string.h

Declaration

char* __fastcall__ strlower (char* s);

Description

The strlower function will apply the tolower function to each character of a string. The function will always return s.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function prototype is unavailable when compiling in strict ANSI mode.
  • An alias name for this function is strlwr.

Availability

cc65

See also

strupper, tolower

Example

None.

3.203 strlwr

See strlower.

3.204 strncat

Function

Concatentate two strings.

Header

string.h

Declaration

char* __fastcall__ strncat (char* s1, const char* s2, size_t n);

Description

The strncat function appends not more than n characters of the string pointed to by s2 to the end of the string pointed to by s1. The terminating null character at the end of s1 is overwritten. A terminating null character is appended to the result, even if not all of s2 is appended to s1.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • If copying takes place between objects that overlap, the behaviour is undefined.

Availability

ISO 9899

See also

strcpy, strncat, strncpy

Example

None.

3.205 strncmp

Function

Compare two strings.

Header

string.h

Declaration

int __fastcall__ strncmp (const char* s1, const char* s2, size_t count);

Description

The strncmp function compares not more than count characters of the two strings passed as parameters. It returns a value that is less than zero if the first count characters of s1 are less than s2, zero if they are identical, and a value greater than zero they are greater.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

strcasecmp, strcmp, strcoll, stricmp, strxfrm

Example

None.

3.206 strncpy

Function

Copy part of a string.

Header

string.h

Declaration

char* __fastcall__ strncpy (char* s1, const char* s2, size_t n);

Description

The strncpy function copies not more than n bytes from the array pointed to by s2 to the array pointed to by s1. If the array pointed to by s2 is a string that is shorter than n bytes, null bytes are appended to the copy in the array pointed to by s1, until n bytes are written. The function always will return s1.

Notes

  • The function is available only as a fastcall function; so, it may be used only in the presence of a prototype.
  • If there is no null byte in the first n bytes of the array pointed to by s2, the result is not null-terminated!
  • If copying takes place between objects that overlap, the behaviour is undefined.

Availability

ISO 9899

See also

memcpy, strcat, strcpy, strncat

Example

#include <string.h>

static char hello[6];

strncpy (hello, "Hello world!\n", sizeof hello - 1)[5] = '\0';

3.207 strqtok

Function

Break a string into tokens.

Header

string.h

Declaration

char* __fastcall__ strqtok (char* s1, const char* s2);

Description

strqtok() will break the string s1 into a sequence of tokens, which are delimited by either quotation marks or characters from the string s2. Tokens inside quotation marks may contain characters from s2 (they aren't delimiters there). The first call to strqtok() will return a pointer to the first token in the string s1. The following calls must pass a NULL pointer as s1, in order to get the next token in the string. Different sets of delimiters may be used for the subsequent calls to strqtok().

Notes

  • The function is available only as a fastcall function; so, it may be used only in the presence of a prototype.
  • strqtok() will modify the string s1.
  • The function will forget where it is in the s1 string if it is given a second s1 string before it finishes the first one.

Availability

cc65

See also

strcspn, strspn, strtok

Example

None.

3.208 strrchr

Function

Search for a character in a string.

Header

string.h

Declaration

char* __fastcall__ strrchr (const char* s, int c);

Description

The strrchr function locates the last occurrence of c (converted to a char) in the string pointed to by s. The terminating null byte is considered to be part of the string. Upon completion, the function returns a pointer to the byte, or a null pointer if the byte was not found.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

strchr

Example

None.

3.209 strspn

Function

Compute the length of a substring.

Header

string.h

Declaration

size_t __fastcall__ strspn (const char* s, const char* set);

Description

The strspn function computes and returns the length of the substring pointed to by s which does consist only of characters contained in the string set.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

strcspn, strstr

Example

None.

3.210 strstr

Function

Find a substring.

Header

string.h

Declaration

char* __fastcall__ strstr (const char* str, const char* substr);

Description

strstr searches for the first occurance of the string substr within str. If found, it returns a pointer to the copy, otherwise it returns NULL.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

strcspn, strspn

Example

None.

3.211 strtok

Function

Break a string into tokens.

Header

string.h

Declaration

char* __fastcall__ strtok (char* s1, const char* s2);

Description

strtok() will break the string s1 into a sequence of tokens, which are delimited by characters from the string s2. The first call to strtok() will return a pointer to the first token in the string s1. The following calls must pass a NULL pointer as s1, in order to get the next token in the string. Different sets of delimiters may be used for the subsequent calls to strtok().

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • strtok() will modify the string s1.
  • The function will forget where it is in the s1 string if it is given a second s1 string before it finishes the first one.

Availability

ISO 9899

See also

strcspn, strqtok, strspn

Example

None.

3.212 strxfrm

Function

Transform a string.

Header

string.h

Declaration

size_t __fastcall__ strxfrm (char* s1, const char* s2, size_t n);

Description

The strxfrm function transforms the string pointed to by s2 and places the resulting string into the string pointed to by s1. The transformation is such that if the strcmp function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the strcoll function applied to the same two original strings. No more than n characters are placed into the resulting array pointed to by s1, including the terminating null character.

Notes

  • s1 and s2 must not point to the same memory area, otherwise the behaviour is undefined.
  • If n is zero, s1 may be a NULL pointer.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • Since cc65 doesn't support different charcter sets, strxfrm will just copy s2 to s1 using strncpy.

Availability

ISO 9899

See also

strcmp, strcoll, strncpy

Example

None.

3.213 strupper

Function

Make a string upper case.

Header

string.h

Declaration

char* __fastcall__ strupper (char* s);

Description

The strupper function will apply the toupper function to each character of a string. The function will always return s.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function prototype is unavailable when compiling in strict ANSI mode.
  • An alias name for this function is strupr.

Availability

cc65

See also

strlower toupper

Example

None.

3.214 strupr

See strupper.

3.215 telldir

Function

Return the current position of a directory stream.

Header

dirent.h

Declaration

long __fastcall__ telldir (DIR* dir);

Description

telldir returns the current position of a directory stream. The return value may be used in subsequent calls to seekdir.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

POSIX 1003.1

See also

seekdir, telldir

Example

None.

3.216 textcolor

Function

Set the text color.

Header

conio.h

Declaration

unsigned char __fastcall__ textcolor (unsigned char color);

Description

The function will set a new text color. It returns the old (current) text color. Text output using any conio.h function will use the color set by this function.

Notes

  • Text colors are system dependent. The function may have no effect on systems where the text color cannot be changed.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

bgcolor, bordercolor

Example

None.

3.217 tgi_arc

Function

Draw an elliptic arc in the current color.

Header

tgi.h

Declaration

void __fastcall__ tgi_arc (int x, int y, unsigned char rx, unsigned char ry, unsigned sa, unsigned ea);

Description

The function draws an elliptic arc with center at x/y and radii rx/ry using the current drawing color. The arc covers the angle between sa and ea (startangle and endangle), which must be in the range 0..360.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function behaves unexpectedly or may crash if the angles are out of range.

Availability

cc65

See also

tgi_bar, tgi_circle, tgi_ellipse, tgi_pieslice, tgi_setcolor

Example

/* Draw the upper half of an ellipse */
tgi_setcolor(TGI_COLOR_BLUE);
tgi_arc (50, 50, 40, 20, 0, 180);

3.218 tgi_bar

Function

The function fills a rectangle on the drawpage with the current color.

Header

tgi.h

Declaration

void __fastcall__ tgi_bar (int x1, int y1, int x2, int y2);

Description

The function fills a rectangle on the drawpage with the current color.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi function

Example

tgi_setcolor(TGI_COLOR_GREEN);
tgi_bar(10, 10, 100, 60);

3.219 tgi_circle

Function

The function draws a circle in the current color.

Header

tgi.h

Declaration

void __fastcall__ tgi_circle (int x, int y, unsigned char radius);

Description

The function draws a circle in the current color.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

tgi_arc, tgi_bar, tgi_ellipse, tgi_pieslice, tgi_setcolor

Example

tgi_setcolor(TGI_COLOR_BLACK);
tgi_circle(50, 40, 40);

3.220 tgi_clear

Function

Clear the drawpage

Header

tgi.h

Declaration

void tgi_clear (void);

Description

Clear the drawpage

Availability

cc65

See also

Other tgi functions

Example

None.

3.221 tgi_done

Function

End graphics mode, switch back to text mode. Will NOT uninstall or unload the driver!

Header

tgi.h

Declaration

void tgi_done (void);

Description

End graphics mode, switch back to text mode. Will NOT uninstall or unload the driver!

Availability

cc65

See also

Other tgi functions

Example

None.

3.222 tgi_ellipse

Function

The function draws an ellipse in the current color.

Header

tgi.h

Declaration

void __fastcall__ tgi_ellipse (int x, int y, unsigned char rx, unsigned char ry);

Description

The function draws an ellipse at position x/y with radii rx and ry, using the current drawing color.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

tgi_arc, tgi_bar, tgi_circle, tgi_pieslice, tgi_setcolor

Example

tgi_setcolor(TGI_COLOR_RED);
tgi_ellipse (50, 40, 40, 20);

3.223 tgi_free_vectorfont

Function

Free a vector font that was previously loaded into memory.

Header

tgi.h

Declaration

void __fastcall__ tgi_free_vectorfont (const tgi_vectorfont* font);

Description

Free a vector font that was previously loaded into memory.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

tgi_load_vectorfont, tgi_install_vectorfont

Example

None.

3.224 tgi_getaspectratio

Function

Return the pixel aspect ratio.

Header

tgi.h

Declaration

unsigned tgi_getaspectratio (void);

Description

The function returns the pixel aspect ratio for the current driver and display as an 8.8 fixed point value. It may be used to correct geometric shapes so they look correct on the display. As an example, a circle with a radius of 100 pixels may look elliptic on some driver/display combinations if the aspect ratio is not 1.00.

Notes

  • The aspect ratio is encoded in the TGI driver which assumes a "standard" monitor for the given platform. The aspect ratio may be wrong if another monitor is used.
  • No TGI function will use the aspect ratio. It is up to the programmer to make use of it.
  • The tgi_setaspectratio function can be used to change the aspect ratio for a loaded driver. The value is not reset by 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.

Availability

cc65

See also

tgi_setaspectratio

Example

None.

3.225 tgi_getcolor

Function

Return the current drawing color.

Header

tgi.h

Declaration

unsigned char tgi_getcolor (void);

Description

The actual color is an index to a palette. During tgi_init you will get a default palette. The number of colors depend on the platform. All platforms recognize at least TGI_COLOR_BLACK and TGI_COLOR_WHITE. But some platforms have many more predefined colors. If you paint using TGI_COLOR_GREEN and then you change the green of the palette to blue using tgi_setpalette then after this painting in TGI_COLOR_GREEN will actually be blue.

Availability

cc65

See also

Other tgi functions

Example

color = tgi_getcolor();

3.226 tgi_getcolorcount

Function

Get the number of available colors.

Header

tgi.h

Declaration

unsigned char tgi_getcolorcount (void);

Description

Tgi platforms use indexed color palettes. This function returns the number of entries we can use in the palette.

Availability

cc65

See also

Other tgi functions

Example

if (tgi_getcolorcount() == 2) {
  printf("Only monochrome graphics is supported\n");
}

3.227 tgi_getdefpalette

Function

Get the palette installed by default.

Header

tgi.h

Declaration

const unsigned char* tgi_getdefpalette (void);

Description

The tgi driver has a default palette that is active at startup. The named colors TGI_COLOR_BLACK, TGI_COLOR_WHITE, TGI_COLOR_RED... need this palette to work correctly.

Availability

cc65

See also

Other tgi functions

Example

None.

3.228 tgi_geterror

Function

Return the error code for the last operation. This will also clear the error.

Header

tgi.h

Declaration

unsigned char tgi_geterror (void);

Description

Return the error code for the last operation. This will also clear the error.

Availability

cc65

See also

Other tgi functions

Example

None.

3.229 tgi_geterrormsg

Function

Get an error message describing the error.

Header

tgi.h

Declaration

const char* __fastcall__ tgi_geterrormsg (unsigned char code);

Description

Get an error message describing the error.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions

Example

None.

3.230 tgi_getmaxcolor

Function

Get the highest index of the palette.

Header

tgi.h

Declaration

unsigned char tgi_getmaxcolor (void);

Description

Get the highest index of the palette.

Availability

cc65

See also

Other tgi functions

Example

None.

3.231 tgi_getmaxx

Function

Get the maximum x coordinate that can be used on this screen.

Header

tgi.h

Declaration

unsigned tgi_getmaxx (void);

Description

Get the maximum x coordinate that can be used on this screen.

Availability

cc65

See also

Other tgi functions

Example

None.

3.232 tgi_getmaxy

Function

Get the maximum y coordinate that can be used on this screen.

Header

tgi.h

Declaration

unsigned tgi_getmaxy (void);

Description

Get the maximum y coordinate that can be used on this screen.

Availability

cc65

See also

Other tgi functions

Example

None.

3.233 tgi_getpagecount

Function

Return the number of screen pages available.

Header

tgi.h

Declaration

unsigned tgi_getpagecount (void);

Description

Return the number of screen pages available.

Availability

cc65

See also

tgi_setdrawpage, tgi_setviewpage

Example

None.

3.234 tgi_getpalette

Function

Get the palette installed.

Header

tgi.h

Declaration

const unsigned char* tgi_getpalette (void);

Description

Get the palette installed.

Availability

cc65

See also

Other tgi functions

Example

None.

3.235 tgi_getpixel

Function

Get the color of a pixel from the viewpage.

Header

tgi.h

Declaration

unsigned char __fastcall__ tgi_getpixel (int x, int y);

Description

Get the color of a pixel from the viewpage.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

3.236 tgi_getxres

Function

Get number of horisontal pixels on the screen.

Header

tgi.h

Declaration

unsigned tgi_getxres (void);

Description

Get number of horisontal pixels on the screen. This is same as tgi_maxx()+1.

Availability

cc65

See also

Other tgi functions.

Example

None.

3.237 tgi_getyres

Function

Get number of vertical pixels on the screen.

Header

tgi.h

Declaration

unsigned tgi_getyres (void);

Description

Get number of vertical pixels on the screen. This is same as tgi_maxy()+1.

Availability

cc65

See also

Other tgi functions.

Example

None.

3.238 tgi_gotoxy

Function

Set graphics cursor at x, y.

Header

tgi.h

Declaration

void __fastcall__ tgi_gotoxy (int x, int y);

Description

Set graphics cursor at x, y.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

3.239 tgi_init

Function

Initialize the already loaded graphics driver.

Header

tgi.h

Declaration

void tgi_init (void);

Description

The tgi_init function will set the default palette to the hardware.

Notes

  • tgi_init will not clear the screen. This allows switching between text and graphics mode on platforms that have separate memory areas for the screens. If you want the screen cleared, call tgi_clear after tgi_init.

Availability

cc65

See also

Other tgi functions.

Example

tgi_install(tgi_static_stddrv); //Include the driver statically instead of loading it.
tgi_init(); //Set up the default palette and clear the screen.

3.240 tgi_install

Function

Install an already loaded driver and return an error code.

Header

tgi.h

Declaration

unsigned char __fastcall__ tgi_install (void* driver);

Description

The function installs a driver that was already loaded into memory (or linked statically to the program). It returns an error code (TGI_ERR_OK in case of success).

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

tgi_load_driver, tgi_uninstall, tgi_unload

Example

tgi_install(tgi_static_stddrv); //Include the driver statically instead of loading it.
tgi_init(); //Set up the default palette and clear the screen.

3.241 tgi_install_vectorfont

Function

Install an already loaded driver and return an error code.

Header

tgi.h

Declaration

void __fastcall__ tgi_install_vectorfont (const tgi_vectorfont* font);

Description

Install a vector font for use. More than one vector font can be loaded, but only one can be active. This function is used to tell which one. Call with a NULL pointer to uninstall the currently installed font.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

tgi_load_vectorfont, tgi_free_vectorfont

Example

None.

3.242 tgi_ioctl

Function

Platform dependent code extensions.

Header

tgi.h

Declaration

unsigned __fastcall__ tgi_ioctl (unsigned char code, void* data);

Description

Some platforms have extra display hardware that is not supported by standard tgi functions. You can extend the driver to support this extra hardware using tgi_ioctl functions.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • These functions are not easily portable to other cc65 platforms.

Availability

cc65

See also

Other tgi functions.

Example

#define tgi_sprite(spr) tgi_ioctl(0, (void*)(spr))
#define tgi_flip() tgi_ioctl(1, (void*)0)
#define tgi_setbgcolor(bgcol) tgi_ioctl(2, (void*)(bgcol))
#define tgi_setframerate(rate) tgi_ioctl(3, (void*)(rate))
#define tgi_busy() tgi_ioctl(4, (void*)0)
#define tgi_updatedisplay() tgi_ioctl(4, (void*)1)
if (!tgi_busy()) {
  tgi_sprite(&background);
  tgi_setcolor(TGI_COLOR_BLUE);
  tgi_outttextxy(20,40,"Hello World");
  tgi_updatedisplay();
}

3.243 tgi_line

Function

Draw a line in the current drawing color. The graphics cursor will be set to x2/y2 by this call.

Header

tgi.h

Declaration

void __fastcall__ tgi_line (int x1, int y1, int x2, int y2);

Description

Draw a line in the current drawing color. The graphics cursor will be set to x2/y2 by this call.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

3.244 tgi_lineto

Function

Draw a line in the current drawing color from the graphics cursor to the new end point. The graphics cursor will be updated to x2/y2.

Header

tgi.h

Declaration

void __fastcall__ tgi_lineto (int x2, int y2);

Description

Draw a line in the current drawing color from the graphics cursor to the new end point. The graphics cursor will be updated to x2/y2.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

3.245 tgi_load_driver

Function

Load and install the given driver.

Header

tgi.h

Declaration

void __fastcall__ tgi_load_driver (const char *name);

Description

Load and install the driver by name. Will just load the driver and check if loading was successful. Will not switch to graphics mode.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

3.246 tgi_load_vectorfont

Function

Load the given vector font.

Header

tgi.h

Declaration

const tgi_vectorfont* __fastcall__ tgi_load_vectorfont (const char* name);

Description

Load a vector font into memory and return it. In case of errors, NULL is returned and an error is set, which can be retrieved using tgi_geterror. To use the font, it has to be installed using tgi_install_vectorfont.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

tgi_install_vectorfont, tgi_free_vectorfont

Example

None.

3.247 tgi_outtext

Function

Output text at the current graphics cursor position. The graphics cursor is moved to the end of the text.

Header

tgi.h

Declaration

void __fastcall__ tgi_outtext (const char* s);

Description

Output text at the current graphics cursor position. The graphics cursor is moved to the end of the text.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

3.248 tgi_outtextxy

Function

Output text at the given cursor position. The graphics cursor is moved to the end of the text.

Header

tgi.h

Declaration

void __fastcall__ tgi_outtextxy (int x, int y, const char* s);

Description

Output text at the given cursor position. The graphics cursor is moved to the end of the text.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

3.249 tgi_pieslice

Function

Draw an elliptic pie slice in the current color.

Header

tgi.h

Declaration

void __fastcall__ tgi_pie slice (int x, int y, unsigned char rx, unsigned char ry, unsigned sa, unsigned ea);

Description

The function draws an elliptic pie slice with center at x/y and radii rx/ry using the current drawing color. The pie slice covers the angle between sa and ea (startangle and endangle), which must be in the range 0..360.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function behaves unexpectedly or may crash if the angles are out of range.

Availability

cc65

See also

tgi_arc, tgi_bar, tgi_circle, tgi_ellipse, tgi_setcolor

Example

/* Draw the closed upper half of an ellipse */
tgi_setcolor(TGI_COLOR_BLUE);
tgi_pieslice (50, 50, 40, 20, 0, 180);

3.250 tgi_setaspectratio

Function

Set the pixel aspect ratio.

Header

tgi.h

Declaration

void __fastcall__ tgi_setaspectratio (unsigned ratio);

Description

The function sets the pixel aspect ratio for the current driver and display. The argument is an 8.8 fixed point value. The aspect ratio may be used to correct geometric shapes so they look correct on a given display. As an example, a circle with a radius of 100 pixels may look elliptic on some driver/display combinations if the aspect ratio is not 1.00.

Notes

  • The aspect ratio is encoded in the TGI driver which assumes a "standard" monitor for the given platform. The aspect ratio may be wrong if another monitor is used.
  • No TGI function will use the aspect ratio. It is up to the programmer to make use of it.
  • The tgi_setaspectratio function can be used to change the aspect ratio for a loaded driver. The value is not reset by 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.
  • The function is available only as a fastcall function; so, it may be used only in the presence of a prototype.

Availability

cc65

See also

tgi_getaspectratio

Example

None.

3.251 tgi_setcolor

Function

Set color to be used in future draw operations.

Header

tgi.h

Declaration

void __fastcall__ tgi_setcolor (unsigned char color);

Description

Set color to be used in future draw operations.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

tgi_setcolor(TGI_COLOR_BLACK);
tgi_bar(0,0,30,30);
tgi_setcolor(TGI_COLOR_WHITE);
tgi_bar(10,10,20,20);

3.252 tgi_setdrawpage

Function

Set the page for drawing.

Header

tgi.h

Declaration

void __fastcall__ tgi_setdrawpage (unsigned char page);

Description

If the drawpage and the viewpage are the same then all drawing is seen immediately as it is drawn. For double buffered games you can set the drawpage to a different page than the viewpage. This lets you draw the next screen in the background and when the screen is ready you display it.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

tgi_setdrawpage(1);
tgi_outtextxy(10, 10, "Hello World");
tgi_setviewpage(1); // Show page 1
tgi_setdrawpage(0);
tgi_outtextxy(10, 10, "Creating next frame");
...
tgi_setviewpage(0); // Show page 0

3.253 tgi_setpalette

Function

Set the palette (not available with all drivers/hardware). Palette is a pointer to as many entries as there are colors.

Header

tgi.h

Declaration

void __fastcall__ tgi_setpalette (const unsigned char* palette);

Description

Set the palette (not available with all drivers/hardware). Palette is a pointer to as many entries as there are colors.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

3.254 tgi_setpixel

Function

Plot a pixel on the drawpage with the current color.

Header

tgi.h

Declaration

void __fastcall__ tgi_setpixel (int x, int y);

Description

Plot a pixel on the drawpage with the current color.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

3.255 tgi_setviewpage

Function

Set page to be visible on screen.

Header

tgi.h

Declaration

void __fastcall__ tgi_setviewpage (unsigned char page);

Description

If the drawpage and the viewpage are the same then all drawing is seen immediately as it is drawn. For double buffered games you can set the drawpage to a different page than the viewpage. This lets you draw the next screen in the background and when the screen is ready you display it.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

tgi_setdrawpage(1);
tgi_outtextxy(10, 10, "Hello World");
tgi_setviewpage(1); // Show page 1
tgi_setdrawpage(0);
tgi_outtextxy(10, 10, "Creating next frame");
...
tgi_setviewpage(0); // Show page 0

3.256 tgi_gettextheight

Function

Calculate the height of the text in pixels according to the current text style.

Header

tgi.h

Declaration

unsigned __fastcall__ tgi_gettextheight (const char* s);

Description

Calculate the height of the text in pixels according to the current text style.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

3.257 tgi_settextscale

Function

Set the scaling for text output.

Header

tgi.h

Declaration

void __fastcall__ tgi_settextscale (unsigned width, unsigned height);

Description

Set the scaling for text output. The scaling factors for width and height are 8.8 fixed point values. This means that $100 = 1 $200 = 2 etc.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

tgi_settextstyle

Example

None.

3.258 tgi_settextstyle

Function

Set the style for text output.

Header

tgi.h

Declaration

void __fastcall__ tgi_settextstyle (unsigned char magx, unsigned char magy, unsigned char dir, unsigned char font);

Description

Set the style for text output.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

tgi_settextscale

Example

None.

3.259 tgi_gettextwidth

Function

Calculate the width of the text in pixels according to the current text style.

Header

tgi.h

Declaration

unsigned __fastcall__ tgi_gettextwidth (const char* s);

Description

Calculate the width of the text in pixels according to the current text style.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

3.260 tgi_uninstall

Function

Uninstall the currently loaded driver but do not unload it. Will call tgi_done if necessary.

Header

tgi.h

Declaration

void tgi_uninstall (void);

Description

Uninstall the currently loaded driver but do not unload it. Will call tgi_done if necessary.

Availability

cc65

See also

Other tgi functions.

Example

None.

3.261 tgi_unload

Function

Uninstall, then unload the currently loaded driver. Will call tgi_done if necessary.

Header

tgi.h

Declaration

void tgi_unload (void);

Description

Uninstall, then unload the currently loaded driver. Will call tgi_done if necessary.

Availability

cc65

See also

Other tgi functions.

Example

None.

3.262 time

Function

Get the time.

Header

time.h

Declaration

time_t __fastcall__ time (time_t* t);

Description

The function returns the time since the 1970-01-01 00:00:00 measured in seconds. If the pointer t is not NULL, the function result will also be stored there. If no time is available, (time_t)-1 is returned and errno is set to ENOSYS.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • Many platforms supported by cc65 do not have a realtime clock, so the returned value may not be valid.

Availability

ISO 9899

See also

clock

Example

None.

3.263 toggle_videomode

Function

Toggle between 40 and 80 column mode.

Header

c128.h

Declaration

void toggle_videomode (void);

Description

Toggle between 40 and 80 column mode. The settings for the old mode (cursor position, color and so on) are saved and restored together with the mode.

Notes

  • The function is specific to the C128.
  • This function is deprecated. Please use videomode instead!

Availability

C128

See also

fast, slow, videomode

Example

None.

3.264 tolower

Function

Convert a character into its lower case representation.

Header

ctype.h

Declaration

int __fastcall__ tolower (int c);

Description

The function returns the given character converted to lower case. If the given character is not a letter, it is returned unchanged.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

islower, isupper, toupper

Example

None.

3.265 toupper

Function

Convert a character into its upper case representation.

Header

ctype.h

Declaration

int __fastcall__ toupper (int c);

Description

The function returns the given character converted to upper case. If the given character is not a letter, it is returned unchanged.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

ISO 9899

See also

islower, isupper, tolower

Example

None.

3.266 ultoa

Function

Convert an unsigned long integer into a string.

Header

stdlib.h

Declaration

char* __fastcall__ ultoa (unsigned long val, char* buf, int radix);

Description

itoa converts the unsigned long integer val into a string using radix as the base.

Notes

  • There are no provisions to prevent a buffer overflow.
  • The function is non standard, so it is not available in strict ANSI mode. You should probably use sprintf instead.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

atoi, atol, itoa, ltoa, utoa

Example

None.

3.267 unlink

Function

Delete a file.

Header

unistd.h

Declaration

int __fastcall__ unlink (const char* name);

Description

unlink deletes the file with the given name. On success, zero is returned. On error, -1 is returned and errno is set to an error code describing the reason for the failure.

Notes

  • The use of this function is discouraged. Please use remove instead, which is a native ANSI C function and does the same.
  • This function is not available on all cc65 targets (depends on the availability of file I/O).
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • Instead of unlink, remove should be used, which has the same semantics, but is more portable, because it conforms to the ISO C standard.

Availability

POSIX 1003.1

See also

remove

Example

#include <stdio.h>
#include <unistd.h>

#define FILENAME "helloworld"

if (unlink (FILENAME) == 0) {
    printf ("We deleted %s successfully\n", FILENAME);
} else {
    printf ("There was a problem deleting %s\n", FILENAME);
}

3.268 utoa

Function

Convert an unsigned integer into a string.

Header

stdlib.h

Declaration

char* __fastcall__ utoa (unsigned val, char* buf, int radix);

Description

itoa converts the unsigned integer val into a string using radix as the base.

Notes

  • There are no provisions to prevent a buffer overflow.
  • The function is non standard, so it is not available in strict ANSI mode. You should probably use sprintf instead.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

atoi, atol, itoa, ltoa, ultoa

Example

None.

3.269 vcprintf

Function

Formatted output to the console.

Header

conio.h

Declaration

int __fastcall__ vcprintf (const char* format, va_list ap);

Description

The arguments specified as a va_list are converted to text where necessary and formatted according to the format string given. The resulting string is output to the console. vcprintf supports the same format specifiers as vprintf.

Notes

  • Like all other conio output functions, vcprintf distinguishes between \r and \n.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

cprintf, cputc, cputcxy, cputs, cputsxy

Example

None.

3.270 videomode

Function

Switch to either 40 or 80 column mode.

Header

apple2enh.h, c128.h

Declaration

unsigned __fastcall__ videomode (unsigned Mode);

Description

Switch to 40 or 80 column mode depending on the argument. If the requested mode is already active, nothing happens. The old mode is returned from the call.

Notes

  • The function is specific to the C128 and enhanced Apple //e.
  • This function replaces toggle_videomode.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

C128 and enhanced Apple //e

See also

fast, slow, toggle_videomode

Example

None.

3.271 wherex

Function

Return the current X position of the text mode cursor.

Header

conio.h

Declaration

unsigned char wherex (void);

Description

The function returns the current X position of the text mode cursor. Zero is returned for the leftmost screen position.

Availability

cc65

See also

gotox, gotoy, gotoxy, wherey

Example

None.

3.272 wherey

Function

Return the current Y position of the text mode cursor.

Header

conio.h

Declaration

unsigned char wherey (void);

Description

The function returns the current Y position of the text mode cursor. Zero is returned for the uppermost screen position.

Availability

cc65

See also

gotox, gotoy, gotoxy, wherex

Example

None.