README- USizeT
- TFFIPtr
- Vabort
- Vatof
- Vatoi
- Vatol
- Vbytes_as_ptr
- Vbytes_to_cstr
- Vcalloc
- Vchdir
- Vclearerr
- Vclose
- Vcstr_to_string
- Vdup
- Vdup2
- Ve2big
- Veacces
- Veaddrinuse
- Veaddrnotavail
- Veafnosupport
- Veagain
- Vealready
- Vebadf
- Vebadmsg
- Vebusy
- Vecanceled
- Vechild
- Veconnaborted
- Veconnrefused
- Veconnreset
- Vedeadlk
- Vedestaddrreq
- Vedom
- Veexist
- Vefault
- Vefbig
- Vehostunreach
- Veidrm
- Veilseq
- Veinprogress
- Veintr
- Veinval
- Veio
- Veisconn
- Veisdir
- Veloop
- Vemfile
- Vemlink
- Vemsgsize
- Venametoolong
- Venetdown
- Venetreset
- Venetunreach
- Venfile
- Venobufs
- Venodata
- Venodev
- Venoent
- Venoexec
- Venolck
- Venolink
- Venomem
- Venomsg
- Venoprotoopt
- Venospc
- Venosr
- Venostr
- Venosys
- Venotconn
- Venotdir
- Venotempty
- Venotrecoverable
- Venotsock
- Venotsup
- Venotty
- Venxio
- Veopnotsupp
- Veother
- Veoverflow
- Veownerdead
- Veperm
- Vepipe
- Veproto
- Veprotonosupport
- Veprototype
- Verange
- Verofs
- Vespipe
- Vesrch
- Vetime
- Vetimedout
- Vetxtbsy
- Vewouldblock
- Vexdev
- Vexit
- Vfclose
- Vfdopen
- Vfeof
- Vferror
- Vfflush
- Vfileno
- Vfixed_array_as_ptr
- Vfopen
- Vfread
- Vfree
- Vfseek
- Vfstat
- Vfstat_atime
- Vfstat_ctime
- Vfstat_is_dir
- Vfstat_is_regular
- Vfstat_mode
- Vfstat_mtime
- Vfstat_size
- Vftell
- Vfwrite
- Vget_errno
- Vget_stderr
- Vget_stdin
- Vget_stdout
- Vgetcwd
- Vgetenv
- Vgetpid
- Vgetppid
- Vis_null
- Vlseek
- Vmalloc
- Vmap_anonymous
- Vmap_failed
- Vmap_private
- Vmap_shared
- Vmemccpy
- Vmemcmp
- Vmemcpy
- Vmemmove
- Vmemset
- Vmmap
- Vmunmap
- Vnull_ptr
- Vo_append
- Vo_creat
- Vo_excl
- Vo_nonblock
- Vo_rdonly
- Vo_rdwr
- Vo_trunc
- Vo_wronly
- Vopen
- Vpipe
- Vprot_exec
- Vprot_none
- Vprot_read
- Vprot_write
- Vptr_add
- Vptr_to_cstr
- Vread
- Vrealloc
- Vrewind
- Vseek_cur
- Vseek_end
- Vseek_set
- Vset_errno
- Vsetenv
- Vstderr_fd
- Vstdin_fd
- Vstdout_fd
- Vstrcat
- Vstrchr
- Vstrcmp
- Vstrcpy
- Vstrcspn
- Vstrdup
- Vstrerror
- Vstring_to_cstr
- Vstrlen
- Vstrncat
- Vstrncmp
- Vstrncpy
- Vstrndup
- Vstrnlen
- Vstrpbrk
- Vstrrchr
- Vstrspn
- Vstrstr
- Vstrtod
- Vstrtok
- Vstrtok_r
- Vstrtol
- Vstruncate
- Vunsetenv
- Vwrite
ffi
ffi
native
syscall
sys
libc
Author
Version
0.2.5-alpha
License
Apache-2.0
Repository
Last updated
11 hours ago
Downloads
31
#moonbit-ffi
MoonBit 的底层 C FFI 绑定。纯声明，无抽象。
#安装
moon add Qisu-dev/ffi#功能
| 模块 | 内容 |
|---|---|
| memory | malloc calloc realloc free |
| mem | memcpy memmove memset memcmp |
| ptr | is_null null_ptr ptr_add bytes_as_ptr fixed_array_as_ptr |
| str | strlen strcmp strcpy strdup bytes_to_cstr cstr_to_string |
| errno | errno_get errno_set strerror enoent eacces 等 |
| file | open close read write lseek pipe dup |
| mmap | mmap munmap（POSIX）、create_file_mapping map_view_of_file unmap_view_of_file（Windows） |
#示例
#内存与文件
fn main {
// 分配内存
let buf = @ffi.malloc(1024)
if @ffi.is_null(buf) { return }
defer @ffi.free(buf)
// 写文件
let cpath = @ffi.string_to_cstr("out.txt")
defer @ffi.free(cpath)
let fd = @ffi.open(cpath, @ffi.o_wronly() | @ffi.o_creat(), 0o644)
defer { @ffi.close(fd); () }
@ffi.write(fd, @ffi.bytes_as_ptr(b"hello"), 5)
// 错误处理
if fd < 0 {
let err = @ffi.errno_get()
println(@ffi.cstr_to_string(@ffi.strerror(err)))
}
}#内存映射读文件
#cfg(not(platform="windows"))
fn mmap_read(name : String) -> Unit raise {
let cpath = @ffi.string_to_cstr(name)
defer @ffi.free(cpath)
let fd = @ffi.open(cpath, @ffi.o_rdonly(), 0)
if fd < 0 { raise Failure("open failed") }
defer { @ffi.close(fd); () }
let fstate = @ffi.fstat(fd)
if @ffi.is_null(fstate) { raise Failure("fstat failed") }
defer @ffi.free(fstate)
let size = @ffi.fstat_size(fstate).reinterpret_as_uint64()
if size == 0 { return }
let addr = @ffi.mmap(
@ffi.null_ptr(), size,
@ffi.prot_read(), @ffi.map_private(),
fd, 0,
)
if addr == @ffi.map_failed() {
raise Failure("mmap failed")
}
defer ignore(@ffi.munmap(addr, size))
// addr 是只读的连续内存，可直接处理
ignore(addr)
}#注意
- mmap 失败返回 MAP_FAILED，用 == @ffi.map_failed() 判断，不是 is_null
- Windows 下 map_view_of_file 失败返回 NULL，用 is_null 判断
- bytes_as_ptr 返回的指针在 Bytes 释放后悬垂
- 指针偏移后不能 free，只能 free 原始指针
- 仅支持 native 后端（Windows / Linux / macOS）
#License
Apache-2.0
abort
fn abort() -> Unit异常终止当前进程。
不会执行任何清理：
- 不调用 atexit
- 不刷新 FILE* 缓冲
- 触发 SIGABRT，可能产生 core dump
用于不可恢复的错误。
chdir
切换当前工作目录到 path。
参数：
- path：目标目录路径（C 字符串）。
返回：
- 成功：0。
- 失败：-1（errno 记录原因，如 ENOENT、EACCES）。
注意：
- 影响后续所有相对路径的解析。
- 只改变当前进程的工作目录，不影响其他进程。
exit
fn exit(code : Int) -> Unit终止当前进程，退出码为 code。
会执行以下清理：
- 调用 atexit 注册的函数
- 刷新所有 FILE* 流的缓冲区
- 关闭所有打开的流
退出码约定：0 表示成功，非 0 表示失败。
fdopen
用已有的 fd 创建 FILE*。
- fd：已打开的文件描述符
- mode：模式字符串（同 fopen）
成功返回 FILE*，失败返回 NULL。
⚠️ fdopen 之后 FILE* 接管 fd，不要再直接用 fd。
fclose 会关闭底层的 fd。
feof
判断是否到达文件末尾。
返回非 0 表示 EOF，0 表示未到。
⚠️ EOF 标志是"粘性"的——只有 clearerr 或 rewind 能清除。
判断前先读取，读完后才能判断。
fileno
从 FILE* 提取底层 fd。
失败返回 -1。
⚠️ 不要混用 fread/fwrite（缓冲）和 read/write（无缓冲）——
缓冲会导致数据错位。
fixed_array_as_ptr
注意, 这个指针在fixed array死亡后会悬空
fopen
打开文件流。
- path：文件路径（C 字符串）
- mode：打开模式（"r"、"w"、"a"、"rb"、"wb" 等）
成功返回 FILE*，失败返回 NULL（errno 记录原因）。
fread
从流读取 count 个元素，每个 size 字节。
返回实际读取的元素个数（不是字节数）。
⚠️ 返回值可能是 count，也可能更少。配合 feof/ferror 判断原因。
常用 size=1 让返回值直接等于字节数。
fseek
移动文件读写位置。
- offset：相对 whence 的偏移量（字节）
- whence：基准位置（seek_set()/seek_cur()/seek_end()）
成功返回 0，失败返回非 0。
⚠️ 不支持管道、socket、终端等不可定位的流。
fstat
获取已打开文件的元数据。
内部 malloc 一个 struct stat 并调用 fstat 填充。
返回：
- 成功：指向 struct stat 的指针。
- 失败：NULL（用 is_null 判断，errno 记录原因）。
⚠️ 用完必须 stat_free 释放。
fwrite
向流写入 count 个元素，每个 size 字节。
返回实际写入的元素个数。
⚠️ 返回值 < count 表示写入不完整或出错。
常用 size=1 让返回值直接等于字节数。
getcwd
获取当前工作目录。
参数：
- buf：接收路径的缓冲区（至少 size 字节）。
- size：缓冲区大小。
返回：
- 成功：buf（指向填充好的缓冲区）。
- 失败：NULL（用 is_null() 判断，errno 记录原因）。
注意：
- 如果路径长度 ≥ size，返回 NULL 并设置 errno = ERANGE。
- 建议缓冲区至少 4096 字节（PATH_MAX 的常见值）。
- 返回的路径不带尾部斜杠（根目录除外）。
getenv
获取环境变量的值。
参数：
- name：环境变量名（C 字符串）。
返回：
- 成功：指向变量值的指针（不要 free，由环境表管理）。
- 不存在：NULL（用 is_null() 判断）。
注意：
- 返回的指针在后续 setenv/unsetenv 后可能失效。
- 不要修改返回的字符串。
map_failed
POSIX mmap 的失败返回值 MAP_FAILED，即 (void*)-1。
⚠️ 这不是 NULL！判断 mmap 是否失败要用 == map_failed()，不能用 is_null()。
fn map_shared() -> IntMAP_SHARED — 共享映射（写入影响原文件）。
memccpy
拷贝直到遇到字符 c 或拷满 n 字节。返回指向 c 后一个字节的指针，或 NULL。
mmap
将文件或匿名内存映射到进程地址空间。
参数：
- addr：建议的映射起始地址。
- 传 null_ptr() → 由系统选择合适地址（推荐）。
- 传具体地址 → 系统尽量满足，但可能忽略。
- len：要映射的字节数。
- 匿名映射：分配的字节数。
- 文件映射：映射的文件区间长度。
- prot：内存保护属性，描述访问权限。
- prot_read()：可读。
- prot_write()：可写。
- prot_exec()：可执行。
- prot_none()：不可访问。
- 可用 | 组合，如 prot_read() | prot_write()。
- flags：映射标志，决定映射类型和行为。
- map_shared()：共享映射，写入影响原文件。
- map_private()：私有映射，写时复制（COW）。
- map_anonymous()：匿名映射，不关联文件（fd 传 -1）。
- 必须指定 map_shared() 或 map_private() 之一。
- fd：文件描述符。
- 文件映射：open() 返回的有效 fd。
- 匿名映射：传 -1（同时 flags 必须含 map_anonymous()）。
- offset：文件偏移量。
- 必须页对齐（通常是 4096 的倍数）。
- 匿名映射：传 0。
返回：
- 成功：映射区域的起始地址。
- 失败：MAP_FAILED（即 (void*)-1，用 == map_failed() 判断，不是 is_null()）。
注意：
- 映射后可用指针直接读写文件内容，无需 read/write。
- 使用完毕必须调用 munmap(addr, len) 解除映射。
- map_shared() 的写入会同步到文件，map_private() 的写入不会。
read
从文件描述符读取。返回读取字节数（0 = EOF，-1 = 错误）。
setenv
设置环境变量。
参数：
- name：变量名。
- value：变量值。
- overwrite：非 0 则覆盖已存在的变量，0 则不覆盖。
返回：
- 成功：0。
- 失败：-1（errno 记录原因）。
注意： Windows 上 overwrite 参数被忽略，总是覆盖。
strcat
⚠️ 不安全：不检查 dst 大小，可能溢出。
strncpy
⚠️ 半安全：限制长度，但可能不补 \0 结尾。
此函数并非不可使用而是极其易错
如果你想继续使用
如下示例
let cstr_ptr = bytes_to_cstr(b"hello", 5)
defer free_cstr(cstr_ptr)
let dst = malloc(6)
defer free(dst)
strncpy(dst, cstr_ptr, 5)
memset(ptr_add(dst, 5), 0, 1)strtok
⚠️ 会修改原字符串，且非线程安全。推荐用 strtok_r/strtok_s。
strtok_r
POSIX 可重入分词（Linux/macOS）
Install
Download zipffinativesyscallsyslibc
Apache-2.0
Updated 11 hours ago
31 downloads