/ 
SPVM-0.990179
⭐ Starred 61 / SPVM::Document::NativeAPI::CFunction

Name

SPVM::Document::NativeAPI::CFunction - C Function Native APIs

Description

Native APIs for C standard functions.

Details

Details

These native APIs are provided to safely invoke C standard functions within the SPVM runtime, effectively bridging the isolation between different compilation environments.

In scenarios where the SPVM core is compiled with one compiler (e.g., GCC) and its extension modules are compiled with another (e.g., MSVC), a "runtime boundary" is created. Because each compiler environment maintains its own global state (such as standard I/O streams) and thread-local storage (such as errno), data modified in the SPVM core may not be visible or correctly interpreted by the extension modules, and vice versa.

These APIs encapsulate the necessary logic to capture, synchronize, and handle such states across these runtime boundaries. By using these APIs, developers ensure that global and thread-specific states—such as error codes or stream positions—remain consistent and accessible, regardless of how the individual components were compiled.

Consider the following implementation of say_stderr, which attempts to print a string to standard error:

int32_t SPVM__Fn__say_stderr(SPVM_ENV* env, SPVM_VALUE* stack) {
  SPVM_OBJ* obj_string = stack[0].oval;
  
  // Prints the string via the SPVM runtime
  env->print_stderr(env, stack, obj_string);
  
  // Attempts to print a newline using a direct C function call
  env->api->cfunc->c_fputs(env, stack, "\n", env->spvm_stderr(env, stack));
  
  return 0;
}

In this example, env-spvm_stderr> returns a FILE* pointer managed by the SPVM core (compiled with GCC). However, when c_fputs is called from an extension module compiled with a different compiler (e.g., MSVC), it attempts to use the standard I/O streams of the MSVC runtime.

Because the FILE* structure and its underlying state are incompatible between different C runtimes, calling fputs with a file pointer from one runtime in another will lead to undefined behavior or crashes. Using the provided NativeAPI ensures that such operations are routed through the correct runtime environment, maintaining cross-compiler compatibility.

Usage

SPVM_API_INTERNAL* api_internal = env->api->internal;

Native APIs

c_strlen

size_t (*c_strlen)(SPVM_ENV* env, SPVM_VALUE* stack, const char* str);

A wrapper for the C standard function strlen.

c_memcpy

void* (*c_memcpy)(SPVM_ENV* env, SPVM_VALUE* stack, void* dest, const void* src, size_t n);

A wrapper for the C standard function memcpy.

c_memset

void* (*c_memset)(SPVM_ENV* env, SPVM_VALUE* stack, void* s, int c, size_t n);

A wrapper for the C standard function memset.

c_memcmp

int (*c_memcmp)(SPVM_ENV* env, SPVM_VALUE* stack, const void* s1, const void* s2, size_t n);

A wrapper for the C standard function memcmp.

c_strtoll

long long (*c_strtoll)(SPVM_ENV* env, SPVM_VALUE* stack, const char* str, char** endptr, int base);

A wrapper for the C standard function strtoll.

c_strtof

float (*c_strtof)(SPVM_ENV* env, SPVM_VALUE* stack, const char* str, char** endptr);

A wrapper for the C standard function strtof.

c_strtod

double (*c_strtod)(SPVM_ENV* env, SPVM_VALUE* stack, const char* str, char** endptr);

A wrapper for the C standard function strtod.

c_fputs

int (*c_fputs)(SPVM_ENV* env, SPVM_VALUE* stack, const char* s, void* stream);

A wrapper for the C standard function fputs.

c_fgetc

int (*c_fgetc)(SPVM_ENV* env, SPVM_VALUE* stack, void* stream);

A wrapper for the C standard function fgetc.

c_snprintf_len

int32_t (*c_snprintf_len)(SPVM_ENV* env, SPVM_VALUE* stack, char* s, size_t n, const char* format, SPVM_VALUE* args, int32_t args_length);

A wrapper for the C standard function snprintf.

