docs/efun: document FFI + dwlib efuns, fix return-type errors, drop stale docs

Reviewed every efun doc against the .spec source of truth (the make_func
declarations) and the implementations.

New docs for 28 previously-undocumented efuns:
- package_ffi (18): new docs/efun/ffi/ category — ffi_load/unload/symbol/
  prepare/call, alloc/free/sizeof/peek/address/read/write, struct_layout,
  callback/callback_addr/callback_free, error/status.
- package_dwlib (10, under contrib/): add_a, vowel, replace,
  replace_dollars/html/mxp/objects, roulette_wheel, query_multiple_short,
  reference_allowed.

Return-type fixes where the doc contradicted the spec/impl (mostly stale
MudOS behavior): cache_stats/debugmalloc/dump_file_descriptors/
malloc_status/mud_status return string; disable_commands/flush_messages/
receive/set_heart_beat are void; get_char/input_to/link/set_eval_limit
return int; call_stack -> mixed *, function_profile -> mapping *. Also
corrected receive's and disable_commands' stale "returns ..." prose.

Expanded implode (function-fold form) and save_object (save-to-string
form), both of which the docs had omitted.

Removed 4 stale docs for efuns that no longer exist (no spec entry, no
f_ implementation, zero references anywhere): errorp, opcprof, swap,
dump_socket_status.

Regenerated the affected efun index pages. The Docusaurus build passes
with onBrokenLinks:throw, confirming no dangling links.

Note: the docs/zh-CN translated tree still mirrors the old English docs
(same stale entries, and it lacks the new efuns); left for a separate
translation pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/efun/calls/call_stack.md

@@ -11,7 +11,7 @@ title: calls / call_stack
 
 ### SYNOPSIS
 
-    string *call_stack(int option);
+    mixed *call_stack(int option);
 
 ### DESCRIPTION
 

docs/efun/contrib/add_a.md

@@ -0,0 +1,25 @@
+---
+layout: doc
+title: contrib / add_a
+---
+# add_a
+
+### NAME
+
+    add_a() - prefix a string with the correct indefinite article
+
+### SYNOPSIS
+
+    string add_a( string str );
+
+### DESCRIPTION
+
+    Returns `str` with "a " or "an " prepended, choosing the article
+    from the following word's sound rather than just its first letter:
+    vowels take "an", but the special cases "us..." ("a user", "a use"),
+    "hour..." ("an hour"), and words already beginning "a "/"an " are
+    handled. A string of only spaces yields "a ".
+
+### SEE ALSO
+
+    add_a(3), vowel(3)

docs/efun/contrib/index.md

@@ -3,6 +3,7 @@ layout: doc
 title: contrib
 ---
 * [abs](abs)
+* [add_a](add_a)
 * [assemble_class](assemble_class)
 * [base_name](base_name)
 * [classes](classes)
@@ -30,18 +31,26 @@ title: contrib
 * [program_info](program_info)
 * [query_charmode](query_charmode)
 * [query_ip_port](query_ip_port)
+* [query_multiple_short](query_multiple_short)
 * [query_notify_fail](query_notify_fail)
 * [query_num](query_num)
 * [query_replaced_program](query_replaced_program)
 * [real_time](real_time)
+* [reference_allowed](reference_allowed)
 * [remove_charmode](remove_charmode)
 * [remove_get_char](remove_get_char)
 * [remove_interactive](remove_interactive)
 * [remove_shadow](remove_shadow)
 * [repeat_string](repeat_string)
+* [replace](replace)
+* [replace_dollars](replace_dollars)
+* [replace_html](replace_html)
+* [replace_mxp](replace_mxp)
+* [replace_objects](replace_objects)
 * [replaceable](replaceable)
 * [restore_from_string](restore_from_string)
 * [roll_MdN](roll_MdN)
+* [roulette_wheel](roulette_wheel)
 * [send_nullbyte](send_nullbyte)
 * [set_prompt](set_prompt)
 * [shuffle](shuffle)
@@ -52,4 +61,5 @@ title: contrib
 * [test_load](test_load)
 * [upper_case](upper_case)
 * [variables](variables)
+* [vowel](vowel)
 * [zonetime](zonetime)

docs/efun/contrib/query_multiple_short.md

@@ -0,0 +1,29 @@
+---
+layout: doc
+title: contrib / query_multiple_short
+---
+# query_multiple_short
+
+### NAME
+
+    query_multiple_short() - combine several objects into one short description
+
+### SYNOPSIS
+
+    string query_multiple_short( mixed *items, int|string|void type, int|void no_dollars, int|void quiet, int|void dark );
+
+### DESCRIPTION
+
+    Formats an array of items (objects, or their short strings) into a
+    single natural-language list — grouping identical shorts and counting
+    them, e.g. "two swords, a shield and some coins".
+
+    The optional arguments tune the output: `type` selects which short
+    (a named category) to query from the objects; `no_dollars` suppresses
+    the `$`-markup used for colour/where clauses; `quiet` omits items
+    flagged as quiet; and `dark` produces the description as seen in the
+    dark. This is a Discworld-mudlib inventory helper.
+
+### SEE ALSO
+
+    query_multiple_short(3)

docs/efun/contrib/reference_allowed.md

