cc65 function reference

Ullrich von Bassewitz,
Greg King

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 reference 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. Because those functions behave identically 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 accelerator.h

2.3 apple2.h

2.4 apple2enh.h

2.5 assert.h

2.6 atari.h

(incomplete)

2.7 atmos.h

2.8 c128.h

2.9 c16.h

(incomplete)

2.10 c64.h

2.11 cbm.h

(incomplete)

2.12 cbm510.h

2.13 cbm610.h

2.14 cc65.h

(incomplete)

2.15 conio.h

2.16 creativision.h

2.17 ctype.h

2.18 cx16.h

(incomplete)

2.19 dbg.h

(incomplete)

2.20 device.h

2.21 dio.h

Low-level disk I/O API.

2.22 dirent.h

2.23 em.h

This header file contains definitions for extended memory access, see also testcode/lib/em-test.c and samples/multidemo.c.

2.24 errno.h

(incomplete)

2.25 fcntl.h

2.26 gamate.h

(incomplete)

2.27 geos.h

GEOS API.

2.28 inet.h

2.29 joystick.h

2.30 kim1.h

(incomplete)

2.31 locale.h

2.32 lynx.h

(incomplete)

2.33 lz4.h

2.34 modload.h

2.35 mouse.h

2.36 nes.h

(incomplete)

2.37 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.38 pce.h

(incomplete)

2.39 peekpoke.h

2.40 pen.h

(incomplete)

2.41 pet.h

(incomplete)

2.42 plus4.h

(incomplete)

2.43 serial.h

This header file contains definitions for initializing serial communication, see also testcode/lib/ser-test.c.

2.44 setjmp.h

2.45 signal.h

2.46 stdarg.h

(incomplete)

2.47 stdbool.h

(incomplete)

2.48 stddef.h

2.49 stdio.h

(incomplete)

2.50 stdlib.h

(incomplete)

2.51 string.h

2.52 sym1.h

2.53 telestrat.h

(incomplete)

2.54 tgi.h

Tiny Graphics Interface.

2.55 time.h

(incomplete)

2.56 unistd.h

(incomplete)

2.57 stat.h

2.58 statvfs.h

2.59 vic20.h

(incomplete)

2.60 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 unpredictable 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 _sound

Function

Use the speaker to produce sound in a specified voice. (Atari only)

Header

atari.h

Declaration

void __fastcall__ _sound (unsigned char voice, unsigned char pitch, unsigned char distortion, unsigned char volume);

Description

The function produces a sound with the specified parameters using any of the 4 available oscillators (voices) controlled by the POKEY chip. Sound is non cpu-blocking and it keeps oscillating until program sends 0 in all the other parameters.

Notes

  • The function is available only as a fastcall function; so, it may be used only in the presence of a prototype.
  • The function is specific to the Atari 8 bit.
  • Voice can be any of 0-3 different sound channels.
  • Pitch goes from 0-255 (about 125 Hz to 32 Khz).
  • Distortion (0-14) uses poly dividers to reshape wave in order to create a noise effect. Use 10 for a "pure" square-wave sound.
  • Volume (0-15) is the intensity for the wave.
  • Extra bits in those parameters will be ignored.
  • Parameters are the same as for the AtariBASIC SOUND statement.

Availability

cc65 (atari and atarixl platforms)

Example


#include <stdio.h>
int main(void)
{
    int i=0;
    unsigned char j;
    printf("playing sound \n");
    for (j=0; j<144; j++) {
      _sound(1,144-j,10,8);     //change the pitch for voice 1
      for (i=0; i<50; i++);     //pause for sound duration
    }
    _sound(1,0,0,0);  //use zero in other parameters to stop the sound
    return 0;
}

3.13 _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.14 _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.15 _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.16 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.17 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.18 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.19 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.20 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.21 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.22 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.23 abort

Function

Terminate 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, signal

Example

None.

3.24 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.25 assert

Function

Test a condition, and possibly abort.

Header

assert.h

Declaration

void assert (int cond);

Description

assert() is a macro that expands to an if statement. If the condition evaluates to zero (false), assert() raises SIGABRT, prints a message on stderr, then exits the program with an exit code of 2.

Notes

  • The function is actually a macro.

Availability

ISO 9899

See also

abort, exit, signal

Example

None.

3.26 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.27 atmos_explode

Function

Bomb sound effect.

Header

atmos.h

Declaration

void __fastcall__ atmos_explode(void);

Description

atmos_explode plays the BASIC sound.

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_ping, atmos_shoot, atmos_tick, atmos_tock, atmos_zap

Example

None.

3.28 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.29 atmos_ping

Function

Bell or ricochet sound effect.

Header

atmos.h

Declaration

void __fastcall__ atmos_ping(void);

Description

atmos_ping plays the BASIC sound.

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_explode, atmos_shoot, atmos_tick, atmos_tock, atmos_zap

Example

None.

3.30 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.31 atmos_shoot

Function

Pistol sound effect.

Header

atmos.h

Declaration

void __fastcall__ atmos_shoot(void);

Description

atmos_shoot plays the BASIC sound.

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_explode, atmos_ping, atmos_tick, atmos_tock, atmos_zap

Example

None.

3.32 atmos_tick

Function

High-pitch click.

Header

atmos.h

Declaration

void __fastcall__ atmos_tick(void);

