C 插件系统实战指南：dlopen 没告诉你的四件事

void *h = dlopen(path, RTLD_LAZY);
void (*init)() = dlsym(h, "plugin_init");
init();

#include <dlfcn.h>

void *dlopen (const char *file, int mode);
void *dlsym  (void *handle, const char *name);
int   dlclose(void *handle);
char *dlerror(void);                       /* 唯一错误通道，读一次就清空 */

int   dladdr(const void *addr, Dl_info *info);      /* 地址 → 哪个 .so、哪个符号 */
void *dlvsym(void *h, char *sym, char *ver);        /* 按符号版本查，glibc only */

/* 插件 */
__attribute__((visibility("default")))
int plugin_init(const host_api_t *host) { ... }

/* 宿主 */
int (*init)(const host_api_t *) =
    (int(*)(const host_api_t*))(intptr_t)dlsym(h, "plugin_init");

$ nm -gU /opt/homebrew/opt/openssl@3/lib/ossl-modules/legacy.dylib | grep provider_init
0000000000001564 T _OSSL_provider_init

$ nm -gU /usr/lib/pam/pam_permit.so.2
0000000000000300 T _pam_sm_acct_mgmt
00000000000002f0 T _pam_sm_authenticate
0000000000000318 T _pam_sm_chauthtok
0000000000000310 T _pam_sm_close_session
0000000000000308 T _pam_sm_open_session
00000000000002f8 T _pam_sm_setcred

typedef struct plugin_desc {
    int         abi_version;      /* ← 必须是第一个字段 */
    size_t      size;             /* ← 细粒度兼容 */
    const char *name;
    int       (*init)(const host_api_t *host, pool_t *pool, registry_t *reg);
    void      (*fini)(void);
    unsigned    flags;
    void       *reserved[8];      /* ← 留白 */
} plugin_desc_t;

__attribute__((visibility("default")))
plugin_desc_t plugin_descriptor = { PLUGIN_ABI, sizeof(plugin_desc_t), ... };

static void hello(void) { ... }
__attribute__((constructor)) static void selfreg(void) {
    host_register("hello", hello);
}

=== dlopen("./p_ctor.so") ===
    [host_register] 'p_ctor:hello' 注册进来了（此刻还在 dlopen 里）
  dlopen 返回 0x74d9f2d0（注意上面 host_register 的输出出现在这一行之前）

snprintf(sym, sizeof sym, "%s_plugin", basename_without_ext);

$ nm -gU .../lib-dynload/_socket.cpython-313-darwin.so
0000000000000a28 T _PyInit__socket

#define REGISTER(x) static void *__reg_##x \
    __attribute__((used, section("myregs"))) = &x;

$ nm -u p_a.so | grep host
_host_report

$ nm -gU host | grep -E "host_report|host_register"
0000000100000588 T _host_register
0000000100000548 T _host_report

typedef struct host_api {
    int    abi;
    size_t size;                                  /* 让插件能判断字段有没有 */
    void (*log)(const char *lvl, const char *fmt, ...);
    void*(*palloc)(pool_t *pool, size_t n);
    int  (*declare_cmd)(registry_t *reg, const char *name, ...);
    void *reserved[8];
} host_api_t;

if (d->abi != MP_ABI) {
    log("插件 abi=%d，宿主要求 %d，请重新编译插件", d->abi, MP_ABI);
    return -1;
}

typedef struct switch_io_routines {
    switch_io_outgoing_channel_t outgoing_channel;
    /* ...14 个方法... */
    void *padding[10];        /* ← FreeSWITCH 真这么写的 */
} switch_io_routines_t;

typedef struct host_api { int abi; size_t size; /* ... */ } host_api_t;

/* 插件侧：判断这个字段存不存在 */
if (host->size >= offsetof(host_api_t, new_fn) + sizeof(void*) && host->new_fn) {
    host->new_fn(...);
}

