From 4fd7c4b9312afb8e40fbe04e61bc1ef8bf49bed7 Mon Sep 17 00:00:00 2001
From: Dan Gohman <sunfish@mozilla.com>
Date: Thu, 28 Mar 2019 10:42:48 -0700
Subject: [PATCH] Document the constraints on `path_open`'s returned file
 descriptor.

Whether the downsides in POSIX and existing application compatibility
outweigh the benefits of thread safety remains an open question.
Right now, this note is just documenting the current behavior.
---
 docs/WASI-api.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/WASI-api.md b/docs/WASI-api.md
index f40899af15..a89cb963d6 100644
--- a/docs/WASI-api.md
+++ b/docs/WASI-api.md
@@ -744,6 +744,12 @@ Inputs:
 
 Open a file or directory.
 
+The returned file descriptor is not guaranteed to be the lowest-numbered
+file descriptor not currently open; it is randomized to prevent
+applications from depending on making assumptions about indexes, since
+this is error-prone in multi-threaded contexts. The returned file
+descriptor is guaranteed to be less than 2<sup>31</sup>.
+
 Note: This is similar to `openat` in POSIX.
 
 Inputs: