reference: document unwinding unsafety issues

diff --git a/src/doc/reference.md b/src/doc/reference.md
index cfa69cdfd4975f9171f218bc20e14fef10ef85bd..7f410b7fd934e840398970d3fe9f7f060ac50f26 100644 (file)
--- a/src/doc/reference.md
+++ b/src/doc/reference.md
@@ -1170,6 +1170,9 @@ exposing an API making it possible for it to occur in safe code.
   * A discriminant in an `enum` not included in the type definition
   * A value in a `char` which is a surrogate or above `char::MAX`
   * non-UTF-8 byte sequences in a `str`
+* Unwinding into Rust from foreign code or unwinding from Rust into foreign
+  code. Rust's failure system is not compatible with exception handling in
+  other languages. Unwinding must be caught and handled at FFI boundaries.
 
 ##### Behaviour not considered unsafe