=== 普通 dlclose ===
卸载前 name = 'p_b'
dlclose ... done
dladdr: 地址已经不属于任何映像了 —— 读它就是 use-after-unmap
尝试读取 saved_name ... (exit=139)          ← SIGSEGV

=== RTLD_NODELETE ===
卸载前 name = 'p_b'
dlclose ... done
尝试读取 saved_name ... 'p_b'
(exit=0)

    [plugin] 起了一个 detached 线程，代码位于本 .so
  dlclose（线程还在跑）...
  dlclose 返回了，睡 300ms 看线程还能不能活
(exit=139  139=SIGSEGV)

=== dlclose 之后退出 ===
    [plugin] init: 注册 atexit(my_cleanup)
  dlclose ...
    [plugin] atexit 回调跑了（代码可能已被 unmap）      ← 在 dlclose 期间就跑了
  main return，接下来 libc 会跑 atexit 链
(exit=0)

#define PROTECT_INTERFACE(_it) if (_it) { \
    switch_thread_rwlock_rdlock(_it->parent->rwlock);   /* 模块级 */ \
    switch_thread_rwlock_rdlock(_it->rwlock);           /* 接口级 */ \
    switch_mutex_lock(_it->reflock); \
    _it->refs++; _it->parent->refs++; \
    switch_mutex_unlock(_it->reflock); }

dlopen(path, RTLD_NOW | RTLD_LOCAL);     /* 插件系统的默认答案 */

--- RTLD_NOW ---
dlopen("./p_bad.so", RTLD_NOW) ... 失败
  dlopen(./p_bad.so, 0x0006): symbol not found in flat namespace
                              '_this_symbol_does_not_exist_anywhere'

--- RTLD_LAZY ---
dlopen("./p_bad.so", RTLD_LAZY) ... 成功 (0x74d9ca40)
  dlsym 成功 = 0x104994008，此时还没崩
  现在调用那个引用了不存在符号的 init() ...
(exit=139)                                       ← SIGSEGV

=== flat namespace + RTLD_LOCAL ===
    g1_entry 调用 shared_helper:
      -> g1 的 shared_helper
    g2_entry 调用 shared_helper:
      -> g2 的 shared_helper          ← 各调自己的，正常

=== flat namespace + RTLD_GLOBAL ===
    g1_entry 调用 shared_helper:
      -> g1 的 shared_helper
    g2_entry 调用 shared_helper:
      -> g1 的 shared_helper          ← 劫持！g2 调到了 g1 的实现

$ otool -hv c2.so | tail -1
... NOUNDEFS DYLDLINK TWOLEVEL NO_REEXPORTED_DYLIBS
$ nm -u c2.so
_printf
dyld_stub_binder          ← shared_helper 根本不在未定义符号表里

# 插件
cc -shared -fPIC -fvisibility=hidden -o p.so p.c                             # Linux
cc -shared -fPIC -fvisibility=hidden -undefined dynamic_lookup -o p.so p.c   # macOS

# 宿主
cc -rdynamic -o host host.c -ldl                                             # Linux
cc -o host host.c                                                            # macOS

#ifndef PLUGIN_API_H
#define PLUGIN_API_H
#include <stddef.h>

#define MP_ABI 1                 /* 粗粒度守门：结构体不兼容变更时 +1 */

/* ---------- 宿主提供给插件的能力（vtable 注入） ---------- */
typedef struct mp_pool     mp_pool_t;      /* 不透明：生命周期容器 */
typedef struct mp_registry mp_registry_t;  /* 不透明：注册暂存区 */

typedef int (*mp_cmd_fn)(void *ctx, const char *arg, char *out, size_t outlen);

typedef struct mp_host {
    int    abi;
    size_t size;                                     /* 细粒度兼容：调用方判 size */
    void (*log)(const char *lvl, const char *fmt, ...);
    void*(*palloc)(mp_pool_t *pool, size_t n);       /* 只从注入的 pool 分配 */
    char*(*pstrdup)(mp_pool_t *pool, const char *s);
    /* 申报能力：只写暂存区，不进全局表 */
    int  (*declare_cmd)(mp_registry_t *reg, const char *name,
                        const char *desc, mp_cmd_fn fn, void *ctx);
    void *reserved[8];
} mp_host_t;