@@ -0,0 +1,25 @@
+---
+layout: doc
+title: contrib / reference_allowed
+---
+# reference_allowed
+
+### NAME
+
+    reference_allowed() - Discworld playtester reference check
+
+### SYNOPSIS
+
+    int reference_allowed( object referee, string|object|void referrer );
+
+### DESCRIPTION
+
+    Discworld-mudlib helper: returns whether `referrer` (defaulting to
+    this_player(), or looked up by name if a string is given) is allowed
+    to hold a reference to `referee`, consulting the mudlib's playtester
+    and player handlers. Returns 0 when the handlers are absent, so it is
+    only meaningful in a mudlib that provides them.
+
+### SEE ALSO
+
+    this_player(3)

docs/efun/contrib/replace.md

@@ -0,0 +1,30 @@
+---
+layout: doc
+title: contrib / replace
+---
+# replace
+
+### NAME
+
+    replace() - replace occurrences of a substring, or of many substrings
+
+### SYNOPSIS
+
+    string replace( string str, string *|string from, string|void to );
+
+### DESCRIPTION
+
+    Two forms:
+
+    - `replace(str, from, to)` returns `str` with every occurrence of the
+      string `from` replaced by `to` (this is the plain string form,
+      equivalent to the replace_string() efun).
+    - `replace(str, arr)` takes an even-length array `arr` of
+      `({ from1, to1, from2, to2, ... })` pairs and applies each
+      replacement in turn.
+
+    Errors on an odd-length pair array.
+
+### SEE ALSO
+
+    replace_string(3), replace_dollars(3)

docs/efun/contrib/replace_dollars.md

@@ -0,0 +1,26 @@
+---
+layout: doc
+title: contrib / replace_dollars
+---
+# replace_dollars
+
+### NAME
+
+    replace_dollars() - expand $-markers in a string
+
+### SYNOPSIS
+
+    string replace_dollars( string str, string *pairs );
+
+### DESCRIPTION
+
+    Scans `str` for `$`-prefixed markers and substitutes them using
+    `pairs`, an even-length array alternating a marker and its
+    replacement text, e.g.
+    `({ "$name", "Bob", "$place", "the docks" })`. Text that matches no
+    marker is copied through unchanged; if nothing matches, the original
+    string is returned.
+
+### SEE ALSO
+
+    replace(3), replace_string(3)

docs/efun/contrib/replace_html.md

@@ -0,0 +1,24 @@
+---
+layout: doc
+title: contrib / replace_html
+---
+# replace_html
+
+### NAME
+
+    replace_html() - escape a string for HTML
+
+### SYNOPSIS
+
+    string replace_html( string str );
+
+### DESCRIPTION
+
+    Returns `str` with the HTML-significant characters escaped:
+    `&` becomes `&amp;`, `<` becomes `&lt;`, `>` becomes `&gt;`, and
+    `"` becomes `&quot;`. The result is capped at the driver's maximum
+    string length.
+
+### SEE ALSO
+
+    replace_mxp(3)

docs/efun/contrib/replace_mxp.md

@@ -0,0 +1,24 @@
+---
+layout: doc
+title: contrib / replace_mxp
+---
+# replace_mxp
+
+### NAME
+
+    replace_mxp() - escape a string for MXP
+
+### SYNOPSIS
+
+    string replace_mxp( string str );
+
+### DESCRIPTION
+
+    Returns `str` escaped for MXP output: `&`, `<` and `>` become their
+    entity forms (`&amp;`, `&lt;`, `&gt;`) and each newline is turned into
+    a secure-line MXP `<BR>` tag. The result is capped at the driver's
+    maximum string length.
+
+### SEE ALSO
+
+    replace_html(3)

docs/efun/contrib/replace_objects.md

@@ -0,0 +1,26 @@
+---
+layout: doc
+title: contrib / replace_objects
+---
+# replace_objects
+
+### NAME
+
+    replace_objects() - recursively render objects in a value as strings
+
+### SYNOPSIS
+
+    mixed replace_objects( mixed value );
+
+### DESCRIPTION
+
+    Walks `value` (an object, array, class, or mapping, to any depth) and
+    returns a copy in which every object is replaced by a descriptive
+    string — its object name plus, via the master apply object_name(),
+    a readable label, or "(destructed)" for a destructed object. Arrays,
+    classes and mappings keep their structure; other values pass through
+    unchanged. Chiefly a debugging / dump helper.
+
+### SEE ALSO
+
+    sprintf(3)

docs/efun/contrib/roulette_wheel.md

@@ -0,0 +1,24 @@
+---
+layout: doc
+title: contrib / roulette_wheel
+---
+# roulette_wheel
+
+### NAME
+
+    roulette_wheel() - weighted-random pick of a mapping key
+
+### SYNOPSIS
+
+    mixed roulette_wheel( mapping weights );
+
+### DESCRIPTION
+
+    Given a mapping whose values are non-negative integer weights,
+    returns one of its keys chosen at random with probability
+    proportional to that key's weight ("roulette-wheel" selection).
+    Errors on an empty mapping or a negative/non-integer weight.
+
+### SEE ALSO
+
+    random(3)

docs/efun/contrib/vowel.md

@@ -0,0 +1,23 @@
+---
+layout: doc
+title: contrib / vowel
+---
+# vowel
+
+### NAME
+
+    vowel() - test whether a character is a vowel
+
+### SYNOPSIS
+
+    int vowel( int c );
+
+### DESCRIPTION
+
+    Returns 1 if the character code `c` is an ASCII vowel
+    (a, e, i, o, u in either case), 0 otherwise. Used together with
+    add_a() for article selection.
+
+### SEE ALSO
+
+    add_a(3)

