[pthread] Honor guard size in pthread_create

Honor requested/default guard size in pthread_create by reserving
guard_size bytes between thread control data/TSD/TLS and the usable
stack.

Although we cannot set memory protection on this region like a native
platform this can still be useful for catching and reporting overflows
that are smaller than the guard region itself.  Without this change
`-sSTACK_OVERFLOW_CHECK=1` is mostly useless for pthreads because
any kind of overflow is likely to corrupt the stack before being
reported.

Add test cases covering guard size queries via pthread_getattr_np and
stack overflow detection within guard region.

Fixes: #27266

Author: sbc100

system/lib/pthread/pthread_create.c

@@ -130,22 +130,32 @@ int __pthread_create(pthread_t* restrict res,
   if (!attr._a_stacksize) {
     attr._a_stacksize = __default_stacksize;
   }
+  if (!attrp || attrp == __ATTRP_C11_THREAD) {
+    attr._a_guardsize = __default_guardsize;
+  }
+
+  size_t guard_size = 0;
+  if (!attr._a_stackaddr) {
+    guard_size = ROUND_UP(attr._a_guardsize, STACK_ALIGN);
+  }
 
   // Allocate memory for new thread.  The layout of the thread block is
   // as follows.  From low to high address:
   //
   // 1. pthread struct (sizeof struct pthread)
   // 2. tls data       (__builtin_wasm_tls_size())
   // 3. tsd pointers   (__pthread_tsd_size)
-  // 4. stack          (__default_stacksize AKA -sDEFAULT_PTHREAD_STACK_SIZE)
+  // 4. guard area     (guard_size)
+  // 5. stack          (__default_stacksize AKA -sDEFAULT_PTHREAD_STACK_SIZE)
   size_t size = sizeof(struct pthread);
   if (__builtin_wasm_tls_size()) {
     size += __builtin_wasm_tls_size() + __builtin_wasm_tls_align() - 1;
   }
   size += __pthread_tsd_size + TSD_ALIGN - 1;
   size_t zero_size = size;
   if (!attr._a_stackaddr) {
-    size += attr._a_stacksize + STACK_ALIGN - 1;
+    size += guard_size + attr._a_stacksize + STACK_ALIGN - 1;
+    zero_size += guard_size;
   }
 
   // Allocate all the data for the new thread and zero-initialize all parts
@@ -176,6 +186,7 @@ int __pthread_create(pthread_t* restrict res,
     new->detach_state = DT_JOINABLE;
   }
   new->stack_size = attr._a_stacksize;
+  new->guard_size = guard_size;
 
   // 2. tls data
   if (__builtin_wasm_tls_size()) {
@@ -197,12 +208,13 @@ int __pthread_create(pthread_t* restrict res,
   if (attr._a_stackaddr) {
     new->stack = (void*)attr._a_stackaddr;
   } else {
+    offset += guard_size;
     offset = ROUND_UP(offset + new->stack_size, STACK_ALIGN);
     new->stack = (void*)offset;
   }
 
   // Check that we didn't use more data than we allocated.
-  assert(offset < (uintptr_t)block + size);
+  assert(offset <= (uintptr_t)block + size);
 
 #ifndef NDEBUG
   _emscripten_thread_profiler_init(new);

test/codesize/test_codesize_cxx_wasmfs.json

@@ -1,10 +1,10 @@
 {
   "a.out.js": 6725,
   "a.out.js.gz": 3184,
-  "a.out.nodebug.wasm": 172829,
-  "a.out.nodebug.wasm.gz": 63329,
-  "total": 179554,
-  "total_gz": 66513,
+  "a.out.nodebug.wasm": 172782,
+  "a.out.nodebug.wasm.gz": 63311,
+  "total": 179507,
+  "total_gz": 66495,
   "sent": [
     "__cxa_throw",
     "_abort_js",

test/codesize/test_codesize_files_wasmfs.json

@@ -1,10 +1,10 @@
 {
   "a.out.js": 5158,
   "a.out.js.gz": 2458,
-  "a.out.nodebug.wasm": 58606,
-  "a.out.nodebug.wasm.gz": 18406,
-  "total": 63764,
-  "total_gz": 20864,
+  "a.out.nodebug.wasm": 58562,
+  "a.out.nodebug.wasm.gz": 18269,
+  "total": 63720,
+  "total_gz": 20727,
   "sent": [
     "a (emscripten_date_now)",
     "b (emscripten_err)",

test/codesize/test_codesize_minimal_pthreads.json

@@ -1,10 +1,10 @@
 {
   "a.out.js": 6945,
   "a.out.js.gz": 3424,
-  "a.out.nodebug.wasm": 19063,
-  "a.out.nodebug.wasm.gz": 8803,
-  "total": 26008,
-  "total_gz": 12227,
+  "a.out.nodebug.wasm": 19130,
+  "a.out.nodebug.wasm.gz": 8828,
+  "total": 26075,
+  "total_gz": 12252,
   "sent": [
     "a (memory)",
     "b (exit)",

test/codesize/test_codesize_minimal_pthreads_memgrowth.json

@@ -1,10 +1,10 @@
 {
   "a.out.js": 7379,
   "a.out.js.gz": 3639,
-  "a.out.nodebug.wasm": 19064,
-  "a.out.nodebug.wasm.gz": 8804,
-  "total": 26443,
-  "total_gz": 12443,
+  "a.out.nodebug.wasm": 19131,
+  "a.out.nodebug.wasm.gz": 8829,
+  "total": 26510,
+  "total_gz": 12468,
   "sent": [
     "a (memory)",
     "b (exit)",

test/pthread/test_pthread_guardsize.c

@@ -0,0 +1,64 @@
+// Copyright 2026 The Emscripten Authors.  All rights reserved.
+// Emscripten is available under two separate licenses, the MIT license and the
+// University of Illinois/NCSA Open Source License.  Both these licenses can be
+// found in the LICENSE file.
+
+#define _GNU_SOURCE
+
+#include <assert.h>
+#include <pthread.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+void* thread_main_default(void* arg) {
+  pthread_attr_t attr;
+  size_t guard_size = 0;
+  assert(pthread_getattr_np(pthread_self(), &attr) == 0);
+  assert(pthread_attr_getguardsize(&attr, &guard_size) == 0);
+  printf("default guard_size: %zu\n", guard_size);
+  assert(guard_size == 8192);
+  return NULL;
+}
+
+void* thread_main_custom(void* arg) {
+  pthread_attr_t attr;
+  size_t guard_size = 0;
+  assert(pthread_getattr_np(pthread_self(), &attr) == 0);
+  assert(pthread_attr_getguardsize(&attr, &guard_size) == 0);
+  printf("custom guard_size: %zu\n", guard_size);
+  assert(guard_size == 16384);
+  return NULL;
+}
+
+void* thread_main_zero(void* arg) {
+  pthread_attr_t attr;
+  size_t guard_size = 0;
+  assert(pthread_getattr_np(pthread_self(), &attr) == 0);
+  assert(pthread_attr_getguardsize(&attr, &guard_size) == 0);
+  printf("zero guard_size: %zu\n", guard_size);
+  assert(guard_size == 0);
+  return NULL;
+}
+
+int main() {
+  pthread_t t1, t2, t3;
+  pthread_attr_t attr;
+
+  assert(pthread_create(&t1, NULL, thread_main_default, NULL) == 0);
+  assert(pthread_join(t1, NULL) == 0);
+
+  assert(pthread_attr_init(&attr) == 0);
+  assert(pthread_attr_setguardsize(&attr, 16384) == 0);
+  assert(pthread_create(&t2, &attr, thread_main_custom, NULL) == 0);
+  assert(pthread_join(t2, NULL) == 0);
+  assert(pthread_attr_destroy(&attr) == 0);
+
+  assert(pthread_attr_init(&attr) == 0);
+  assert(pthread_attr_setguardsize(&attr, 0) == 0);
+  assert(pthread_create(&t3, &attr, thread_main_zero, NULL) == 0);
+  assert(pthread_join(t3, NULL) == 0);
+  assert(pthread_attr_destroy(&attr) == 0);
+
+  printf("done\n");
+  return 0;
+}

test/pthread/test_pthread_guardsize.out

@@ -0,0 +1,4 @@
+default guard_size: 8192
+custom guard_size: 16384
+zero guard_size: 0
+done

test/pthread/test_pthread_guardsize_overflow.c

@@ -0,0 +1,29 @@
+// Copyright 2026 The Emscripten Authors.  All rights reserved.
+// Emscripten is available under two separate licenses, the MIT license and the
+// University of Illinois/NCSA Open Source License.  Both these licenses can be
+// found in the LICENSE file.
+
+#include <assert.h>
+#include <pthread.h>
+#include <stdio.h>
+#include <emscripten/stack.h>
+
+void* thread_main_overflow(void* arg) {
+  uintptr_t stack_end = emscripten_stack_get_end();
+  // Overwrite 500 bytes into the guard region below stack_end and the 8-byte stack cookie at stack_end.
+  // Total 508 bytes (well under default guard_size = 8192).
+  volatile char* ptr = (volatile char*)(stack_end - 500);
+  for (int i = 0; i < 508; i++) {
+    ptr[i] = 0xAA;
+  }
+  printf("thread_main_overflow done\n");
+  return NULL;
+}
+
+int main() {
+  pthread_t t;
+  assert(pthread_create(&t, NULL, thread_main_overflow, NULL) == 0);
+  assert(pthread_join(t, NULL) == 0);
+  printf("main done\n");
+  return 0;
+}

test/test_core.py

@@ -2655,6 +2655,16 @@ def test_pthread_attr_getstack(self):
       self.skipTest('MINIMAL_RUNTIME + threads + asan does not work')
     self.do_runf_out_file('pthread/test_pthread_attr_getstack.c')
 
+  @requires_pthreads
+  def test_pthread_guardsize(self):
+    self.do_runf_out_file('pthread/test_pthread_guardsize.c')
+
+  @requires_pthreads
+  def test_pthread_guardsize_overflow(self):
+    self.set_setting('STACK_OVERFLOW_CHECK', 1)
+    expected = r'Aborted\(Stack overflow! Stack cookie has been overwritten at 0x[0-9a-fA-F]+, expected hex dwords 0x89BACDFE and 0x2135467, but received 0xaaaaaaaa 0xaaaaaaaa\)'
+    self.do_runf('pthread/test_pthread_guardsize_overflow.c', expected, regex=True, assert_returncode=NON_ZERO)
+
   @requires_pthreads
   @no_bun('https://github.com/emscripten-core/emscripten/issues/26199')
   @flaky('flaky specifically in esm_integration suite. https://github.com/emscripten-core/emscripten/issues/25151')