/* ---------- 插件暴露给宿主的描述符（Pattern B 的数据符号） ---------- */
typedef struct mp_plugin {
    int         abi;             /* ← 必须是第一个字段 */
    size_t      size;
    const char *name;
    const char *version;
    int       (*init)(const mp_host_t *host, mp_pool_t *pool, mp_registry_t *reg);
    void      (*fini)(void);
    unsigned    flags;
    void       *reserved[8];     /* ← 给未来留白，加字段不破 ABI */
} mp_plugin_t;

#define MP_FLAG_NONE           0u
#define MP_FLAG_GLOBAL_SYMBOLS 1u   /* 需要 RTLD_GLOBAL（脚本语言插件） */
#define MP_FLAG_NO_UNLOAD      2u   /* 声明自己不可卸载 */

/* Pattern B + D：符号名 = <文件名>_plugin，宿主按文件名推导 */
#define MP_PLUGIN_DEFINE(modname, ver, initfn, finifn, fl)          \
    __attribute__((visibility("default")))                          \
    mp_plugin_t modname##_plugin = {                                \
        MP_ABI, sizeof(mp_plugin_t), #modname, ver,                 \
        initfn, finifn, fl, {0}                                     \
    }
#endif

int mp_load(const char *path){
    char key[128], sym[160];
    basename_noext(path, key, sizeof key);
    snprintf(sym, sizeof sym, "%s_plugin", key);        /* Pattern D */

    for (module_t *m = R.modules; m; m = m->next)
        if (!strcmp(m->key, key)) { log("模块已加载"); return -1; }

    /* ① 先在宿主自身找（支持静态编入），找不到再 dlopen */
    void *dso = dlopen(NULL, RTLD_NOW | RTLD_LOCAL);
    dlerror();                                          /* 先清空错误 */
    mp_plugin_t *d = (mp_plugin_t *)dlsym(dso, sym);
    int from_self = (d != NULL);
    if (!d) {
        if (dso) dlclose(dso);
        dso = dlopen(path, RTLD_NOW | RTLD_LOCAL);      /* ② NOW + LOCAL */
        if (!dso) { log("dlopen: %s", dlerror()); return -1; }
        dlerror();
        d = (mp_plugin_t *)dlsym(dso, sym);
        char *e = dlerror();                            /* ③ 用 dlerror 判错，不看返回值 */
        if (!d) { log("dlsym: %s", e ? e : "not found"); dlclose(dso); return -1; }
    }

    /* ④ 门禁：abi → size → 必填字段，全部在调用任何插件代码之前 */
    if (d->abi != MP_ABI) {
        log("ABI 不匹配: 插件 %d, 宿主 %d —— 请重新编译插件", d->abi, MP_ABI);
        dlclose(dso); return -1;
    }
    if (d->size < offsetof(mp_plugin_t, flags)) { log("描述符被截断"); ... }
    if (!d->init) { log("缺 init"); ... }

    /* ⑤ 需要 RTLD_GLOBAL？重开一次（flags 在 .so 里，不读进来不知道） */
    if ((d->flags & MP_FLAG_GLOBAL_SYMBOLS) && !from_self) {
        dlclose(dso);
        dso = dlopen(path, RTLD_NOW | RTLD_GLOBAL);
        d = (mp_plugin_t *)dlsym(dso, sym);
    }

    module_t *m = calloc(1, sizeof(*m));
    m->key = strdup(key); m->dso = dso; m->desc = d;
    m->pool = pool_create();                    /* ⑥ pool 生命周期 = 模块生命周期 */
    m->staging.owner = m;

    /* ⑦ 阶段 1：插件申报（只写暂存区，不进全局表） */
    if (d->init(&HOST, m->pool, &m->staging) != 0) { /* 清理并返回 */ }

    /* ⑧ 阶段 2：宿主发布（门禁、冲突检查、审计都在这一步） */
    publish(m);
    m->next = R.modules; R.modules = m;
    return 0;
}