This function receives arguments as an array of SPVM_VALUE instead of variadic arguments.

The format specifiers in the format string must match the types of the values stored in args.

For example: * %d, %x: Expects an ival (int32_t). * %ld, %lld (or PRId64): Expects a lval (int64_t). * %f, %g: Expects a dval (double). * %s, %p: Expects an address (void*).

Returns the number of characters that would have been written if n had been sufficiently large, not counting the terminating null character.

せやな、新しく追加したAPIたちのドキュメントを書き足すで。形式を揃えて、きもっちゃんが使いやすいように整えたわ。

c_errno

int (c_errno)(SPVM_ENV env, SPVM_VALUE* stack);

A wrapper for the C standard variable errno.

c_set_errno

void (c_set_errno)(SPVM_ENV env, SPVM_VALUE* stack, int errno_value);

Sets the value of the C standard variable errno.

c_fopen

FILE* (c_fopen)(SPVM_ENV env, SPVM_VALUE* stack, const char* path, const char* mode);

A wrapper for the C standard function fopen.

c_freopen

FILE* (c_freopen)(SPVM_ENV env, SPVM_VALUE* stack, const char* path, const char* mode, FILE* stream);

A wrapper for the C standard function freopen.

c_fclose

int (c_fclose)(SPVM_ENV env, SPVM_VALUE* stack, FILE* stream);

A wrapper for the C standard function fclose.

c_fread

size_t (c_fread)(SPVM_ENV env, SPVM_VALUE* stack, void* ptr, size_t size, size_t nmemb, FILE* stream);

A wrapper for the C standard function fread.

c_fwrite

size_t (c_fwrite)(SPVM_ENV env, SPVM_VALUE* stack, const void* ptr, size_t size, size_t nmemb, FILE* stream);

A wrapper for the C standard function fwrite.

c_fflush

int (c_fflush)(SPVM_ENV env, SPVM_VALUE* stack, FILE* stream);

A wrapper for the C standard function fflush.

c_fseek

int (c_fseek)(SPVM_ENV env, SPVM_VALUE* stack, FILE* stream, long offset, int whence);

A wrapper for the C standard function fseek.

c_ftell

long (c_ftell)(SPVM_ENV env, SPVM_VALUE* stack, FILE* stream);

A wrapper for the C standard function ftell.

c_feof

int (c_feof)(SPVM_ENV env, SPVM_VALUE* stack, FILE* stream);

A wrapper for the C standard function feof.

c_ferror

int (c_ferror)(SPVM_ENV env, SPVM_VALUE* stack, FILE* stream);

A wrapper for the C standard function ferror.

c_fileno

int (c_fileno)(SPVM_ENV env, SPVM_VALUE* stack, FILE* stream);

A wrapper for the C standard function fileno.

c_stdin

FILE* (c_stdin)(SPVM_ENV env, SPVM_VALUE* stack);

Returns the standard input stream stdin.

c_stdout

FILE* (c_stdout)(SPVM_ENV env, SPVM_VALUE* stack);

Returns the standard output stream stdout.

c_stderr

FILE* (c_stderr)(SPVM_ENV env, SPVM_VALUE* stack);

Returns the standard error stream stderr.

Native C Function API IDs

0 c_strlen
1 c_memcpy
2 c_memset
3 c_memcmp
4 c_strtoll
5 c_strtof
6 c_strtod
7 c_fputs
8 c_fgetc
9 c_snprintf_len
10 c_errno
11 c_set_errno
12 c_fopen
13 c_freopen
14 c_fclose
15 c_fread
16 c_fwrite
17 c_fflush
18 c_fseek
19 c_ftell
20 c_feof
21 c_ferror
22 c_fileno
23 c_stdin
24 c_stdout
25 c_stderr

See Also

Copyright & License

Copyright (c) 2026 Yuki Kimoto

MIT License

1 POD Error

The following errors were encountered while parsing the POD:

Around line 17:

Non-ASCII character seen before =encoding in 'states—such'. Assuming UTF-8