docs/efun/ffi/ffi_address.md

@@ -0,0 +1,23 @@
+---
+layout: doc
+title: ffi / ffi_address
+---
+# ffi_address
+
+### NAME
+
+    ffi_address() - raw native address of a buffer
+
+### SYNOPSIS
+
+    int ffi_address( buffer mem );
+
+### DESCRIPTION
+
+    Returns the raw native address of the first byte of `mem` as an
+    integer — for passing to C as a pointer value or for pointer
+    comparisons. The address is valid only while `mem` is alive.
+
+### SEE ALSO
+
+    ffi_alloc(3), ffi_peek(3), ffi_call(3)

docs/efun/ffi/ffi_alloc.md

@@ -0,0 +1,24 @@
+---
+layout: doc
+title: ffi / ffi_alloc
+---
+# ffi_alloc
+
+### NAME
+
+    ffi_alloc() - allocate a native memory block as a buffer
+
+### SYNOPSIS
+
+    buffer ffi_alloc( int nbytes );
+
+### DESCRIPTION
+
+    Returns a zeroed buffer of `nbytes` bytes whose storage is the native
+    memory block itself, suitable for structs, out-parameters, and
+    pointer arguments to ffi_call(). The block is reference-counted like
+    any buffer and freed by the GC; ffi_free() releases it early.
+
+### SEE ALSO
+
+    ffi_free(3), ffi_read(3), ffi_write(3), ffi_address(3), ffi_struct_layout(3)

docs/efun/ffi/ffi_call.md

@@ -0,0 +1,30 @@
+---
+layout: doc
+title: ffi / ffi_call
+---
+# ffi_call
+
+### NAME
+
+    ffi_call() - call a prepared C function
+
+### SYNOPSIS
+
+    mixed ffi_call( int func, mixed *args );
+
+### DESCRIPTION
+
+    Calls the function handle `func` returned by ffi_prepare(). `args`
+    must have exactly the prepared argument count; each element is an
+    int, a float, or a buffer (never a string — LPC strings are
+    UTF-8-native and never implicitly marshalled to char*), matching the
+    prepared argument type codes.
+
+    The return value follows `ret_type`: an int or float for scalar
+    types, a buffer for an owned FFI_POINTER result or an int address for
+    a raw foreign pointer, and 0 for FFI_VOID. Argument-count or -type
+    mismatches raise an error rather than calling C with a bad frame.
+
+### SEE ALSO
+
+    ffi_prepare(3), ffi_peek(3), ffi_alloc(3), string_encode(3), string_decode(3)

docs/efun/ffi/ffi_callback.md

@@ -0,0 +1,27 @@
+---
+layout: doc
+title: ffi / ffi_callback
+---
+# ffi_callback
+
+### NAME
+
+    ffi_callback() - expose an LPC function to C as a callback
+
+### SYNOPSIS
+
+    int ffi_callback( function fn, int ret_type, int *arg_types );
+
+### DESCRIPTION
+
+    Wraps the LPC function pointer `fn` in a libffi closure with the
+    given return and argument type codes (from <ffi.h>), and returns a
+    callback handle. Pass ffi_callback_addr() of that handle to C as an
+    FFI_POINTER argument so a C library (a comparator for qsort(), an
+    event handler, ...) can call back into LPC.
+
+    Gated by the master apply valid_ffi("callback", 0, caller).
+
+### SEE ALSO
+
+    ffi_callback_addr(3), ffi_callback_free(3), ffi_call(3), valid_ffi(4)

docs/efun/ffi/ffi_callback_addr.md

@@ -0,0 +1,23 @@
+---
+layout: doc
+title: ffi / ffi_callback_addr
+---
+# ffi_callback_addr
+
+### NAME
+
+    ffi_callback_addr() - raw address of a callback closure
+
+### SYNOPSIS
+
+    int ffi_callback_addr( int cb );
+
+### DESCRIPTION
+
+    Returns the raw native code address of the closure for callback
+    handle `cb` (from ffi_callback()), as an integer — the value to hand
+    to C as an FFI_POINTER argument.
+
+### SEE ALSO
+
+    ffi_callback(3), ffi_callback_free(3), ffi_call(3)

docs/efun/ffi/ffi_callback_free.md

@@ -0,0 +1,23 @@
+---
+layout: doc
+title: ffi / ffi_callback_free
+---
+# ffi_callback_free
+
+### NAME
+
+    ffi_callback_free() - release a callback closure
+
+### SYNOPSIS
+
+    void ffi_callback_free( int cb );
+
+### DESCRIPTION
+
+    Releases the libffi closure for callback handle `cb`. Optional — the
+    closure is also reclaimed by the GC. Do not free a callback while C
+    still holds its address.
+
+### SEE ALSO
+
+    ffi_callback(3), ffi_callback_addr(3)

docs/efun/ffi/ffi_error.md

@@ -0,0 +1,25 @@
+---
+layout: doc
+title: ffi / ffi_error
+---
+# ffi_error
+
+### NAME
+
+    ffi_error() - most recent FFI error message
+
+### SYNOPSIS
+
+    string ffi_error();
+
+### DESCRIPTION
+
+    Returns the most recent FFI error message for the current thread —
+    for example the reason a ffi_load() returned 0 — or the empty string
+    if there has been no error. Efuns on the FFI surface raise an LPC
+    error on misuse; ffi_error() reports the failures that are signalled
+    by a 0 return instead.
+
+### SEE ALSO
+
+    ffi_load(3), ffi_symbol(3), ffi_status(3)