static int publish(module_t *m){
    pthread_mutex_lock(&R.lock);
    for (cmd_entry_t *e = m->staging.head; e; e = e->next_in_module) {
        /* 门禁：allowlist */
        if (!permitted(m->key, e->name)) {
            printf("    [SKIP ] '%s' 被 allowlist 拒绝\n", e->name); continue;
        }
        /* 冲突要报错，不静默覆盖 */
        int dup = -1;
        for (int i=0;i<R.n;i++) if (!strcmp(R.tab[i].name, e->name)) { dup = i; break; }
        if (dup >= 0) {
            printf("    [ERROR] 命令 '%s' 已被 %s 注册，%s 的注册被拒绝\n",
                   e->name, R.tab[dup].e->owner->key, m->key);
            continue;
        }
        R.tab[R.n].name = e->name; R.tab[R.n].e = e; R.n++;
    }
    pthread_mutex_unlock(&R.lock);
}

static int h_declare_cmd(mp_registry_t *reg, const char *name, const char *desc,
                         mp_cmd_fn fn, void *ctx){
    mp_pool_t *pool = reg->owner->pool;
    cmd_entry_t *e = pool_alloc(pool, sizeof(*e));
    e->name = pool_strdup(pool, name);        /* ← 不存 .so 里的指针 */
    e->desc = pool_strdup(pool, desc);
    e->fn = fn; e->ctx = ctx; e->owner = reg->owner;
    e->next_in_module = reg->head; reg->head = e;
    return 0;
}

int mp_exec(const char *name, const char *arg, char *out, size_t outlen){
    cmd_entry_t *e = NULL;
    pthread_mutex_lock(&R.lock);
    for (int i=0;i<R.n;i++) if (!strcmp(R.tab[i].name, name)) { e = R.tab[i].e; break; }
    if (e) e->refs++;                                  /* 防止调用期间被卸载 */
    pthread_mutex_unlock(&R.lock);
    if (!e) { snprintf(out, outlen, "-ERR 未知命令 '%s'", name); return -1; }
    int rc = e->fn(e->ctx, arg, out, outlen);
    pthread_mutex_lock(&R.lock); e->refs--; pthread_mutex_unlock(&R.lock);
    return rc;
}

for (int i=0;i<R.n;i++)
    if (R.tab[i].e == e) {                     /* 比指针，不比名字 */
        R.tab[i] = R.tab[--R.n]; break;
    }

#include "plugin_api.h"
#include <stdio.h>
#include <string.h>
#include <ctype.h>

static const mp_host_t *H;                  /* 保存注入的 host vtable */

static int cmd_hello(void *ctx, const char *arg, char *out, size_t n){
    (void)ctx; snprintf(out, n, "+OK hello, %s!", arg && *arg ? arg : "world"); return 0;
}
static int cmd_upper(void *ctx, const char *arg, char *out, size_t n){
    (void)ctx; size_t i; snprintf(out, n, "+OK ");
    for (i = 0; arg && arg[i] && i + 5 < n; i++)
        out[4+i] = (char)toupper((unsigned char)arg[i]);
    out[4+i] = 0; return 0;
}
static int init(const mp_host_t *host, mp_pool_t *pool, mp_registry_t *reg){
    H = host;
    if (host->abi != MP_ABI) return -1;      /* 双向检查：插件也验宿主 */
    host->log("INFO", "mod_hello: host abi=%d size=%zu", host->abi, host->size);
    host->declare_cmd(reg, "hello", "打个招呼", cmd_hello, NULL);
    host->declare_cmd(reg, "upper", "转大写",   cmd_upper, NULL);
    (void)pool; return 0;
}
static void fini(void){ if (H) H->log("INFO", "mod_hello: fini"); }