Description

atmos_tick plays the system sound.

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_explode, atmos_ping, atmos_shoot, atmos_tock, atmos_zap

Example

None.

3.33 atmos_tock

Function

Low-pitch click.

Header

atmos.h

Declaration

void __fastcall__ atmos_tock(void);

Description

atmos_tock plays the system sound.

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_explode, atmos_ping, atmos_shoot, atmos_tick, atmos_zap

Example

None.

3.34 atmos_zap

Function

Raygun sound effect.

Header

atmos.h

Declaration

void __fastcall__ atmos_zap(void);

Description

atmos_zap plays the BASIC sound.

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_explode, atmos_ping, atmos_shoot, atmos_tick, atmos_tock

Example

None.

3.35 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.36 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.37 beep

Function

Beep sound.

Header

sym1.h

Header

apple2.h

Declaration

void beep(void);

Description

beep makes a brief tone.

Notes

  • The function is specific to the Sym-1 and Apple2 platforms.

Availability

cc65

See also

fdisp, loadt, dumpt

Example

None.

3.38 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.39 bios_playsound

Function

Play a sequence of musical notes.

Header

creativision.h

Declaration

void __fastcall__ bios_playsound (const void *a, unsigned char b);

Description

The function plays chords based on a BASIC statement. Notes and durations are defined in the BASIC manual, chapter 13 on pages 102 resp. 103.

Notes

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

Availability

cc65

See also

psg_delay, psg_outb

Example

#include <creativision.h>
void main (void)
{
  static const unsigned char notes[] = {
    0x77, 0x4F, 0x37,
    0x4B, 0x05, 0xBB,
    0x4F, 0x27, 0x83,
    0x93, 0x9B, 0x93,
    0x17, 0x4F, 0x96,  // played backwards
    0xAB, 0x17, 0x4F,  // three-note chords
    0x0E               // tempo
  };
  bios_playsound (notes, sizeof notes);
}

3.40 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.41 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.42 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.43 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

cc65

Example

None.

3.44 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.45 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.46 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.47 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.48 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.49 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.50 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.51 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.52 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.53 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.54 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.55 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.56 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.57 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.58 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.59 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.60 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.61 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.62 cmb_k_second

Function

Send secondary address for LISTEN.

Header

cbm.h

Declaration

void __fastcall__ cbm_k_second (unsigned char addr);

Description

This function is used to send a secondary address to an I/O device after a call to LISTEN is made, and the device is commanded to LISTEN.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function can only be called after a call to LISTEN.
  • The function will not work after a TALK.
  • When a secondary address is to be sent to a device on the serial bus, the address must first be ORed with $60.

Availability

cc65

See also

cbm_k_listen

Exampe

None.

3.63 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_load, cbm_k_open, cbm_k_save, cbm_k_setnam

Example

None.

3.64 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_load, cbm_k_open, cbm_k_save, cbm_k_setlfs

Example

None.

3.65 cbm_k_settim

Function

Set the Jiffy clock.

Header

cbm.h

Declaration

void __fastcall__ cbm_k_settim (unsigned long timer);

Description

This function changes the Jiffy clock to a different value. That clock counts sixtieths of a second. It is used by the library's clock() function. The Jiffy clock is updated by the Kernal's Interrupt Service Routine.

Notes

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

Availability

cc65

See also

cbm_k_udtim, clock

Example

None.

3.66 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.67 cbm_k_tksa

Function

Send TALK secondary address to serial bus

Header

cbm.h

Declaration

void __fastcall__ cbm_k_tksa (unsigned char addr);

Description

This function transmits a secondary address on the serial bus for a TALK device.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function can only be called after a call to TALK.
  • The function will not work after a LISTEN.

Availability

cc65

See also

cbm_k_talk

Example

None.

3.68 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, cbm_k_settim, clock

Example

None.

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

Availability

cc65

See also

cbm_k_listen

Example

None.

3.70 cbm_k_untlk

Function

Send an UNTALK command

Header

cbm.h

Declaration

void cbm_k_untlk (void);

Description

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

Availability

cc65

See also

cbm_k_talk

Example

None.

3.71 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.72 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.73 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.74 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.75 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.76 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.77 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_settim, cbm_k_udtim, time

Example

None.

3.78 clock_getres

Function

Determine the realtime clock resolution.

Header

time.h

Declaration

int __fastcall__ clock_getres (clockid_t clock_id, struct timespec *res);

Description

The clock_getres function finds the resolution (precision) of the realtime clock. clock_id has to be CLOCK_REALTIME. If res is not NULL, the resolution of the realtime clock is stored in the location pointed to by res. If res is NULL, the clock resolution is not returned. If the tp argument of clock_settime is not a multiple of res, then the value is truncated to a multiple of res. 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 function is only available as fastcall function, so it may only be used in presence of a prototype.
  • Depending on the target either the tv_sec or the tv_nsec field of the struct timespec returned is zero.

Availability

POSIX 1003.1

See also

clock_gettime, clock_settime

Example

None.

3.79 clock_gettime

Function

Get the time from the realtime clock.

Header

time.h

Declaration

int __fastcall__ clock_gettime (clockid_t clock_id, struct timespec *tp);

Description

The clock_gettime function retrieves the time since the 1970-01-01 00:00:00 measured in nanoseconds. clock_id has to be CLOCK_REALTIME. 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 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 retrieved value may not be valid. See also the platform-specific information.