docs/efun/ffi/ffi_free.md

@@ -0,0 +1,23 @@
+---
+layout: doc
+title: ffi / ffi_free
+---
+# ffi_free
+
+### NAME
+
+    ffi_free() - free a native memory block
+
+### SYNOPSIS
+
+    void ffi_free( buffer mem );
+
+### DESCRIPTION
+
+    Releases a buffer allocated by ffi_alloc(). Optional — the block is
+    also reclaimed by the garbage collector when no LPC value references
+    it. Using `mem` after freeing it is an error.
+
+### SEE ALSO
+
+    ffi_alloc(3)

docs/efun/ffi/ffi_load.md

@@ -0,0 +1,30 @@
+---
+layout: doc
+title: ffi / ffi_load
+---
+# ffi_load
+
+### NAME
+
+    ffi_load() - load a native shared library
+
+### SYNOPSIS
+
+    int ffi_load( string path );
+
+### DESCRIPTION
+
+    Opens the shared library at `path` (via dlopen/LoadLibrary) and
+    returns a positive library handle for use with ffi_symbol() and
+    ffi_prepare(). Returns 0 on failure; call ffi_error() for the reason.
+
+    An empty `path` opens the driver's own process image, giving access
+    to already-linked C symbols such as libc/libm (`sqrt`, `abs`, ...).
+
+    Every call is gated by the master apply valid_ffi("load", path,
+    caller); the default master denies it. This efun is only present when
+    the driver is built with package_ffi (`__PACKAGE_FFI__`).
+
+### SEE ALSO
+
+    ffi_symbol(3), ffi_prepare(3), ffi_unload(3), ffi_error(3), valid_ffi(4)

docs/efun/ffi/ffi_peek.md

@@ -0,0 +1,26 @@
+---
+layout: doc
+title: ffi / ffi_peek
+---
+# ffi_peek
+
+### NAME
+
+    ffi_peek() - copy bytes from a raw foreign address into a buffer
+
+### SYNOPSIS
+
+    buffer ffi_peek( int address, int nbytes );
+
+### DESCRIPTION
+
+    Copies `nbytes` bytes starting at the raw native `address` into a
+    fresh owned buffer. This is the only way bytes behind a foreign
+    pointer — for example a `char *` returned by a C function — become an
+    LPC value. Pass -1 for `nbytes` to copy a NUL-terminated string up to
+    an internal cap. Decode text with string_decode() once you have the
+    bytes.
+
+### SEE ALSO
+
+    ffi_call(3), ffi_symbol(3), ffi_address(3), string_decode(3)

docs/efun/ffi/ffi_prepare.md

@@ -0,0 +1,27 @@
+---
+layout: doc
+title: ffi / ffi_prepare
+---
+# ffi_prepare
+
+### NAME
+
+    ffi_prepare() - describe a C function signature for calling
+
+### SYNOPSIS
+
+    int ffi_prepare( int lib, string name, int ret_type, int *arg_types );
+
+### DESCRIPTION
+
+    Resolves `name` in `lib`, builds the platform call frame for the
+    described signature, and returns a callable function handle for
+    ffi_call(). `ret_type` and each element of `arg_types` are type codes
+    from <ffi.h> (FFI_INT32, FFI_DOUBLE, FFI_POINTER, ...).
+
+    Gated by the master apply valid_ffi("prepare", name, caller). Errors
+    if the symbol is missing or a type code is invalid.
+
+### SEE ALSO
+
+    ffi_call(3), ffi_load(3), ffi_sizeof(3), valid_ffi(4)

docs/efun/ffi/ffi_read.md

@@ -0,0 +1,24 @@
+---
+layout: doc
+title: ffi / ffi_read
+---
+# ffi_read
+
+### NAME
+
+    ffi_read() - read a typed scalar from a buffer
+
+### SYNOPSIS
+
+    mixed ffi_read( buffer mem, int offset, int type_code );
+
+### DESCRIPTION
+
+    Reads the scalar of type `type_code` (a code from <ffi.h>) stored at
+    byte `offset` within `mem`, returning an int for integer/pointer
+    types or a float for FFI_FLOAT/FFI_DOUBLE. Combine with
+    ffi_struct_layout() to read C struct fields symbolically.
+
+### SEE ALSO
+
+    ffi_write(3), ffi_struct_layout(3), ffi_sizeof(3)

docs/efun/ffi/ffi_sizeof.md

@@ -0,0 +1,23 @@
+---
+layout: doc
+title: ffi / ffi_sizeof
+---
+# ffi_sizeof
+
+### NAME
+
+    ffi_sizeof() - size of a scalar type code
+
+### SYNOPSIS
+
+    int ffi_sizeof( int type_code );
+
+### DESCRIPTION
+
+    Returns the size in bytes, on this platform, of the scalar C type
+    named by `type_code` (a code from <ffi.h>). Useful for sizing
+    ffi_alloc() blocks and computing offsets by hand.
+
+### SEE ALSO
+
+    ffi_alloc(3), ffi_struct_layout(3), ffi_read(3)

docs/efun/ffi/ffi_status.md