MP_PLUGIN_DEFINE(mod_hello, "1.0.0", init, fini, MP_FLAG_NONE);

CFLAGS        = -std=c11 -Wall -Wextra -O2 -I.
PLUGIN_CFLAGS = $(CFLAGS) -fPIC -fvisibility=hidden

UNAME := $(shell uname -s)
ifeq ($(UNAME),Darwin)
  PLUGIN_LDFLAGS = -shared -undefined dynamic_lookup
  HOST_LDFLAGS   =
else
  PLUGIN_LDFLAGS = -shared
  HOST_LDFLAGS   = -rdynamic -ldl        # ← Linux 必须 -rdynamic
endif

PLUGINS = mod_hello.so mod_dup.so mod_old.so
all: host $(PLUGINS)
host: main.c loader.c ; $(CC) $(CFLAGS) -o $@ $^ $(HOST_LDFLAGS) -lpthread
%.so: %.c              ; $(CC) $(PLUGIN_CFLAGS) $(PLUGIN_LDFLAGS) -o $@ $<
clean:                 ; rm -f host $(PLUGINS)

$ make && ./host

>>> load ./mod_hello.so  (查符号 'mod_hello_plugin')
    符号来自 该 .so
    [INFO ] mod_hello: host abi=1 size=112
    plugin 'mod_hello' v1.0.0 申报完成
    [ADD  ] 命令 'upper'  (转大写)
    [ADD  ] 命令 'hello'  (打个招呼)

>>> load ./mod_old.so  (查符号 'mod_old_plugin')
    符号来自 该 .so
    [ERROR] ABI 不匹配: 插件 0, 宿主 1 —— 请重新编译插件

>>> load ./mod_dup.so  (查符号 'mod_dup_plugin')
    plugin 'mod_dup' v0.1 申报完成
    [ADD  ] 命令 'dup'  (我自己的命令)
    [ERROR] 命令 'hello' 已被 mod_hello 注册，mod_dup 的注册被拒绝

>>> load ./mod_hello.so  (查符号 'mod_hello_plugin')
    [ERROR] 模块已加载

=== 注册表（3 条） ===
  upper        转大写                    [mod_hello]
  hello        打个招呼                  [mod_hello]
  dup          我自己的命令              [mod_dup]

=== 派发 ===
  hello    walter    -> +OK hello, walter!
  upper    abi guard -> +OK ABI GUARD
  dup                -> +OK from mod_dup
  nope               -> -ERR 未知命令 'nope'

>>> unload mod_hello
    [DEL  ] 命令 'upper'
    [DEL  ] 命令 'hello'
    [INFO ] mod_hello: fini
    模块 mod_hello 已卸载（dso 保留映射，不 dlclose）

=== 注册表（1 条） ===
  dup          我自己的命令              [mod_dup]

=== 派发（mod_hello 已卸载）===
  hello    walter    -> -ERR 未知命令 'hello'
  dup                -> +OK from mod_dup      ← 别人的命令没被连带删掉

$ for f in mod_hello.so mod_dup.so mod_old.so; do printf "%-14s " $f; nm -gU $f; done
mod_hello.so   0000000000008010 D _mod_hello_plugin
mod_dup.so     0000000000008008 D _mod_dup_plugin
mod_old.so     0000000000004000 D _mod_old_plugin

=== 开启 allowlist：只放行 mod_hello.hello ===

>>> load ./mod_hello.so
    plugin 'mod_hello' v1.0.0 申报完成
    [SKIP ] 'upper' 被 allowlist 拒绝
    [ADD  ] 命令 'hello'  (打个招呼)

>>> load ./mod_dup.so
    plugin 'mod_dup' v0.1 申报完成
    [SKIP ] 'dup' 被 allowlist 拒绝
    [SKIP ] 'hello' 被 allowlist 拒绝