Availability

POSIX 1003.1

See also

clock_getres, clock_settime, time

Example

None.

3.80 clock_settime

Function

Set the time on the realtime clock.

Header

time.h

Declaration

int __fastcall__ clock_settime (clockid_t clock_id, const struct timespec *tp);

Description

The clock_settime function sets the time since the 1970-01-01 00:00:00 measured in nanoseconds. clock_id has to be CLOCK_REALTIME. 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 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 setting the time may not work. See also the platform-specific information.

Availability

POSIX 1003.1

See also

clock_getres, clock_gettime

Example

None.

3.81 gmtime_dt

Function

Converts a ProDOS date to a struct tm.

Header

apple2.h

Declaration

struct tm* __fastcall__ gmtime_dt (const struct datetime* dt);

Description

The gmtime_dt function converts the given proDOS date/time to a struct tm. On error, NULL is returned and errno is set to an error code describing the reason for the failure.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • This function is only available on Apple II.
  • On Apple II, you can't stat() an opened file. stat() before opening.

Availability

cc65

Example


#include <stdio.h>
#include <time.h>
#include <sys/stat.h>
int main(void)
{
    struct stat st;
    struct tm* tm;
    if (stat ("/disk/file", &st) == 0) {
        tm = gmtime_dt (&st.st_ctime);
        if (tm)
            printf ("File created on %s\n", asctime(tm));
    }
}

3.82 mktime_dt

Function

Converts a ProDOS date to a time_t.

Header

apple2.h

Declaration

time_t __fastcall__ mktime_dt (const struct datetime* dt);

Description

The mktime_dt function parses the given proDOS date/time and returns a time_t timestamp. On error, 0 is returned, and errno is set.

Notes

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

Availability

cc65

Example


#include <stdio.h>
#include <time.h>
#include <sys/stat.h>
int main(void)
{
    struct stat st;
    if (stat ("/disk/file", &st) == 0) {
        printf ("File created on %s\n",
          localtime (mktime_dt (&st.st_ctime)));
    }
}

3.83 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.84 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.85 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.86 cpeekc

Function

Get a character from the display memory.

Header

conio.h

Declaration

char cpeekc (void);

Description

The function gets the character that's at the current location of the cursor in the display screen RAM. That character is converted, if needed, into the encoding that can be passed to cputc().

Notes

  • Conio peek functions don't have cpeek...xy() versions. That was done to make it obvious that peeking doesn't move the cursor in any way. Your program must place the cursor where it wants to peek before it calls any of those functions.

Availability

cc65

See also

cpeekcolor, cpeekrevers, cpeeks, cputc

Example

None.

3.87 cpeekcolor

Function

Get a color from the display memory.

Header

conio.h

Declaration

unsigned char cpeekcolor (void);

Description

The function gets the color number that's at the current location of the cursor in the display screen RAM. That number can be passed to textcolor().

Notes

  • Conio peek functions don't have cpeek...xy() versions. That was done to make it obvious that peeking doesn't move the cursor in any way. Your program must place the cursor where it wants to peek before it calls any of those functions.
  • On the cx16 (Commander X16) target, this function returns two values: the background color, in the high nybble, and the text color, in the low nybble.

Availability

cc65

See also

cpeekc, cpeekrevers, cpeeks, cputc, textcolor

Example

None.

3.88 cpeekrevers

Function

Get a reverse-character attribute from the display memory.

Header

conio.h

Declaration

unsigned char cpeekrevers (void);

Description

The function gets the "reverse-mode" attribute of the character that's at the current location of the cursor in the display screen RAM. It returns a boolean value (0/1) that can be passed to revers().

Notes

  • Conio peek functions don't have cpeek...xy() versions. That was done to make it obvious that peeking doesn't move the cursor in any way. Your program must place the cursor where it wants to peek before it calls any of those functions.

Availability

cc65

See also

cpeekc, cpeekcolor, cpeeks, cputc, revers

Example

None.

3.89 cpeeks

Function

Get a string from the display memory.

Header

conio.h

Declaration

void __fastcall__ cpeeks (char* s, unsigned length);

Description

The function gets a fixed-length string ('\0'-terminated) of characters that start at the current location of the cursor in the display screen RAM. Those characters are converted, if needed, into the encoding that can be passed to cputs(). The first argument must point to a RAM area that's large enough to hold "length + 1" bytes.

Notes

  • Conio peek functions don't have cpeek...xy() versions. That was done to make it obvious that peeking doesn't move the cursor in any way. Your program must place the cursor where it wants to peek before it calls any of those functions.
  • The function is available as only a fastcall function; so, it may be used only in the presence of a prototype.

Availability

cc65

See also

cpeekc, cpeekcolor, cpeekrevers, cputc, cputs

Example

None.

3.90 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.91 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.92 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.93 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.94 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.95 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.96 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.97 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.98 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.99 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.100 detect_c128

Function

Check if a C128 CPU is the current CPU.

Header

accelerator.h

Declaration

unsigned char detect_c128 (void);

Description

The function returns a 1 if a C128 CPU is the current CPU.

Notes

  • The function is specific to the C64 and C128.

Availability

cc65 (not all platforms)

See also

get_c128_speed, set_c128_speed

Example

None.

3.101 detect_c64dtv