@@ -0,0 +1,24 @@
+---
+layout: doc
+title: ffi / ffi_status
+---
+# ffi_status
+
+### NAME
+
+    ffi_status() - counts of open FFI handles
+
+### SYNOPSIS
+
+    mapping ffi_status();
+
+### DESCRIPTION
+
+    Returns a mapping of live-handle counts for introspection and leak
+    checks, with integer values under the keys "libraries" (open
+    ffi_load() handles), "functions" (prepared ffi_prepare() handles),
+    and "callbacks" (live ffi_callback() closures).
+
+### SEE ALSO
+
+    ffi_load(3), ffi_prepare(3), ffi_callback(3)

docs/efun/ffi/ffi_struct_layout.md

@@ -0,0 +1,25 @@
+---
+layout: doc
+title: ffi / ffi_struct_layout
+---
+# ffi_struct_layout
+
+### NAME
+
+    ffi_struct_layout() - compute a C struct's field layout
+
+### SYNOPSIS
+
+    mixed *ffi_struct_layout( int *field_types );
+
+### DESCRIPTION
+
+    Given an array of scalar type codes (from <ffi.h>), one per struct
+    field, returns `({ total_size, ({ offset0, offset1, ... }) })`
+    honoring the platform's alignment rules. Size an ffi_alloc() block to
+    `total_size` and use the offsets with ffi_read()/ffi_write(). The
+    tools/ffi generator emits these arrays from a C header.
+
+### SEE ALSO
+
+    ffi_alloc(3), ffi_read(3), ffi_write(3), ffi_sizeof(3)

docs/efun/ffi/ffi_symbol.md

@@ -0,0 +1,29 @@
+---
+layout: doc
+title: ffi / ffi_symbol
+---
+# ffi_symbol
+
+### NAME
+
+    ffi_symbol() - resolve a symbol to its raw address
+
+### SYNOPSIS
+
+    int ffi_symbol( int lib, string name );
+
+### DESCRIPTION
+
+    Resolves the symbol `name` in library `lib` and returns its raw
+    native address as an integer, or 0 if not found.
+
+    To *call* a C function you do not need this — use ffi_prepare(), which
+    resolves the symbol itself. ffi_symbol() is for taking the address of
+    a data symbol (read it with ffi_peek()) or of a function to pass to C
+    as an FFI_POINTER argument.
+
+    Gated by the master apply valid_ffi("symbol", name, caller).
+
+### SEE ALSO
+
+    ffi_prepare(3), ffi_peek(3), ffi_address(3), valid_ffi(4)

docs/efun/ffi/ffi_unload.md

@@ -0,0 +1,23 @@
+---
+layout: doc
+title: ffi / ffi_unload
+---
+# ffi_unload
+
+### NAME
+
+    ffi_unload() - release a library handle
+
+### SYNOPSIS
+
+    void ffi_unload( int lib );
+
+### DESCRIPTION
+
+    Releases a library handle returned by ffi_load(). Function handles
+    prepared from it become invalid. Libraries are also released when the
+    driver shuts down.
+
+### SEE ALSO
+
+    ffi_load(3), ffi_status(3)

docs/efun/ffi/ffi_write.md

@@ -0,0 +1,24 @@
+---
+layout: doc
+title: ffi / ffi_write
+---
+# ffi_write
+
+### NAME
+
+    ffi_write() - write a typed scalar into a buffer
+
+### SYNOPSIS
+
+    void ffi_write( buffer mem, int offset, int type_code, mixed value );
+
+### DESCRIPTION
+
+    Writes `value` as the scalar type `type_code` (a code from <ffi.h>)
+    at byte `offset` within `mem`. `value` is an int for integer/pointer
+    types or a float for FFI_FLOAT/FFI_DOUBLE. Used to fill struct fields
+    and out-parameters before an ffi_call().
+
+### SEE ALSO
+
+    ffi_read(3), ffi_struct_layout(3), ffi_alloc(3)

docs/efun/ffi/index.md

@@ -0,0 +1,22 @@
+---
+layout: doc
+title: ffi
+---
+* [ffi_address](ffi_address)
+* [ffi_alloc](ffi_alloc)
+* [ffi_call](ffi_call)
+* [ffi_callback](ffi_callback)
+* [ffi_callback_addr](ffi_callback_addr)
+* [ffi_callback_free](ffi_callback_free)
+* [ffi_error](ffi_error)
+* [ffi_free](ffi_free)
+* [ffi_load](ffi_load)
+* [ffi_peek](ffi_peek)
+* [ffi_prepare](ffi_prepare)
+* [ffi_read](ffi_read)
+* [ffi_sizeof](ffi_sizeof)
+* [ffi_status](ffi_status)
+* [ffi_struct_layout](ffi_struct_layout)
+* [ffi_symbol](ffi_symbol)
+* [ffi_unload](ffi_unload)
+* [ffi_write](ffi_write)

docs/efun/filesystem/link.md

@@ -10,7 +10,7 @@ title: filesystem / link
 
 ### SYNOPSIS
 
-    void link( string original, string reference );
+    int link( string original, string reference );
 
 ### DESCRIPTION
 

docs/efun/index.md

@@ -40,6 +40,7 @@ title: EFUN
 * [throw](calls/throw)
 ## contrib
 * [abs](contrib/abs)
+* [add_a](contrib/add_a)
 * [assemble_class](contrib/assemble_class)
 * [base_name](contrib/base_name)
 * [classes](contrib/classes)
