ShadowMountPlus/docs/socket-api.md

ShadowMount socket API v1

ShadowMount exposes a public Unix stream socket at /system_tmp/shadowmount-api.sock. The internal /system_tmp/shadowmount.sock endpoint is reserved for the SceShellCore bridge and must not be used by third-party applications.

The ABI is defined in include/sm_api_protocol.h. All integers use the native PS5 little-endian byte order. A client opens one connection, writes exactly one 64-byte sm_api_request_t, reads one 32-byte sm_api_response_t followed by the advertised payload, and closes the connection.

Validate magic, version, operation, size, item_count, and item_size before consuming a response. status is zero on success or a positive errno value. Strings are NUL-terminated fixed-size byte arrays.

Operations

• SM_API_GET_VERSION returns one sm_api_version_info_t.
• SM_API_LIST_IMAGES returns sm_api_image_info_t entries. offset is the zero-based entry offset; limit is clamped to 16 and zero means 16.
• SM_API_LIST_GAMES uses the same pagination and returns sm_api_game_info_t entries.
• SM_API_MOUNT_GAME mounts the managed runtime stack identified by title_id.
• SM_API_UNMOUNT_GAME releases that runtime stack and its backing image chain.

List responses contain the full current count in total_count and the current page size in item_count. Continue with offset += item_count until the offset reaches total_count.

Mount mutations are deliberately conservative. They return EBUSY while a game is active, while ShellCore owns another prepared title, during suspend, or while a conflicting mount/release is in progress. ENOENT means the title does not have a ShadowMount mount.lnk tracker. Clients should not retry EBUSY in a tight loop.

The socket is created only after startup synchronization completes and is removed before shutdown mount cleanup begins.

Test payload

Build api-test.elf and run it while ShadowMount is active. It validates the version response, walks every image and game page, then selects the first managed game that is not already mounted and performs a mount/unmount cycle. The mutation test is skipped when no safe candidate exists or the runtime is busy; an existing mounted game is never selected.

Clients should call SM_API_GET_VERSION first and check its capability bits. Unknown operations return ENOTSUP, malformed requests return EPROTO, and a future incompatible structure layout will increment SM_API_VERSION.