summaryrefslogtreecommitdiff
path: root/lib9p
diff options
context:
space:
mode:
authorLuke T. Shumaker <lukeshu@lukeshu.com>2025-02-23 10:58:41 -0700
committerLuke T. Shumaker <lukeshu@lukeshu.com>2025-02-23 10:58:41 -0700
commit53723a43e50863968bb040f5ad4f2f9005bac041 (patch)
tree7ffd6ab41a2ecf7754d3db0eded4c31257613a48 /lib9p
parent19a41387633e53d64d8a0ae69f3d3d3e35641c8d (diff)
parentc2f977be6492fd93b359c97dee9b2968fe56fef6 (diff)
Merge branch 'lukeshu/docs'
Diffstat (limited to 'lib9p')
-rw-r--r--lib9p/CMakeLists.txt2
-rw-r--r--lib9p/include/lib9p/9p.h41
-rw-r--r--lib9p/internal.h2
-rwxr-xr-xlib9p/tests/runtest24
-rw-r--r--lib9p/tests/test_server/main.c46
-rw-r--r--lib9p/tests/test_server/static/Documentation/x6
-rw-r--r--lib9p/tests/test_server/static/README.md6
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!