@@ -67,18 +68,26 @@ title: EFUN
 * [program_info](contrib/program_info)
 * [query_charmode](contrib/query_charmode)
 * [query_ip_port](contrib/query_ip_port)
+* [query_multiple_short](contrib/query_multiple_short)
 * [query_notify_fail](contrib/query_notify_fail)
 * [query_num](contrib/query_num)
 * [query_replaced_program](contrib/query_replaced_program)
 * [real_time](contrib/real_time)
+* [reference_allowed](contrib/reference_allowed)
 * [remove_charmode](contrib/remove_charmode)
 * [remove_get_char](contrib/remove_get_char)
 * [remove_interactive](contrib/remove_interactive)
 * [remove_shadow](contrib/remove_shadow)
 * [repeat_string](contrib/repeat_string)
+* [replace](contrib/replace)
+* [replace_dollars](contrib/replace_dollars)
+* [replace_html](contrib/replace_html)
+* [replace_mxp](contrib/replace_mxp)
+* [replace_objects](contrib/replace_objects)
 * [replaceable](contrib/replaceable)
 * [restore_from_string](contrib/restore_from_string)
 * [roll_MdN](contrib/roll_MdN)
+* [roulette_wheel](contrib/roulette_wheel)
 * [send_nullbyte](contrib/send_nullbyte)
 * [set_prompt](contrib/set_prompt)
 * [shuffle](contrib/shuffle)
@@ -89,6 +98,7 @@ title: EFUN
 * [test_load](contrib/test_load)
 * [upper_case](contrib/upper_case)
 * [variables](contrib/variables)
+* [vowel](contrib/vowel)
 * [zonetime](contrib/zonetime)
 ## crypto
 * [hash](crypto/hash)
@@ -106,6 +116,25 @@ title: EFUN
 * [query_ed_mode](ed/query_ed_mode)
 ## external
 * [external_start](external/external_start)
+## ffi
+* [ffi_address](ffi/ffi_address)
+* [ffi_alloc](ffi/ffi_alloc)
+* [ffi_call](ffi/ffi_call)
+* [ffi_callback](ffi/ffi_callback)
+* [ffi_callback_addr](ffi/ffi_callback_addr)
+* [ffi_callback_free](ffi/ffi_callback_free)
+* [ffi_error](ffi/ffi_error)
+* [ffi_free](ffi/ffi_free)
+* [ffi_load](ffi/ffi_load)
+* [ffi_peek](ffi/ffi_peek)
+* [ffi_prepare](ffi/ffi_prepare)
+* [ffi_read](ffi/ffi_read)
+* [ffi_sizeof](ffi/ffi_sizeof)
+* [ffi_status](ffi/ffi_status)
+* [ffi_struct_layout](ffi/ffi_struct_layout)
+* [ffi_symbol](ffi/ffi_symbol)
+* [ffi_unload](ffi/ffi_unload)
+* [ffi_write](ffi/ffi_write)
 ## filesystem
 * [cp](filesystem/cp)
 * [file_size](filesystem/file_size)
@@ -244,21 +273,18 @@ title: EFUN
 * [debugmalloc](internals/debugmalloc)
 * [dump_file_descriptors](internals/dump_file_descriptors)
 * [dump_prog](internals/dump_prog)
-* [dump_socket_status](internals/dump_socket_status)
 * [dumpallobj](internals/dumpallobj)
 * [get_config](internals/get_config)
 * [malloc_status](internals/malloc_status)
 * [memory_info](internals/memory_info)
 * [moncontrol](internals/moncontrol)
 * [mud_status](internals/mud_status)
-* [opcprof](internals/opcprof)
 * [query_load_average](internals/query_load_average)
 * [refs](internals/refs)
 * [rusage](internals/rusage)
 * [set_config](internals/set_config)
 * [set_debug_level](internals/set_debug_level)
 * [set_malloc_mask](internals/set_malloc_mask)
-* [swap](internals/swap)
 * [time_expression](internals/time_expression)
 * [trace](internals/trace)
 * [traceprefix](internals/traceprefix)
@@ -394,7 +420,6 @@ title: EFUN
 * [ctime](system/ctime)
 * [deep_inherit_list](system/deep_inherit_list)
 * [error](system/error)
-* [errorp](system/errorp)
 * [eval_cost](system/eval_cost)
 * [find_call_out](system/find_call_out)
 * [flush_messages](system/flush_messages)

docs/efun/interactive/disable_commands.md

@@ -10,16 +10,15 @@ title: interactive / disable_commands
 
 ### SYNOPSIS
 
-    int disable_commands( void );
+    void disable_commands();
 
 ### DESCRIPTION
 
     Makes a living object non-living, that is, add_actions have no effects,
     livingp returns false, and, if the object is interactive, disallows the
-    user  to type in commands other than for an input_to.  disable_commands
-    always returns 0.
+    user to type in commands other than for an input_to.
 
-    calling disable_commands() also have side-effct of clearing all actions
+    calling disable_commands() also has the side-effect of clearing all actions
     previously  added  by  other  object,  it also removes actions that was
     defined by this object.
 

docs/efun/interactive/get_char.md

@@ -11,7 +11,7 @@ title: interactive / get_char
 
 ### SYNOPSIS
 
-    varargs void get_char( string | function fun, int flag, ... );
+    varargs int get_char( string | function fun, int flag, ... );
 
 ### DESCRIPTION
 

