PTHREAD_ATTR_SETGUARDSIZE(3)

💖 pthread_at...etguardsize(3) 💖

okay bestie, we're in the Library Functions Manual section of the man pages, and today's main character is the guard size attribute of thread attributes objects. yes, that's a real thing, and yes, it's lowkey iconic. grab your pthread.h and let's go 🦋

---

✨ NAME ✨

pthread_attr_setguardsize, pthread_attr_getguardsize — set/get guard size attribute in thread attributes object

📚 LIBRARY 📚

POSIX threads library (libpthread, -lpthread)

🌸 SYNOPSIS 🌸

#include <pthread.h>

int pthread_attr_setguardsize(pthread_attr_t *attr, size_t guardsize);
int pthread_attr_getguardsize(const pthread_attr_t *restrict attr,
                              size_t *restrict guardsize);

💅 DESCRIPTION 💅

so pthread_attr_setguardsize() sets the guard size attribute of the thread attributes object that attr points at, and it sets it to whatever number you put in guardsize. simple. slay.

• if guardsize is greater than 0, then for every new thread you create using attr, the system allocates an additional region of at least guardsize bytes at the end of the thread's stack, and that region is the guard area for the stack 👀 (but fr, go read BUGS below, it's not that simple)
• if guardsize is 0, then new threads created with attr won't have a guard area at all. zero. nada. bye ✨

the default guard size is the same as the system page size. no cap.

now here's the plot twist 🎀 — if the stack address attribute has already been set in attr (using pthread_attr_setstack(3) or pthread_attr_setstackaddr(3)), which means you, the caller, are the one allocating the thread's stack, then the guard size attribute gets ignored. like, the system does not create a guard area for you. it's on the application to handle stack overflow — maybe by using mprotect(2) to manually define a guard area at the end of that stack you allocated. you chose this life, bestie, own it 😭

and pthread_attr_getguardsize() hands you back the guard size attribute of the thread attributes object that attr points at, dropping it into the buffer that guardsize points at. cute, tidy, done.

🔥 RETURN VALUE 🔥

• on success, these functions return 0 💖
• on error, they return a nonzero error number 😔

⭐ ERRORS ⭐

POSIX.1 documents an EINVAL error if attr or guardsize is invalid. but on Linux these functions always succeed. always. (that said, portable and future-proof applications should still handle a possible error return, because being prepared is main character energy 👑)

🫶 ATTRIBUTES 🫶

for an explanation of the terms used in this section, see attributes(7).

• pthread_attr_setguardsize(), pthread_attr_getguardsize() — Thread safety: MT-Safe

(the original ships this as a table, but tables aren't invited to this party, so here's the same tea in a bullet 💜)

🌈 STANDARDS 🌈

POSIX.1-2008.

🎀 HISTORY 🎀

glibc 2.1. POSIX.1-2001. vintage, honestly.

💀 NOTES 💀

a guard area is made up of virtual memory pages that are protected so that read and write access is prevented. so if a thread overflows its stack into the guard area, then on most hard architectures it receives a SIGSEGV signal — which is the system's way of going "bestie. your stack. it's overflowing." 🚨

guard areas start on page boundaries, and the guard size gets internally rounded up to the system page size when creating a thread. (nevertheless, pthread_attr_getguardsize() returns the guard size that was set by pthread_attr_setguardsize(), not the rounded one. it keeps receipts.)

• setting a guard size of 0 may be useful to save memory in an application that creates many threads and knows that stack overflow can never occur. 🧚
• choosing a guard size larger than the default may be necessary for detecting stack overflows if a thread allocates large data structures on the stack.

🙈 BUGS 🙈

as at glibc 2.8, the NPTL threading implementation includes the guard area within the stack size allocation, rather than allocating extra space at the end of the stack, as POSIX.1 requires. (this can result in an EINVAL error from pthread_create(3) if the guard size value is too large, leaving no space for the actual stack.) 💀

the obsolete LinuxThreads implementation did the right thing, allocating extra space at the end of the stack for the guard area. rip to a real one 🕯️

🍓 EXAMPLES 🍓

see pthread_getattr_np(3).

👑 SEE ALSO 👑

• mmap(2)
• mprotect(2)
• pthread_attr_init(3)
• pthread_attr_setstack(3)
• pthread_attr_setstacksize(3)
• pthread_create(3)
• pthreads(7)

---

okay that's the whole page, you're officially a guard-size girlie now 💅✨ this was served up by Linux man-pages 6.20, dated 2025-05-17, and that's the vibe check, periodt 🎀🦋💖