=== 注册表（1 条） ===
  hello        打个招呼                  [mod_hello]

$ nm -gU p_a.so
（空 —— plugin_init 被 -fvisibility=hidden 藏起来了，dlsym 找不到）

$ nm -gU p_a2.so     # 加了 __attribute__((visibility("default")))
0000000000000558 T _plugin_init

nm -D --dynamic host | grep host_report      # Linux：空 = 忘了 -rdynamic

$ c++ -shared -fPIC -o t_mangle.so t_mangle.cpp
$ nm -gU t_mangle.so
0000000000000598 T __Z11plugin_initv          ← 函数：被 mangle 了！
0000000000008008 D _plugin_descriptor         ← 全局命名空间的变量：没有 mangle
0000000000008018 D _plugin_descriptor_ok
00000000000005b8 T _plugin_init_ok

$ nm -gU t_mangle2.so | while read a b c; do printf "%-32s -> %s\n" "$c" "$(echo $c|c++filt)"; done
__ZN6Holder8cls_descE            -> Holder::cls_desc          ← 类静态成员：mangle
__ZN6myplug7ns_descE             -> myplug::ns_desc           ← namespace 里的变量：mangle
_global_desc                     -> _global_desc              ← 全局命名空间变量：不 mangle

=== 坑 1：dlerror() 读一次就清空 ===
  第一次 dlerror(): dlsym(0x74d9ca40, no_such_symbol_1): symbol not found
  第二次 dlerror(): (NULL —— 已经被清空了)

=== 对照：dlsym 返回的是“变量的地址”，不是变量的值 ===
  dlsym 给的地址 = 0x102734008，*地址 = 0x0（变量值确实是 0）

=== dlsym 返回 NULL 的真实合法场景：未解析的弱符号 ===
  &maybe_missing 直接取址 = 0x0
  dlsym(RTLD_DEFAULT,"maybe_missing") = 0x0
  dlerror() = dlsym(RTLD_DEFAULT, maybe_missing): symbol not found

dlerror();                       /* 清掉残留 */
void *p = dlsym(h, name);
char *e = dlerror();             /* 用它判错，不看 p */
if (e) { /* 真的找不到 */ }

宿主和插件都静态链接了 libcounter.a（同一份 static int counter）
    [host]   counter_bump() = 1   (&counter = 0x1046b0000)
    [host]   counter_bump() = 2   (&counter = 0x1046b0000)
    [plugin] counter_bump() = 1   (&counter = 0x1046e0010)   ← 另一个地址！
    [plugin] counter_bump() = 2   (&counter = 0x1046e0010)
    [host]   counter_bump() = 3   (&counter = 0x1046b0000)

nm -gU plugin.so | grep <可疑符号>       # 插件是不是自带了一份？

# 这个 .so 需要谁？（排查 undefined symbol）
nm -u plugin.so | grep -v '^_\?dyld'       # macOS
nm -D --undefined-only plugin.so           # Linux

# 这个 .so 给出什么？（排查 dlsym 找不到、导出面积过大）
nm -gU plugin.so                           # macOS
nm -D --defined-only plugin.so             # Linux
nm -gU plugin.so | c++filt                 # C++ 看 demangle 后的名字

# 宿主到底导出了哪些符号（排查 -rdynamic 漏加）
nm -D --dynamic host | grep ' T '          # Linux

# 依赖链
otool -L plugin.so                         # macOS
ldd plugin.so                              # Linux

# 加载过程发生了什么（最有用的一招）
DYLD_PRINT_LIBRARIES=1 ./host              # macOS
LD_DEBUG=libs,bindings,symbols ./host      # Linux

# 符号被谁劫持了（排查 RTLD_GLOBAL 污染，几乎是唯一手段）
LD_DEBUG=bindings ./host 2>&1 | grep shared_helper    # Linux

# 运行期反查地址属于哪个 .so
# 代码里用 dladdr()，见上面“现场一”的例子