Skip to main content

libspectranet API Reference

The libspectranet (spectranet.h) library provides the classic miscellaneous Spectranet helpers that are not part of the socket API or the SPDOS VFS layer. This includes hardware detection, MAC/IP configuration helpers, page control, simple text utilities, address conversion, and BASIC extension registration.

Paging and Non-Paging versions

SDK includes two versions of libspectranet prebuilt: libspectranet.lib and libspectranet_np.lib

Use the same rule as elsewhere in Spectranext:

  • libspectranet.lib — Paged build: use when your program already follows the usual Spectranet paging model (see memory).
  • libspectranet_np.lib — No-page stubs: often paired with an explicit pagein() at startup when your code expects Spectranet ROM to be mapped before calling these helpers.

Overview​

All functions on this page are declared in spectranet.h. They are thin wrappers around Spectranet ROM routines and utility code.

Use this library for:

  • Detecting compatible hardware
  • Reading or changing MAC/IP configuration
  • Controlling Spectranet paging
  • Formatting or parsing MAC and IPv4 addresses
  • Registering custom BASIC extensions

Use other references for other areas:

  • Detection — detailed behaviour of spectranet_detect
  • libspdos — VFS and filesystem calls
  • spectranext.h — Spectranext-specific syscalls and higher-level helpers

Types and Constants​

in_addr_t​

spectranet.h defines:

#define in_addr_t unsigned long

This is the IPv4 address type used by the configuration and conversion helpers on this page.

struct basic_cmd​

Describe a BASIC extension command to be registered with addbasicext().

struct basic_cmd
{
    unsigned char errorcode;
    char *command;
    unsigned char rompage;
    void *function;
};

Fields:

  • errorcode (unsigned char): BASIC error code to raise when parsing fails
  • command (char*): Token or command name to register
  • rompage (unsigned char): ROM page to map before calling the handler, or 0 for no extra paging
  • function (void*): Handler entry point for the new BASIC command

Example:

struct basic_cmd bc;
bc.errorcode = TRAP_NONSENSE;
bc.command = "*poke";
bc.rompage = 0;
bc.function = doublepoke;

TRAP_NONSENSE​

#define TRAP_NONSENSE 0x0b

Convenience constant for the classic BASIC "Nonsense in BASIC" trap code. Commonly used in basic_cmd.errorcode.

Hardware Detection​

spectranet_detect​

Detect whether Spectranext, classic Spectranet, or no compatible hardware is present.

int spectranet_detect(void);

Returns:

  • 1 — Spectranext detected
  • 0 — Classic Spectranet detected
  • -1 — No compatible hardware detected

Example:

#include <spectranet.h>

int kind = spectranet_detect();
if (kind == 1) {
    /* Spectranext */
} else if (kind == 0) {
    /* Classic Spectranet */
} else {
    /* No hardware */
}

See Detection for a deeper explanation of how this probe works.

Hardware Address Helpers​

sethwaddr​

Set the hardware MAC address.

int sethwaddr(char *hwaddr);

Parameters:

  • hwaddr (char*): Pointer to a 6-byte MAC address buffer

Returns:

  • On success: 0
  • On error: negative value

Example:

char mac[6] = { 0x02, 0x12, 0x34, 0x56, 0x78, 0x9a };
if (sethwaddr(mac) < 0) {
    /* handle error */
}

gethwaddr​

Read the current hardware MAC address.

void gethwaddr(char *hwaddr);

Parameters:

  • hwaddr (char*): Destination buffer, at least 6 bytes

Example:

char mac[6];
gethwaddr(mac);

mac2string​

Convert a 6-byte MAC address to printable text.

void mac2string(char *mac, char *str);

Parameters:

  • mac (char*): Pointer to a 6-byte MAC address
  • str (char*): Output buffer for the textual representation

Example:

char mac[6];
char text[19];

gethwaddr(mac);
mac2string(mac, text);

Note: In spectranet.h, mac2string() is macro-mapped to the callee-linkage form by default.

string2mac​

Parse a textual MAC address into 6 raw bytes.

void string2mac(char *str, char *mac);

Parameters:

  • str (char*): Input MAC string
  • mac (char*): Output buffer, at least 6 bytes

Example:

char mac[6];
string2mac("02:12:34:56:78:9A", mac);

Note: In spectranet.h, string2mac() is macro-mapped to the callee-linkage form by default.

mac2string_callee​

Callee-linkage version of mac2string.

void mac2string_callee(char *mac, char *str);

Most C code should use mac2string(). This symbol matters when you need the explicit z88dk callee calling convention.

string2mac_callee​

Callee-linkage version of string2mac.

void string2mac_callee(char *str, char *mac);

Most C code should use string2mac().

IP Configuration Helpers​

ifconfig_inet​

Set the interface IPv4 address.

void ifconfig_inet(in_addr_t *addr);

Parameters:

  • addr (in_addr_t*): Pointer to the IPv4 address value to apply

get_ifconfig_inet​

Read the current interface IPv4 address.

void get_ifconfig_inet(in_addr_t *addr);

Parameters:

  • addr (in_addr_t*): Destination for the IPv4 address

ifconfig_netmask​

Set the IPv4 netmask.

void ifconfig_netmask(in_addr_t *addr);

Parameters:

  • addr (in_addr_t*): Pointer to the netmask value

get_ifconfig_netmask​

Read the current IPv4 netmask.

void get_ifconfig_netmask(in_addr_t *addr);

Parameters:

  • addr (in_addr_t*): Destination for the netmask value

ifconfig_gw​

Set the IPv4 gateway.

void ifconfig_gw(in_addr_t *addr);

Parameters:

  • addr (in_addr_t*): Pointer to the gateway value

