diff options
author | Luke T. Shumaker <lukeshu@lukeshu.com> | 2025-02-23 10:58:41 -0700 |
---|---|---|
committer | Luke T. Shumaker <lukeshu@lukeshu.com> | 2025-02-23 10:58:41 -0700 |
commit | 53723a43e50863968bb040f5ad4f2f9005bac041 (patch) | |
tree | 7ffd6ab41a2ecf7754d3db0eded4c31257613a48 /lib9p | |
parent | 19a41387633e53d64d8a0ae69f3d3d3e35641c8d (diff) | |
parent | c2f977be6492fd93b359c97dee9b2968fe56fef6 (diff) |
Merge branch 'lukeshu/docs'
Diffstat (limited to 'lib9p')
-rw-r--r-- | lib9p/CMakeLists.txt | 2 | ||||
-rw-r--r-- | lib9p/include/lib9p/9p.h | 41 | ||||
-rw-r--r-- | lib9p/internal.h | 2 | ||||
-rwxr-xr-x | lib9p/tests/runtest | 24 | ||||
-rw-r--r-- | lib9p/tests/test_server/main.c | 46 | ||||
-rw-r--r-- | lib9p/tests/test_server/static/Documentation/x | 6 | ||||
-rw-r--r-- | lib9p/tests/test_server/static/README.md | 6 |
7 files changed, 73 insertions, 54 deletions
diff --git a/lib9p/CMakeLists.txt b/lib9p/CMakeLists.txt index 2f5fc70..b356288 100644 --- a/lib9p/CMakeLists.txt +++ b/lib9p/CMakeLists.txt @@ -1,4 +1,4 @@ -# lib9p/CMakeLists.txt - TODO +# lib9p/CMakeLists.txt - A 9P protocol and server library # # Copyright (C) 2024-2025 Luke T. Shumaker <lukeshu@lukeshu.com> # SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib9p/include/lib9p/9p.h b/lib9p/include/lib9p/9p.h index f743afb..7724fc8 100644 --- a/lib9p/include/lib9p/9p.h +++ b/lib9p/include/lib9p/9p.h @@ -63,7 +63,7 @@ int lib9p_errorf(struct lib9p_ctx *ctx, uint32_t linux_errno, char const *fmt, . /* main T-message functions ***************************************************/ /** - * Validate a message's structure; it's size, string encodings, enums, + * Validate a message's structure; its size, string encodings, enums, * and bitfields. * * Return how much space the message will take when unmarshaled. This @@ -91,13 +91,10 @@ ssize_t lib9p_Tmsg_validate(struct lib9p_ctx *ctx, uint8_t *net_bytes); /** * Unmarshal the 9P message `net_bytes` into the C struct `ret_body`. * - * Emits an error (return 0, set ctx->err_num and ctx->err_msg) if a - * string contains invalid UTF-8 or a nul-byte. - * - * lib9p_unmarshal does no validation; you must run + * lib9p_Tmsg_unmarshal does no validation; you must run * lib9p_Tmsg_validate() first. * - * @param ctx : negotiated protocol parameters, where to record errors + * @param ctx : negotiated protocol parameters * @param net_bytes : the complete message, starting with the "size[4]" * * @return ret_typ : the mesage type @@ -152,17 +149,27 @@ static inline void lib9p_stat_assert(struct lib9p_stat stat) { } /** - * TODO + * Validate a message's `stat` structure. + * + * @param ctx : negotiated protocol parameters, where to record errors + * @param net_bytes : network-encoded stat structure + * @param net_size : the number of net_bytes that may be read * - * @return ret_net_size: number of bytes consumed; <=net_size - * @return ret_host_size: number of bytes that lib9p_stat_unmarshal would take + * @return ret_net_size : number of bytes consumed; <=net_size + * @return ret_host_size : number of bytes that lib9p_stat_unmarshal would take * @return whether there was an error */ bool lib9p_stat_validate(struct lib9p_ctx *ctx, uint32_t net_size, uint8_t *net_bytes, uint32_t *ret_net_size, ssize_t *ret_host_size); /** - * TODO + * Unmarshal the 9P `net_bytes` into the C struct `ret_obj`. + * + * lib9p_stat_unmarshal does no validation; you must run + * lib9p_stat_validate() first. + * + * @param ctx : negotiated protocol parameters + * @param net_bytes : network-encoded stat structure * * @return ret_obj : where to put the stat object itself * @return ret_extra : where to put strings for the stat object @@ -172,8 +179,22 @@ uint32_t lib9p_stat_unmarshal(struct lib9p_ctx *ctx, uint8_t *net_bytes, struct lib9p_stat *ret_obj, void *ret_extra); /** + * Marhsal a `struct lib9p_stat` structure into a byte-array. + * + * lib9p_Tmsg_marshal does no validation; it trusts that the + * programmer won't give it garbage input. However, just as it + * doesn't marshal struct fields that aren't in ctx->version, it won't + * marshal bitfield bits that aren't in ctx->version; it applies a + * version-specific mask to bitfields. + * + * @param ctx : negotiated protocol parameters, where to record errors + * @param max_net_size : the maximum network-encoded size to allow + * @param obj : the message to encode + * * @return ret_bytes: the buffer to encode into * @return the number of bytes written, or 0 if the stat object does not fit in max_net_size + * + * @errno LINUX_ERANGE: reply does not fit in max_net_size */ uint32_t lib9p_stat_marshal(struct lib9p_ctx *ctx, uint32_t max_net_size, struct lib9p_stat *obj, uint8_t *ret_bytes); diff --git a/lib9p/internal.h b/lib9p/internal.h index 1f4975f..801dc4c 100644 --- a/lib9p/internal.h +++ b/lib9p/internal.h @@ -1,4 +1,4 @@ -/* lib9p/internal.h - TODO +/* lib9p/internal.h - Internal machinery shared between parts of lib9p * * Copyright (C) 2024-2025 Luke T. Shumaker <lukeshu@lukeshu.com> * SPDX-License-Identifier: AGPL-3.0-or-later diff --git a/lib9p/tests/runtest b/lib9p/tests/runtest index 0966000..c2f6c41 100755 --- a/lib9p/tests/runtest +++ b/lib9p/tests/runtest @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# lib9p/tests/runtest - TODO +# lib9p/tests/runtest - Simple tests for the 9P `test_server` # # Copyright (C) 2025 Luke T. Shumaker <lukeshu@lukeshu.com> # SPDX-License-Identifier: AGPL-3.0-or-later @@ -25,25 +25,37 @@ while [[ -d /proc/$server_pid && "$(readlink /proc/$server_pid/fd/4 2>/dev/null) out=$("${client[@]}" ls -l '') expect_lines \ - 'd-r-xr-xr-x M 0 root root 0 Oct 7 15:51 Documentation' \ - '--r--r--r-- M 0 root root 14 Oct 7 15:51 README.md' \ - '---w--w--w- M 0 root root 0 Oct 7 15:51 shutdown' + 'd-r-xr-xr-x M 0 root root 0 Oct 7 15:51 Documentation' \ + '--r--r--r-- M 0 root root 166 Oct 7 15:51 README.md' \ + '---w--w--w- M 0 root root 0 Oct 7 15:51 shutdown' out=$("${client[@]}" ls -l 'Documentation/') expect_lines \ - '--r--r--r-- M 0 root root 4 Oct 7 15:51 x' + '--r--r--r-- M 0 root root 162 Oct 7 15:51 x' out=$("${client[@]}" read 'README.md') expect_lines \ + '<!--' \ + ' README.md - test static file' \ + '' \ + ' Copyright (C) 2024-2025 Luke T. Shumaker <lukeshu@lukeshu.com>' \ + ' SPDX-License-Identifier: AGPL-3.0-or-later' \ + '-->' \ 'Hello, world!' out=$("${client[@]}" read 'Documentation/x') expect_lines \ + '<!--' \ + ' Documentation/x - test static file' \ + '' \ + ' Copyright (C) 2024-2025 Luke T. Shumaker <lukeshu@lukeshu.com>' \ + ' SPDX-License-Identifier: AGPL-3.0-or-later' \ + '-->' \ 'foo' out=$("${client[@]}" stat 'Documentation/x') expect_lines \ - "'x' 'root' 'root' 'root' q (0000000000000001 1 ) m 0444 at 1728337905 mt 1728337904 l 4 t 0 d 0" + "'x' 'root' 'root' 'root' q (0000000000000001 1 ) m 0444 at 1728337905 mt 1728337904 l 162 t 0 d 0" out=$("${client[@]}" write 'shutdown' <<<1) expect_lines '' diff --git a/lib9p/tests/test_server/main.c b/lib9p/tests/test_server/main.c index 2c64cd4..c60dd71 100644 --- a/lib9p/tests/test_server/main.c +++ b/lib9p/tests/test_server/main.c @@ -73,8 +73,8 @@ static struct lib9p_stat api_stat(struct api_file *self, struct lib9p_srv_ctx *c .kern_dev = 0, .file_qid = api_qid(self), .file_mode = 0222, - .file_atime = 1728337905, - .file_mtime = 1728337904, + .file_atime = UTIL9P_ATIME, + .file_mtime = UTIL9P_MTIME, .file_size = 0, .file_name = lib9p_str("shutdown"), .file_owner_uid = lib9p_str("root"), @@ -113,45 +113,19 @@ static uint32_t api_pread(struct api_file *, struct lib9p_srv_ctx *, void *, uin assert_notreached("not readable"); } -/* file tree ******************************************************************/ +#define lo_box_api_as_lib9p_srv_file(obj) util9p_box(api, obj) -#define _box(nam, obj) \ - ((struct lib9p_srv_file){ \ - .self = obj, \ - .vtable = (void*)&_lo_##nam##_lib9p_srv_file_vtable, \ - }) -#define lo_box_util9p_static_file_as_lib9p_srv_file(obj) _box(util9p_static_file, obj) -#define lo_box_util9p_static_dir_as_lib9p_srv_file(obj) _box(util9p_static_dir, obj) -#define lo_box_api_as_lib9p_srv_file(obj) _box(api, obj) +/* file tree ******************************************************************/ enum { PATH_BASE = __COUNTER__ }; #define PATH_COUNTER __COUNTER__ - PATH_BASE -#define STATIC_COMMON(STRNAME, MODE) \ - { \ - .u_name = "root", .u_num = 0, /* owner user */ \ - .g_name = "root", .g_num = 0, /* owner group */ \ - .m_name = "root", .m_num = 0, /* last-modified-by user */ \ - \ - .pathnum = PATH_COUNTER, \ - .name = STRNAME, \ - .perm = MODE, \ - .atime = 1728337905, \ - .mtime = 1728337904, \ - } - -#define STATIC_FILE(STRNAME, SYMNAME) \ - lo_box_util9p_static_file_as_lib9p_srv_file(&((struct util9p_static_file){ \ - ._util9p_static_common = STATIC_COMMON(STRNAME, 0444), \ - .data_start = _binary_static_##SYMNAME##_start, \ - .data_end = _binary_static_##SYMNAME##_end, \ - })) - -#define STATIC_DIR(STRNAME, ...) \ - lo_box_util9p_static_dir_as_lib9p_srv_file(&((struct util9p_static_dir){ \ - ._util9p_static_common = STATIC_COMMON(STRNAME, 0555), \ - .members = { __VA_ARGS__ LO_NULL(lib9p_srv_file) }, \ - })) +#define STATIC_FILE(STRNAME, SYMNAME) \ + UTIL9P_STATIC_FILE(PATH_COUNTER, STRNAME, \ + .data_start = _binary_static_##SYMNAME##_start, \ + .data_end = _binary_static_##SYMNAME##_end) +#define STATIC_DIR(STRNAME, ...) \ + UTIL9P_STATIC_DIR(PATH_COUNTER, STRNAME, __VA_ARGS__) struct lib9p_srv_file root = STATIC_DIR("", diff --git a/lib9p/tests/test_server/static/Documentation/x b/lib9p/tests/test_server/static/Documentation/x index 257cc56..b9b08d4 100644 --- a/lib9p/tests/test_server/static/Documentation/x +++ b/lib9p/tests/test_server/static/Documentation/x @@ -1 +1,7 @@ +<!-- + Documentation/x - test static file + + Copyright (C) 2024-2025 Luke T. Shumaker <lukeshu@lukeshu.com> + SPDX-License-Identifier: AGPL-3.0-or-later +--> foo diff --git a/lib9p/tests/test_server/static/README.md b/lib9p/tests/test_server/static/README.md index af5626b..c2d88ed 100644 --- a/lib9p/tests/test_server/static/README.md +++ b/lib9p/tests/test_server/static/README.md @@ -1 +1,7 @@ +<!-- + README.md - test static file + + Copyright (C) 2024-2025 Luke T. Shumaker <lukeshu@lukeshu.com> + SPDX-License-Identifier: AGPL-3.0-or-later +--> Hello, world! |