docs/efun/interactive/input_to.md

@@ -11,7 +11,7 @@ title: interactive / input_to
 
 ### SYNOPSIS
 
-    varargs void input_to( string | function fun, int flag, ... );
+    varargs int input_to( string | function fun, int flag, ... );
 
 ### DESCRIPTION
 

docs/efun/interactive/receive.md

@@ -10,14 +10,14 @@ title: interactive / receive
 
 ### SYNOPSIS
 
-    int receive( string message );
+    void receive( string | buffer message );
 
 ### DESCRIPTION
 
     This  efun is an interface to the add_message() function in the driver.
-    Its purpose is to display a message to the current object.  It  returns
-    1  if the current object is interactive, 0 otherwise.  Often, receive()
-    is called from within catch_tell(4) or receive_message(4).
+    Its  purpose  is  to  display  a message to the current object. The
+    message may be a string or a buffer of raw bytes.  Often, receive() is
+    called from within catch_tell(4) or receive_message(4).
 
 ### SEE ALSO
 

docs/efun/internals/cache_stats.md

@@ -10,7 +10,7 @@ title: internals / cache_stats
 
 ### SYNOPSIS
 
-    void cache_stats( void );
+    string cache_stats();
 
 ### DESCRIPTION
 

docs/efun/internals/debugmalloc.md

@@ -10,7 +10,7 @@ title: internals / debugmalloc
 
 ### SYNOPSIS
 
-    void debugmalloc( string filename, int mask );
+    string debugmalloc( string filename, int mask );
 
 ### DESCRIPTION
 

docs/efun/internals/dump_file_descriptors.md

@@ -10,7 +10,7 @@ title: internals / dump_file_descriptors
 
 ### SYNOPSIS
 
-    void dump_file_descriptors( void );
+    string dump_file_descriptors();
 
 ### DESCRIPTION
 

docs/efun/internals/dump_socket_status.md

@@ -1,48 +0,0 @@
----
-layout: doc
-title: internals / dump_socket_status
----
-# dump_socket_status
-
-### NAME
-
-    dump_socket_status() - display the status of each LPC socket
-
-### SYNOPSIS
-
-    void dump_socket_status( void );
-
-### DESCRIPTION
-
-    dump_socket_status()  is  a diagnostic facility which displays the cur‐
-    rent status of all LPC sockets configured into the MudOS driver.  It is
-    useful  for debugging LPC sockets applications.  Each row in the output
-    corresponds to a single LPC socket.  The first row corresponds  to  LPC
-    socket descriptor 0, the second row, 1, etc.  The total number of sock‐
-    ets is configured when the driver is built.
-
-    The first column "Fd" is the operating system file  descriptor  associ‐
-    ated  with the LPC socket.  "State" is the current operational state of
-    the LPC socket.  "Mode" is the socket mode, which is passed as an argu‐
-    ment to socket_create().  The local and remote addresses are the Inter‐
-    net address and port numbers in Internet dot notations.  '*'  indicates
-    an  address  or  which  is  0.  N.B. LPC sockets that are in the CLOSED
-    state are not currently in use; therefore the data displayed  for  that
-    socket may be idiosyncratic.
-
-    The  following  output  was generated on Portals, where the only socket
-    application running at the time was MWHOD.  It indicates that two sock‐
-    ets  are  current in use, one is listening for connection requests on a
-    STREAM mode socket.  The other is waiting for incoming data on a  DATA‐
-    GRAM mode socket.
-
-    Fd    State      Mode      Local Address      Remote Address
-    --  ---------  --------  -----------------  ------------------
-    13   LISTEN     STREAM   *.6889             *.*
-    14    BOUND    DATAGRAM  *.6888             *.*
-    -1    CLOSED      MUD    *.*                *.*
-
-### SEE ALSO
-
-    debug_info(3), dump_file_descriptors(3)
-

docs/efun/internals/index.md

@@ -8,21 +8,18 @@ title: internals
 * [debugmalloc](debugmalloc)
 * [dump_file_descriptors](dump_file_descriptors)
 * [dump_prog](dump_prog)
-* [dump_socket_status](dump_socket_status)
 * [dumpallobj](dumpallobj)
 * [get_config](get_config)
 * [malloc_status](malloc_status)
 * [memory_info](memory_info)
 * [moncontrol](moncontrol)
 * [mud_status](mud_status)
-* [opcprof](opcprof)
 * [query_load_average](query_load_average)
 * [refs](refs)
 * [rusage](rusage)
 * [set_config](set_config)
 * [set_debug_level](set_debug_level)
 * [set_malloc_mask](set_malloc_mask)
-* [swap](swap)
 * [time_expression](time_expression)
 * [trace](trace)
 * [traceprefix](traceprefix)

docs/efun/internals/malloc_status.md

@@ -10,7 +10,7 @@ title: internals / malloc_status
 
 ### SYNOPSIS
 
-    void malloc_status( void );
+    string malloc_status();
 
 ### DESCRIPTION
 

docs/efun/internals/mud_status.md

@@ -10,7 +10,7 @@ title: internals / mud_status
 
 ### SYNOPSIS
 
-    void mud_status( int extra );
+    string mud_status( int extra );
 
 ### DESCRIPTION
 

docs/efun/internals/opcprof.md

