diff --git a/lib/libc/gen/getcontext.3 b/lib/libc/gen/getcontext.3
--- a/lib/libc/gen/getcontext.3
+++ b/lib/libc/gen/getcontext.3
@@ -141,9 +141,31 @@
 .It Bq Er ENOMEM
 No memory was available to allocate for the context or some extended state.
 .El
+.Sh BUGS
+.Fn getcontext
+and
+.Fn setcontext
+may not save and restore all the CPU's state.
+The state that is not saved can change between a call to
+.Fn getcontext
+and subsequent
+.Fn setcontext .
+Use
+.Fn getcontextx
+and
+.Fn setcotnextx
+to avoid this problem.
+The same caveat applies for
+.Fn getcontext
+and
+.Fn sigreturn
+though the kernel typically manages the
+.Vt ucontext_t
+when signals are sent to a process.
 .Sh SEE ALSO
 .Xr sigaction 2 ,
 .Xr sigaltstack 2 ,
+.Xr sigreturn 2 ,
 .Xr makecontext 3 ,
 .Xr ucontext 3
 .Sh STANDARDS