Function

Check for the presence of the C64DTV.

Header

accelerator.h

Declaration

unsigned char detect_c64dtv (void);

Description

The function returns a 1 if a C64DTV has been detected.

Notes

  • The function is specific to the C64.

Availability

cc65 (not all platforms)

See also

get_c64dtv_speed, set_c64dtv_speed,

Example

None.

3.102 detect_c65

Function

Check for the presence of a C65/C64DX in C64 mode.

Header

accelerator.h

Declaration

unsigned char detect_c65 (void);

Description

The function returns a 1 if a C65/C64DX in C64 mode has been detected.

Notes

  • The function is specific to the C64.

Availability

cc65 (not all platforms)

See also

get_c65_speed, set_c65_speed

Example

None.

3.103 detect_chameleon

Function

Check for the presence of the C64 Chameleon cartridge.

Header

accelerator.h

Declaration

unsigned char detect_chameleon (void);

Description

The function returns a 1 if a C64 Chameleon cartridge has been detected.

Notes

  • The function is specific to the C64.

Availability

cc65 (not all platforms)

See also

get_chameleon_speed, set_chameleon_speed,

Example

None.

3.104 detect_iigs

Function

Check whether we are running on an Apple IIgs..

Header

accelerator.h

Declaration

unsigned char detect_iigs (void);

Description

The function returns a 1 if running on an Apple IIgs.

Notes

  • The function is specific to the Apple2 and Apple2enh platforms.

Availability

cc65 (not all platforms)

See also

get_iigs_speed, set_iigs_speed,

Example

None.

3.105 detect_scpu

Function

Check for the presence of the C64/C128 SuperCPU cartridge.

Header

accelerator.h

Declaration

unsigned char detect_scpu (void);

Description

The function returns a 1 if a SuperCPU cartridge has been detected.

Notes

  • The function is specific to the C128 and C64.

Availability

cc65 (not all platforms)

See also

get_scpu_speed, set_scpu_speed,

Example

None.

3.106 detect_turbomaster

Function

Check for the presence of the C64 Turbo Master cartridge.

Header

accelerator.h

Declaration

unsigned char detect_turbomaster (void);

Description

The function returns a 1 if a C64 Turbo Master cartridge has been detected.

Notes

  • The function is specific to the C64.

Availability

cc65 (not all platforms)

See also

get_turbomaster_speed, set_turbomaster_speed,

Example

None.

3.107 dir_entry_count

Function

Returns the number of entries in the directory.

Header

apple2.h

Declaration

unsigned int __fastcall__ dir_entry_count(DIR *dir);

Description

dir_entry_count is machine dependent and does not exist for all supported targets. If it exists, it returns the number of active (non-deleted) files and directories in the directory.

Notes

  • The function does not exist on all platforms.

Availability

cc65 (not all platforms)

Example

None.

3.108 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.109 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.110 dumpt

Function

Dump memory to tape.

Header

sym1.h, kim1.h

Declaration

int __fastcall__ dumpt (unsigned char id, const void* start, const void* end);

Description

dumpt saves memory onto data tape.

Notes

  • The function is specific to the Sym-1 and KIM-1.
  • The return value is status. Non-zero status indicates an error.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

beep, fdisp, loadt

Example

None.

3.111 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.112 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.113 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.114 em_install

Function

Install an already loaded extended memory driver.

Header

em.h

Declaration