get_ifconfig_gw​

Read the current IPv4 gateway.

void get_ifconfig_gw(in_addr_t *addr);

Parameters:

  • addr (in_addr_t*): Destination for the gateway value

deconfig​

Reset IPv4 address, gateway, and netmask to 0.0.0.0.

void deconfig(void);

Example:

deconfig();

Example: Read and Print Current Network Settings​

#include <stdio.h>
#include <spectranet.h>

in_addr_t ip, netmask, gw;
char ipbuf[19];

get_ifconfig_inet(&ip);
get_ifconfig_netmask(&netmask);
get_ifconfig_gw(&gw);

long2ipstring(&ip, ipbuf);
printf("IP: %s\n", ipbuf);

long2ipstring(&netmask, ipbuf);
printf("Netmask: %s\n", ipbuf);

long2ipstring(&gw, ipbuf);
printf("Gateway: %s\n", ipbuf);

Paging Helpers​

setpagea​

Select the Spectranet RAM page visible in page window A.

void setpagea(unsigned char page);

Parameters:

  • page (unsigned char): Page number to map

setpageb​

Select the Spectranet RAM page visible in page window B.

void setpageb(unsigned char page);

Parameters:

  • page (unsigned char): Page number to map

pagein​

Page Spectranet ROM/RAM into the Spectrum address space.

void pagein(void);

Use this when you are explicitly managing Spectranet paging yourself.

pageout​

Page Spectranet ROM/RAM back out.

void pageout(void);

Example:

pagein();
setpageb(0xC0);
setpagea(0xC0);
pageout();

Console and Utility Helpers​

clear42​

Clear channel 42 output.

void clear42(void);

This belongs to the classic Spectranet text UI helper set.

putchar42​

Write a character to channel 42.

void putchar42(char ch);

Parameters:

  • ch (char): Character to output

inputstring​

Read a string from input into a caller-provided buffer.

void inputstring(char *str, int len);

Parameters:

  • str (char*): Destination buffer
  • len (int): Maximum input length

Example:

char name[32];
inputstring(name, sizeof(name) - 1);

Note: In spectranet.h, inputstring() is macro-mapped to inputstring_callee().

inputstring_callee​

Callee-linkage version of inputstring.

void inputstring_callee(char *str, int len);

rand16​

Return a 16-bit pseudo-random value.

unsigned int rand16(void);

Returns:

  • A pseudo-random 16-bit value

Example:

unsigned int r = rand16();

Address Conversion Helpers​

long2ipstring​

Convert an IPv4 address value into dotted-decimal text.

void long2ipstring(in_addr_t *addr, char *str);

Parameters:

  • addr (in_addr_t*): Pointer to the IPv4 address
  • str (char*): Output buffer for the textual representation

Example:

in_addr_t ip;
char text[16];

get_ifconfig_inet(&ip);
long2ipstring(&ip, text);

Note: In spectranet.h, long2ipstring() is macro-mapped to long2ipstring_callee().

ipstring2long​

Parse dotted-decimal IPv4 text into an in_addr_t.

int ipstring2long(char *str, in_addr_t *addr);

Parameters:

  • str (char*): Input IPv4 text such as "192.168.1.10"
  • addr (in_addr_t*): Output address value

Returns:

  • On success: 0
  • On parse error: non-zero value

Example:

in_addr_t ip;
if (ipstring2long("1.2.3.4", &ip) == 0) {
    ifconfig_inet(&ip);
}

Note: In spectranet.h, ipstring2long() is macro-mapped to ipstring2long_callee().

long2ipstring_callee​

Callee-linkage version of long2ipstring.

void long2ipstring_callee(in_addr_t *addr, char *str);

ipstring2long_callee​

Callee-linkage version of ipstring2long.

int ipstring2long_callee(char *str, in_addr_t *addr);

BASIC Extension Helpers​

addbasicext​

Register a new BASIC extension command.

int addbasicext(struct basic_cmd *cmd);

Parameters:

  • cmd (struct basic_cmd*): Description of the BASIC command to add

Returns:

  • On success: 0
  • On error: negative value

Example:

#include <spectranet.h>

void my_handler(void);

struct basic_cmd bc = {
    .errorcode = TRAP_NONSENSE,
    .command = "*poke",
    .rompage = 0,
    .function = my_handler,
};

if (addbasicext(&bc) < 0) {
    /* handle failure */
}

statement_end​

Validate that the BASIC statement parser is at the end of the current statement.

void statement_end(void);

This is typically used inside a BASIC extension handler after argument parsing.

Example:

void my_handler(void)
{
    /* parse arguments first */
    statement_end();
}

exit_success​

Exit a BASIC extension successfully through the standard Spectranet return path.

void exit_success(void);

Use this when your BASIC extension has finished its work and should return cleanly to BASIC.

Example:

void my_handler(void)
{
    /* do work */
    exit_success();
}

Calling Convention Notes​

Several conversion/input helpers expose both caller-linkage and callee-linkage forms:

  • mac2string / mac2string_callee
  • string2mac / string2mac_callee
  • inputstring / inputstring_callee
  • long2ipstring / long2ipstring_callee
  • ipstring2long / ipstring2long_callee

At the end of spectranet.h, the plain names are macro-mapped to the callee versions by default:

#define mac2string(a,b)      mac2string_callee(a,b)
#define string2mac(a,b)      string2mac_callee(a,b)
#define inputstring(a,b)     inputstring_callee(a,b)
#define long2ipstring(a,b)   long2ipstring_callee(a,b)
#define ipstring2long(a,b)   ipstring2long_callee(a,b)

So in normal C code, just call the plain names from the header.

See also​