@@ -1,25 +0,0 @@
----
-layout: doc
-title: internals / opcprof
----
-# opcprof
-
-### NAME
-
-    opcprof() - reports statistics on calling frequencies of various efuns
-
-### SYNOPSIS
-
-    void opcprof( string | void );
-
-### DESCRIPTION
-
-    This  function dumps a list of statistics on each efunction and eopera‐
-    tor.  If no argument is specified, then the information will be  dumped
-    to  files  named  /OPCPROF.efun  and /OPCPROF.eoper.  If an argument is
-    specified, then that name is used as the filename for the dump.
-
-### SEE ALSO
-
-    function_profile(3)
-

docs/efun/internals/swap.md

@@ -1,23 +0,0 @@
----
-layout: doc
-title: internals / swap
----
-# swap
-
-### NAME
-
-    swap - swap out a file explicitly
-
-### SYNOPSIS
-
-    void swap( object );
-
-### DESCRIPTION
-
-    This  efun  should be reserved for debugging only.  It allows an object
-    to be explicitly swapped out.  If enabled, it is  strongly  recommended
-    that a simul_efun override (for this efun) be used to prevent abuse.
-
-    Note:  objects which have been destructed, already swapped out, contain
-    a heart beat, cloned, inherited, or interactive, cannot be swapped out.
-

docs/efun/objects/save_object.md

@@ -11,6 +11,7 @@ title: objects / save_object
 ### SYNOPSIS
 
     int save_object( string name, int flag );
+    string save_object( int flag );
 
 ### DESCRIPTION
 
@@ -21,9 +22,15 @@ title: objects / save_object
     aren't).   Object  variables always save as 0.  If bit 1 is 1, then the
     save file will be compressed.
 
+    If no file name is given (the argument is omitted or is the integer
+    flag bitfield), the serialized data is not written to disk but is
+    returned as a string instead, suitable for use with the string form of
+    restore_object().
+
 ### RETURN VALUE
 
-    save_object() returns 1 for success, 0 for failure.
+    With a file name, save_object() returns 1 for success, 0 for failure.
+    In the no-file-name form it returns the save data as a string.
 
 ### SEE ALSO
 

docs/efun/objects/set_heart_beat.md

@@ -10,7 +10,7 @@ title: objects / set_heart_beat
 
 ### SYNOPSIS
 
-    int set_heart_beat( int flag );
+    void set_heart_beat( int flag );
 
 ### DESCRIPTION
 

docs/efun/strings/implode.md

@@ -11,14 +11,26 @@ title: strings / implode
 ### SYNOPSIS
 
     string implode( mixed *arr, string del );
+    mixed implode( mixed *arr, function f, void | mixed extra );
 
 ### DESCRIPTION
 
-    Concatenate  all  strings  found  in array 'arr', with the string 'del'
-    between each element. Only strings are used from the  array.   elements
-    that are not strings are ignored.
+    In the first form, concatenate all strings found in array 'arr', with
+    the  string  'del' between each element. Only strings are used from the
+    array; elements that are not strings are ignored.
+
+    In the second form, when the second argument is a function, implode()
+    instead  reduces  the  array: it combines the elements left to right by
+    repeatedly  calling  'f'  with the running result and the next element
+    (a fold), and returns whatever the final call returns. The optional
+    'extra' argument, when present, is used as the starting value.
+
+### RETURN VALUE
+
+    The joined string for the delimiter form, or the accumulated value
+    (any type) for the function form.
 
 ### SEE ALSO
 
-    explode(3), sprintf(3)
+    explode(3), sprintf(3), filter(3), map(3)
 

docs/efun/system/errorp.md

@@ -1,31 +0,0 @@
----
-layout: doc
-title: system / errorp
----
-# errorp
-
-### NAME
-
-    errorp() - determine whether or not a given variable is an error code
-
-### SYNOPSIS
-
-    int errorp( mixed arg );
-
-### DESCRIPTION
-
-    Returns 1 if 'arg' is an integer that is an error code.
-
-    Eventually  efuns  will  be  modified to return standard error codes so
-    that code like this will be possible:
-
-        if (errorp(result = efun_call()))
-            printf("error = %d\n", result);
-
-    In future, there will also be a perror(result)  efun  to  return  error
-    string that goes with a particular error integer.
-
-### SEE ALSO
-
-    nullp(3), undefinedp(3)
-

docs/efun/system/flush_messages.md

@@ -10,8 +10,8 @@ title: system / flush_messages
 
 ### SYNOPSIS
 
-    int flush_messages();
-    int flush_messages(object user);
+    void flush_messages();
+    void flush_messages(object user);
 
 ### DESCRIPTION
 

docs/efun/system/function_profile.md

@@ -10,7 +10,7 @@ title: system / function_profile
 
 ### SYNOPSIS
 
-    mixed *function_profile( object ob );
+    mapping *function_profile( object ob );
 
 ### DESCRIPTION
 

docs/efun/system/index.md

@@ -7,7 +7,6 @@ title: system
 * [ctime](ctime)
 * [deep_inherit_list](deep_inherit_list)
 * [error](error)
-* [errorp](errorp)
 * [eval_cost](eval_cost)
 * [find_call_out](find_call_out)
 * [flush_messages](flush_messages)

docs/efun/system/set_eval_limit.md

@@ -10,7 +10,7 @@ title: system / set_eval_limit
 
 ### SYNOPSIS
 
-    void set_eval_limit( int );
+    int set_eval_limit( int );
 
 ### DESCRIPTION