unsigned char _fastcall__ em_install (const 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.115 em_load_driver

Function

Load and initialize an extended memory driver.

Header

em.h

Declaration

unsigned char __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.116 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 transferred 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.117 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.118 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.119 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.120 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.121 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.122 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.123 fast

Function

Switch the CPU into fast mode (C128: 2MHz mode, C16/Plus4: double clock mode).

Header

c128.h, c16.h, plus4.h

Declaration

void fast (void);

Description

The function will switch the clock of the CPU to fast mode. For the C128 target it means switching the CPU into 2MHz mode. For the C16/Plus4 target it means switching the CPU into double clock mode.

Notes

  • The function is specific to the C128, C16 and Plus4.
  • On the C128 the 2MHz clock will not work in 40 column mode.

Availability

cc65 (not all platforms)

See also

isfast, slow,

Example

None.

3.124 fdisp

Function

Flash front-panel display.

Header

sym1.h

Declaration

void fdisp(void);

Description

fdisp flashes front-panel display.

Notes

  • The function is specific to the Sym-1.
  • The front-panel display buffer must be loaded prior to calling fdisp. See the DISPLAY struct definition in sym1.h.

Availability

cc65

See also

beep, loadt, dumpt

Example

None.

3.125 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 of the 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.126 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.127 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.128 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.129 get_ostype

Function

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

Header

apple2.h, atari.h, c64.h, cx16.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.130 get_c128_speed

Function

Get the current speed of the C128 CPU.

Header

accelerator.h

Declaration

unsigned char get_c128_speed (void);

Description

The function returns the current speed of the C128 CPU.

Notes

  • The function is specific to the C64 and C128.
  • The function does not check if the C128 CPU is the current CPU.
  • See the accelerator.h header for the speed definitions.

Availability

cc65 (not all platforms)

See also

detect_c128, set_c128_speed,

Example

None.

3.131 get_c64dtv_speed

Function

Get the current speed of the C64DTV.

Header

accelerator.h

Declaration

unsigned char get_c64dtv_speed (void);

Description

The function returns the current speed of the C64DTV.

Notes

  • The function is specific to the C64.
  • The function does not check for the presence of the C64DTV.
  • See the accelerator.h header for the speed definitions.

Availability

cc65 (not all platforms)

See also

detect_c64dtv, set_c64dtv_speed,

Example

None.

3.132 get_c65_speed

Function

Get the current speed of the C65/C64DX in C64 mode.

Header

accelerator.h

Declaration

unsigned char get_c65_speed (void);

Description

The function returns the current speed of the C65/C64DX in C64 mode.

Notes

  • The function is specific to the C64.
  • The function does not check for the presence of a C65/C64DX in C64 mode.
  • See the accelerator.h header for the speed definitions.

Availability

cc65 (not all platforms)

See also

detect_c65, set_c65_speed,

Example

None.

3.133 get_chameleon_speed

Function

Get the current speed of the C64 Chameleon cartridge.

Header

accelerator.h

Declaration

unsigned char get_chameleon_speed (void);

Description

The function returns the current speed of the C64 Chameleon cartridge.

Notes

  • The function is specific to the C64.
  • The function does not check for the presence of the C64 Chameleon cartridge.
  • See the accelerator.h header for the speed definitions.

Availability

cc65 (not all platforms)

See also

detect_chameleon, set_chameleon_speed,

Example

None.

3.134 get_iigs_speed

Function

Get the current speed of the Apple IIgs.

Header

accelerator.h

Declaration

unsigned char get_iigs_speed (void);

Description

The function returns the current speed of the Apple IIgs.

Notes

  • The function is specific to the Apple2 and Apple2enh platforms.
  • See the accelerator.h header for the speed definitions.

Availability

cc65 (not all platforms)

See also

detect_iigs, set_iigs_speed,

Example

None.

3.135 get_scpu_speed

Function

Get the current speed of the C64/C128 SuperCPU cartridge.

Header

accelerator.h

Declaration

unsigned char get_scpu_speed (void);

Description

The function returns the current speed of the SuperCPU cartridge.

Notes

  • The function is specific to the C128 and C64.
  • The function does not check for the presence of the cartridge.
  • See the accelerator.h header for the speed definitions.

Availability

cc65 (not all platforms)

See also

detect_scpu, set_scpu_speed,

Example

None.

3.136 get_turbomaster_speed

Function

Get the current speed of the C64 Turbo Master cartridge.

Header

accelerator.h

Declaration

unsigned char get_turbomaster_speed (void);

Description

The function returns the current speed of the C64 Turbo Master cartridge.

Notes

  • The function is specific to the C64.
  • The function does not check for the presence of the C64 Turbo Master cartridge.
  • See the accelerator.h header for the speed definitions.

Availability

cc65 (not all platforms)

See also

detect_turbomaster, set_turbomaster_speed,

Example

None.

3.137 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
  • CPU_4510
  • CPU_65SC02
  • CPU_65CE02
  • CPU_HUC6280
  • CPU_2A0x

Notes

  • Other, more exotic CPU types are not disinguished.

Availability

cc65

Example

None.

3.138 getcurrentdevice

Function

Get current device.

Header

device.h

Declaration

unsigned char getcurrentdevice (void);

Description

The function returns the current device. It allows to access the current device with the Low-level disk I/O API or cbm_* I/O functions requiring a 'device' parameter.

Availability

cc65

See also

getdevicedir, getfirstdevice, getnextdevice

Example

dio_open (getcurrentdevice ());

3.139 getcwd

Function

Get current working directory.

Header

unistd.h

Declaration

char* __fastcall__ getcwd (char* buf, size_t size);

Description

The function will return the current working 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

Example

None.

3.140 getdevicedir

Function

Get device directory.

Header

device.h

Declaration

char* __fastcall__ getdevicedir (unsigned char device, char* buf, size_t size);

Description

The function returns the directory representing device. It allows to access the device on filesystem level by calling chdir() with the directory returned.

Notes

  • Calling getdevicedir() does check for a (formatted) disk in a floppy-disk-type device and returns NULL if that check fails.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

getcwd, getcurrentdevice, getfirstdevice, getnextdevice

Example

chdir (getdevicedir (device, buf, sizeof buf));
cf. samples/enumdevdir.c

3.141 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.142 getfirstdevice

Function

Get first device.

Header

device.h

Declaration

unsigned char getfirstdevice (void);

Description

The function returns the first device. The constant INVALID_DEVICE indicates no device.

Notes

  • Calling getfirstdevice() does not turn on the motor of a drive-type device and does not check for a disk in the drive.

Availability

cc65

See also

getcurrentdevice, getdevicedir, getnextdevice

Example

unsigned char dev = getfirstdevice ();
while (dev != INVALID_DEVICE) {
        printf ("%d\n", dev);
        dev = getnextdevice (dev);
        }

3.143 getnextdevice

Function

Get next device.

Header

device.h

Declaration

unsigned char __fastcall__ getnextdevice (unsigned char device);

Description

The function returns the next device after device. The constant INVALID_DEVICE indicates no further device.

Notes

  • Calling getnextdevice() does not turn on the motor of a drive-type device and does not check for a disk in the drive.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

getcurrentdevice, getdevicedir, getfirstdevice

Example

unsigned char dev = getfirstdevice ();
while (dev != INVALID_DEVICE) {
        printf ("%d\n", dev);
        dev = getnextdevice (dev);
        }

3.144 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 preceded 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.145 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.146 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.147 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.148 htonl

Function

Swaps byte order in a 32 bit word.

Header

arpa/inet.h

Declaration

int htonl(val)

Description

Converts a 32 bit word from from network byte order (big endian) to little endian (or vice-versa).

Notes

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

See also

ntohl

Availability

cc65

3.149 htons

Function

Swaps byte order in a 16 bit word.

Header

arpa/inet.h

Declaration

int htons(val)

Description

Converts a 16 bit word from from network byte order (big endian) to little endian (or vice-versa) by swapping both its bytes.

Notes

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

See also

ntohs

Availability

cc65

3.150 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 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.151 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 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.152 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 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.153 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 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.154 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 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.155 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 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.156 isfast

Function

Check if the CPU is in fast mode (C128: 2MHz mode, C16/Plus4: double clock mode).

Header

c128.h, c16.h, plus4.h

Declaration

unsigned char isfast (void);

Description

The function returns a 1 if the CPU is in fast mode (C128: 2MHz mode, C16/Plus4: double clock mode).

Notes

  • The function is specific to the C128, C16 and Plus4.

Availability

cc65 (not all platforms)

See also

fast, slow,

Example

None.

3.157 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 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.158 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 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.159 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 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.160 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 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.161 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 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.162 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 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.163 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 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.164 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.165 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.166 joy_install

Function

Install an already loaded driver and return an error code.

Header

joystick.h

Declaration

unsigned char __fastcall__ joy_install (const 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.167 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.168 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.169 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.170 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.171 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.172 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.173 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.174 loadt

Function

Load memory from tape.

Header

sym1.h, kim1.h

Declaration

int __fastcall__ loadt (unsigned char id);

Description

loadt loads memory from data tape.

Notes

  • The function is specific to the Sym-1 and KIM-1.
  • The return value is status. Non-zero status indicates an error.
  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

beep, fdisp, dumpt

Example

None.

3.175 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.176 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.177 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 preceding 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.178 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.179 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.180 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.181 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.182 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.183 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.184 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.185 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.186 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.187 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.188 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.189 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.190 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.191 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.192 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.193 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.194 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.195 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.196 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.197 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.198 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.199 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.200 mul20

Function

Multiplies argument by 20.

Header

cc65.h

Declaration

unsigned int __fastcall__ mul20 (unsigned char value);

Description

Speed optimized function to multiply an 8 bit unsigned value by 20 to get a 16 bit result.

Availability

cc65

3.201 mul40

Function

Multiplies argument by 40.

Header

cc65.h

Declaration

unsigned int __fastcall__ mul40 (unsigned char value);

Description

Speed optimized function to multiply an 8 bit unsigned value by 40 to get a 16 bit result.

Availability

cc65

3.202 ntohl

Function

Swaps byte order in a 32 bit word.

Header

arpa/inet.h

Declaration

int __fastcall__ ntohl (int val);

Description

Converts a 32 bit word from from host byte order (little endian) to big endian (or vice-versa).

Notes

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

See also

htonl

Availability

cc65

3.203 ntohs

Function

Swaps byte order in a 16 bit word.

Header

arpa/inet.h

Declaration

int __fastcall__ ntohs (int val);

Description

Converts a 16 bit word from from host byte order (little endian) to big endian (or vice-versa) by swapping both its bytes.

Notes

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

See also

htons

Availability

cc65

3.204 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.205 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.206 opendir

Function

Open a directory.

Header

dirent.h

Declaration

DIR* __fastcall__ opendir (const char* name);

Description

opendir opens a directory and returns the directory 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.207 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.208 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.209 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.210 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.211 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.212 psg_delay

Function

Delay for a short period of time.

Header

creativision.h

Declaration

void __fastcall__ psg_delay (unsigned char b);

Description

The function specifies how long each note or pause between notes should last.

Notes

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

Availability

cc65

See also

psg_outb, psg_silence

Example

None.

3.213 psg_outb

Function

Output a byte to the PSG.

Header

creativision.h

Declaration

void __fastcall__ psg_outb (unsigned char b);

Description

The function sends a byte to the Programmable Sound Generator, then waits for the PSG to acknowledge.

Notes

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

Availability

cc65

See also

psg_delay, psg_silence

Example

#include <creativision.h>
void main (void)
{
  psg_outb (0x80); // Latch frequency
  psg_outb (0x07); // Frequency byte 2
  psg_outb (0x90); // Channel 0 full volume
  psg_delay (100);
  psg_silence ();
}

3.214 psg_silence

Function

Set volume off on each PSG channel.

Header

creativision.h

Declaration

void psg_silence (void);

Description

The function resets the Programmable Sound Generator, then sends $9F, $BF, $DF, $FF to the PSG.

Availability

cc65

See also

psg_delay, psg_outb

Example

None.

3.215 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.216 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, non-zero otherwise.

Notes

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

Availability

ISO 9899

See also

abort, assert, signal

Example

None.

3.217 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.218 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 the Apple II platform, the d_ctime and d_mtime returned are in the ProDOS format. You can convert them to more portable time representations using the ProDOS datetime conversion functions.
  • 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.219 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 lose 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.220 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.221 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.222 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 exiting the program.

Availability

cc65

See also

reset_irq, set_brk, set_irq

Example

None.

3.223 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 exiting the program.

Availability

cc65

See also

reset_brk, set_brk, set_irq

Example

None.

3.224 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.225 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.226 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.227 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.228 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.229 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.230 ser_install

Function

Install an already loaded driver and return an error code.

Header

serial.h

Declaration

unsigned char __fastcall__ ser_install (const 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.231 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.232 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.233 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.234 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.235 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.236 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. This function returns SER_ERR_NO_DRIVER if no driver was installed, 0 otherwise.

Availability

cc65

See also

Other serial functions.

Example

None.

3.237 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.238 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 exiting the program.

Availability

cc65

See also

reset_brk

Example

None.

3.239 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 exiting the program.

Availability

cc65

See also

reset_brk, reset_irq, set_brk

Example

None.

3.240 set_c128_speed

Function

Set the current speed of a C128 CPU.

Header

accelerator.h

Declaration

unsigned char __fastcall__ set_c128_speed (unsigned char speed);

Description

The function returns the speed after trying to set the speed of the C128 CPU.

Notes

  • The function is specific to the C64 and C128.
  • The function does not check if the C128 CPU is the current CPU.
  • See the accelerator.h header for the speed definitions.

Availability

cc65 (not all platforms)

See also

detect_c128, get_c128_speed,

Example

None.

3.241 set_c64dtv_speed

Function

Set the current speed of the C64DTV.

Header

accelerator.h

Declaration

unsigned char __fastcall__ set_c64dtv_speed (unsigned char speed);

Description

The function returns the speed after trying to set the speed of the C64DTV.

Notes

  • The function is specific to the C64.
  • The function does not check for the presence of the C64DTV.
  • See the accelerator.h header for the speed definitions.

Availability

cc65 (not all platforms)

See also

detect_c64dtv, get_c64dtv_speed,

Example

None.

3.242 set_c65_speed

Function

Set the current speed of the C65/C64DX in C64 mode.

Header

accelerator.h

Declaration

unsigned char __fastcall__ set_c65_speed (unsigned char speed);

Description

The function returns the speed after trying to set the speed of the C65/C64DX in C64 mode.

Notes

  • The function is specific to the C64.
  • The function does not check for the presence of a C65/C64DX in C64 mode.
  • See the accelerator.h header for the speed definitions.

Availability

cc65 (not all platforms)

See also

detect_c65, get_c65_speed,

Example

None.

3.243 set_chameleon_speed

Function

Set the current speed of the C64 Chameleon cartridge.

Header

accelerator.h

Declaration

unsigned char __fastcall__ set_chameleon_speed (unsigned char speed);

Description

The function returns the speed after trying to set the speed of the C64 Chameleon cartridge.

Notes

  • The function is specific to the C64.
  • The function does not check for the presence of the C64 Chameleon cartridge.
  • See the accelerator.h header for the speed definitions.

Availability

cc65 (not all platforms)

See also

detect_chameleon, get_chameleon_speed,

Example

None.

3.244 set_iigs_speed

Function

Set the current speed of the Apple IIgs.

Header

accelerator.h

Declaration

unsigned char __fastcall__ set_iigs_speed (unsigned char speed);

Description

The function sets the speed of the Apple IIgs CPU (and returns the new speed).

Notes

  • The function is specific to the Apple2 and Apple2enh platforms.
  • See the accelerator.h header for the speed definitions.
  • Accepted parameters are SPEED_SLOW and SPEED_FAST (all other values are considered SPEED_FAST).

Availability

cc65 (not all platforms)

See also

detect_iigs, get_iigs_speed,

Example

None.

3.245 set_scpu_speed

Function

Set the current speed of the C64/C128 SuperCPU cartridge.

Header

accelerator.h

Declaration

unsigned char __fastcall__ set_scpu_speed (unsigned char speed);

Description

The function returns the speed after trying to set the speed of the SuperCPU cartridge.

Notes

  • The function is specific to the C128 and C64.
  • The function does not check for the presence of the cartridge.
  • See the accelerator.h header for the speed definitions.

Availability

cc65 (not all platforms)

See also

detect_scpu, get_scpu_speed,

Example

None.

3.246 set_turbomaster_speed

Function

Set the current speed of the C64 Turbo Master cartridge.

Header

accelerator.h

Declaration

unsigned char __fastcall__ set_turbomaster_speed (unsigned char speed);

Description

The function returns the speed after trying to set the speed of the C64 Turbo Master cartridge.

Notes

  • The function is specific to the C64.
  • The function does not check for the presence of the C64 Turbo Master cartridge.
  • See the accelerator.h header for the speed definitions.

Availability

cc65 (not all platforms)

See also

detect_turbomaster, get_turbomaster_speed,

Example

None.

3.247 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.248 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.249 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, assert, raise

Example

None.

3.250 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.251 slow

Function

Switch the CPU into slow mode (C128: 1MHz mode, C16/Plus4: single clock mode).

Header

c128.h, c16.h, plus4.h

Declaration

void slow (void);

Description

The function will switch the clock of the CPU to slow mode. for the C128 target it means switching the CPU into 1MHz mode. for the C16/Plus4 target it means switching the CPU into single clock mode.

Notes

  • The function is specific to the C128, C16 and Plus4.

Availability

cc65 (not all platforms)

See also

fast, isfast,

Example

None.

3.252 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.253 stat

Function

Get file status.

Header

sys/stat.h

Declaration

int __fastcall__ stat (const char* pathname, struct stat* statbuf);

Description

stat gets information for 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 function is only available as fastcall function, so it may only be used in presence of a prototype.
  • On the Apple II platform, the st_ctim, st_mtim and st_atim members are left to zero, for size and performance reasons. The ProDOS creation and modification dates are returned in the ProDOS format in st_ctime and st_mtime. The access date does not exist. You can convert them to POSIX-style time representations using the ProDOS datetime conversion functions.

Availability

POSIX 1003.1

See also

statvfs

Example

#include <sys/stat.h>

#define FILENAME "helloworld"
struct stat stbuf;
if (stat (FILENAME, &stbuf) == 0) {
    printf ("%s size is %lu bytes (created on %s)\n", FILENAME, stbuf.st_size,
#ifndef __APPLE2__
    localtime (&stbuf.st_ctim.tv_sec)
#else
    localtime (mktime_dt (&stbuf.st_ctime))
#endif
    );
} else {
    printf ("There was a problem stat'ing %s: %d\n", FILENAME, errno);
}

3.254 statvfs

Function

Get filesystem statistics.

Header

sys/statvfs.h

Declaration

int __fastcall__ statvfs (const char* pathname, struct statvfs* buf);

Description

statvfs gets information for the filesytem on which the given file resides. 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 function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function requires an absolute pathname.

Availability

POSIX 1003.1

See also

stat

Example

#include <sys/statvfs.h>

#define FILENAME "/disk/helloworld"
struct statvfs stvbuf;
if (statvfs (FILENAME, &stvbuf) == 0) {
    printf ("%s filesystem has %u blocks of %u size, %u of them free.\n", FILENAME, stvbuf.f_blocks, stvbuf.f_bsize, stvbuf.f_bfree);
} else {
    printf ("There was a problem statvfs'ing %s: %d\n", FILENAME, errno);
}

3.255 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.256 strcat

Function

Concatenate 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.257 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.258 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.259 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.260 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.261 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

strpbrk, strqtok, strspn, strstr, strtok

Example

None.

3.262 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.263 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.264 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.265 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.266 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.267 strlwr

See strlower.

3.268 strncasecmp

Function

Compare two strings case insensitive.

Header

string.h

Declaration

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

Description

The strncasecmp 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.269 strncat

Function

Concatenate 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.270 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.271 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.272 strnicmp

Function

Compare two strings case insensitive.

Header

string.h

Declaration

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

Description

The strnicmp 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.273 strpbrk

Function

Find a character in a string, from a set of characters.

Header

string.h

Declaration

char* __fastcall__ strpbrk (const char* str, const char* set);

Description

strpbrk() searches within str for the first occurrence of any character from set. It returns a pointer to that character if found; otherwise, it returns NULL.

Notes

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

Availability

ISO 9899

See also

strchr, strcspn, strqtok, strspn, strtok

Example

None.

3.274 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, strpbrk, strspn, strtok

Example

None.

3.275 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.276 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, strpbrk, strstr

Example

None.

3.277 strcasestr

Function

Find a substring, case-insensitive.

Header

string.h

Declaration

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

Description

strcasestr searches for the first occurrence of the string substr within str. If found, it returns a pointer to the start of the match in str, 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

strstr, strcspn, strspn

Example

None.

3.278 strstr

Function

Find a substring, case-sensitive.

Header

string.h

Declaration

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

Description

strstr searches for the first occurrence of the string substr within str. If found, it returns a pointer to the start of the match in str, 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

strcasestr, strcspn, strspn

Example

None.

3.279 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, strpbrk, strqtok, strspn

Example

None.

3.280 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 character sets, strxfrm will just copy s2 to s1 using strncpy.

Availability

ISO 9899

See also

strcmp, strcoll, strncpy

Example

None.

3.281 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.282 strupr

See strupper.

3.283 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.284 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.285 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 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.
  • 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, clock_gettime

Example

None.

3.286 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, isfast, slow, videomode

Example

None.

3.287 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.288 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.289 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.290 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.291 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.292 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.293 videomode

Function

Switch to either 40- or 80-column text mode, or a standard graphics mode.

Header

apple2enh.h, c128.h, cx16.h

Declaration

unsigned __fastcall__ videomode (unsigned Mode); /* for apple2enh and c128 */
signed char __fastcall__ videomode (signed char Mode); /* for cx16 */

Description

Switch to a 40- or 80-column text or graphics 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 Commodore 128, the enhanced Apple //e, and the Commander X16.
  • This function replaces toggle_videomode.
  • The function is available as only a fastcall function, so it may be used only in the presence of a prototype.

Availability

C128, enhanced Apple //e, and CX16

See also

fast, isfast, slow, toggle_videomode

Example

None.

3.294 waitvsync

Function

Wait until the start of the next video frame.

Header

atmos.h, cbm.h, gamate.h, nes.h, pce.h

Declaration

void waitvsync (void);

Description

Wait for vertical sync, to reduce flickering.

Availability

Platforms served by the headers above (Atmos requires the VSync hack)

Example

None.

3.295 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.296 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.