From 2a269512aea19cc7823f7354e9030288269e7e90 Mon Sep 17 00:00:00 2001
From: MaulingMonkey <git@maulingmonkey.com>
Date: Wed, 24 Feb 2021 09:38:47 -0800
Subject: [PATCH] Document `=` and `\0` use in args/environ docs. (#399)

---
 phases/ephemeral/docs.md                          | 4 +++-
 phases/ephemeral/witx/wasi_ephemeral_args.witx    | 3 ++-
 phases/ephemeral/witx/wasi_ephemeral_environ.witx | 1 +
 phases/old/snapshot_0/docs.md                     | 4 +++-
 phases/old/snapshot_0/witx/wasi_unstable.witx     | 4 +++-
 phases/snapshot/docs.md                           | 4 +++-
 phases/snapshot/witx/wasi_snapshot_preview1.witx  | 4 +++-
 7 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/phases/ephemeral/docs.md b/phases/ephemeral/docs.md
index 7fa4c11d..e7a3aa91 100644
--- a/phases/ephemeral/docs.md
+++ b/phases/ephemeral/docs.md
@@ -1211,7 +1211,8 @@ When type is [`preopentype::dir`](#preopentype.dir):
 
 #### <a href="#get" name="get"></a> `get(argv: Pointer<Pointer<u8>>, argv_buf: Pointer<u8>) -> Result<(), errno>`
 Read command-line argument data.
-The size of the array should match that returned by [`sizes_get`](#sizes_get)
+The size of the array should match that returned by [`sizes_get`](#sizes_get).
+Each argument is expected to be `\0` terminated.
 
 ##### Params
 - <a href="#get.argv" name="get.argv"></a> `argv`: `Pointer<Pointer<u8>>`
@@ -1327,6 +1328,7 @@ The time value of the clock.
 #### <a href="#get" name="get"></a> `get(environ: Pointer<Pointer<u8>>, environ_buf: Pointer<u8>) -> Result<(), errno>`
 Read environment variable data.
 The sizes of the buffers should match that returned by [`sizes_get`](#sizes_get).
+Key/value pairs are expected to be joined with `=`s, and terminated with `\0`s.
 
 ##### Params
 - <a href="#get.environ" name="get.environ"></a> `environ`: `Pointer<Pointer<u8>>`
diff --git a/phases/ephemeral/witx/wasi_ephemeral_args.witx b/phases/ephemeral/witx/wasi_ephemeral_args.witx
index b8d77b50..bb956fc5 100644
--- a/phases/ephemeral/witx/wasi_ephemeral_args.witx
+++ b/phases/ephemeral/witx/wasi_ephemeral_args.witx
@@ -10,7 +10,8 @@
   (import "memory" (memory))
 
   ;;; Read command-line argument data.
-  ;;; The size of the array should match that returned by `sizes_get`
+  ;;; The size of the array should match that returned by `sizes_get`.
+  ;;; Each argument is expected to be `\0` terminated.
   (@interface func (export "get")
     (param $argv (@witx pointer (@witx pointer (@witx char8))))
     (param $argv_buf (@witx pointer (@witx char8)))
diff --git a/phases/ephemeral/witx/wasi_ephemeral_environ.witx b/phases/ephemeral/witx/wasi_ephemeral_environ.witx
index 0cad3c1c..ef1c20b2 100644
--- a/phases/ephemeral/witx/wasi_ephemeral_environ.witx
+++ b/phases/ephemeral/witx/wasi_ephemeral_environ.witx
@@ -11,6 +11,7 @@
 
   ;;; Read environment variable data.
   ;;; The sizes of the buffers should match that returned by `sizes_get`.
+  ;;; Key/value pairs are expected to be joined with `=`s, and terminated with `\0`s.
   (@interface func (export "get")
     (param $environ (@witx pointer (@witx pointer (@witx char8))))
     (param $environ_buf (@witx pointer (@witx char8)))
diff --git a/phases/old/snapshot_0/docs.md b/phases/old/snapshot_0/docs.md
index 707c836b..634e304b 100644
--- a/phases/old/snapshot_0/docs.md
+++ b/phases/old/snapshot_0/docs.md
@@ -1270,7 +1270,8 @@ Alignment: 4
 
 #### <a href="#args_get" name="args_get"></a> `args_get(argv: Pointer<Pointer<u8>>, argv_buf: Pointer<u8>) -> Result<(), errno>`
 Read command-line argument data.
-The size of the array should match that returned by [`args_sizes_get`](#args_sizes_get)
+The size of the array should match that returned by [`args_sizes_get`](#args_sizes_get).
+Each argument is expected to be `\0` terminated.
 
 ##### Params
 - <a href="#args_get.argv" name="args_get.argv"></a> `argv`: `Pointer<Pointer<u8>>`
@@ -1325,6 +1326,7 @@ Offset: 4
 #### <a href="#environ_get" name="environ_get"></a> `environ_get(environ: Pointer<Pointer<u8>>, environ_buf: Pointer<u8>) -> Result<(), errno>`
 Read environment variable data.
 The sizes of the buffers should match that returned by [`environ_sizes_get`](#environ_sizes_get).
+Key/value pairs are expected to be joined with `=`s, and terminated with `\0`s.
 
 ##### Params
 - <a href="#environ_get.environ" name="environ_get.environ"></a> `environ`: `Pointer<Pointer<u8>>`
diff --git a/phases/old/snapshot_0/witx/wasi_unstable.witx b/phases/old/snapshot_0/witx/wasi_unstable.witx
index 5481882a..dbece264 100644
--- a/phases/old/snapshot_0/witx/wasi_unstable.witx
+++ b/phases/old/snapshot_0/witx/wasi_unstable.witx
@@ -16,7 +16,8 @@
   (import "memory" (memory))
 
   ;;; Read command-line argument data.
-  ;;; The size of the array should match that returned by `args_sizes_get`
+  ;;; The size of the array should match that returned by `args_sizes_get`.
+  ;;; Each argument is expected to be `\0` terminated.
   (@interface func (export "args_get")
     (param $argv (@witx pointer (@witx pointer u8)))
     (param $argv_buf (@witx pointer u8))
@@ -31,6 +32,7 @@
 
   ;;; Read environment variable data.
   ;;; The sizes of the buffers should match that returned by `environ_sizes_get`.
+  ;;; Key/value pairs are expected to be joined with `=`s, and terminated with `\0`s.
   (@interface func (export "environ_get")
     (param $environ (@witx pointer (@witx pointer u8)))
     (param $environ_buf (@witx pointer u8))
diff --git a/phases/snapshot/docs.md b/phases/snapshot/docs.md
index c55a661b..44c3c35f 100644
--- a/phases/snapshot/docs.md
+++ b/phases/snapshot/docs.md
@@ -1267,7 +1267,8 @@ Alignment: 4
 
 #### <a href="#args_get" name="args_get"></a> `args_get(argv: Pointer<Pointer<u8>>, argv_buf: Pointer<u8>) -> Result<(), errno>`
 Read command-line argument data.
-The size of the array should match that returned by [`args_sizes_get`](#args_sizes_get)
+The size of the array should match that returned by [`args_sizes_get`](#args_sizes_get).
+Each argument is expected to be `\0` terminated.
 
 ##### Params
 - <a href="#args_get.argv" name="args_get.argv"></a> `argv`: `Pointer<Pointer<u8>>`
@@ -1322,6 +1323,7 @@ Offset: 4
 #### <a href="#environ_get" name="environ_get"></a> `environ_get(environ: Pointer<Pointer<u8>>, environ_buf: Pointer<u8>) -> Result<(), errno>`
 Read environment variable data.
 The sizes of the buffers should match that returned by [`environ_sizes_get`](#environ_sizes_get).
+Key/value pairs are expected to be joined with `=`s, and terminated with `\0`s.
 
 ##### Params
 - <a href="#environ_get.environ" name="environ_get.environ"></a> `environ`: `Pointer<Pointer<u8>>`
diff --git a/phases/snapshot/witx/wasi_snapshot_preview1.witx b/phases/snapshot/witx/wasi_snapshot_preview1.witx
index df3c670f..efb2c797 100644
--- a/phases/snapshot/witx/wasi_snapshot_preview1.witx
+++ b/phases/snapshot/witx/wasi_snapshot_preview1.witx
@@ -13,7 +13,8 @@
   (import "memory" (memory))
 
   ;;; Read command-line argument data.
-  ;;; The size of the array should match that returned by `args_sizes_get`
+  ;;; The size of the array should match that returned by `args_sizes_get`.
+  ;;; Each argument is expected to be `\0` terminated.
   (@interface func (export "args_get")
     (param $argv (@witx pointer (@witx pointer u8)))
     (param $argv_buf (@witx pointer u8))
@@ -28,6 +29,7 @@
 
   ;;; Read environment variable data.
   ;;; The sizes of the buffers should match that returned by `environ_sizes_get`.
+  ;;; Key/value pairs are expected to be joined with `=`s, and terminated with `\0`s.
   (@interface func (export "environ_get")
     (param $environ (@witx pointer (@witx pointer u8)))
     (param $environ_buf (@witx pointer u8))