Merge pull request #917 from corob-msft/cr-longjmp

Fix longjmp docs for DD288352

Author: GitHubber17

.openpublishing.redirection.json

@@ -1,4 +1,4 @@
-{
+{ 
     "redirections": [
         {
             "source_path": "docs/assembler/arm/index.md",
@@ -240,6 +240,11 @@
             "redirect_url": "/cpp/cpp/extern-cpp",
             "redirect_document_id": false
         },
+        {
+            "source_path": "docs/cpp/using-structured-exception-handling-with-cpp.md",
+            "redirect_url": "/cpp/cpp/exception-handling-differences",
+            "redirect_document_id": false
+        },
         {
             "source_path": "docs/cpp/support-for-cpp11-14-17-features-modern-cpp.md",
             "redirect_url": "/cpp/visual-cpp-language-conformance",

docs/build/reference/eh-exception-handling-model.md

@@ -1,7 +1,7 @@
 ---
 title: "longjmp | Microsoft Docs"
 ms.custom: ""
-ms.date: "11/04/2016"
+ms.date: "08/14/2018"
 ms.technology: ["cpp-standard-libraries"]
 ms.topic: "reference"
 apiname: ["longjmp"]
@@ -17,7 +17,7 @@ ms.workload: ["cplusplus"]
 ---
 # longjmp
 
-Restores stack environment and execution locale.
+Restores the stack environment and execution locale set by a `setjmp` call.
 
 ## Syntax
 
@@ -30,27 +30,39 @@ void longjmp(
 
 ### Parameters
 
-*env*
+*env*  
 Variable in which environment is stored.
 
-*value*
-Value to be returned to **setjmp** call.
+*value*  
+Value to be returned to `setjmp` call.
 
 ## Remarks
 
-The **longjmp** function restores a stack environment and execution locale previously saved in *env* by **setjmp**. **setjmp** and **longjmp** provide a way to execute a nonlocal **goto**; they are typically used to pass execution control to error-handling or recovery code in a previously called routine without using the normal call and return conventions.
+The **longjmp** function restores a stack environment and execution locale previously saved in *env* by `setjmp`. `setjmp` and **longjmp** provide a way to execute a nonlocal **goto**; they are typically used to pass execution control to error-handling or recovery code in a previously called routine without using the normal call and return conventions.
 
-A call to **setjmp** causes the current stack environment to be saved in *env*. A subsequent call to **longjmp** restores the saved environment and returns control to the point immediately following the corresponding **setjmp** call. Execution resumes as if *value* had just been returned by the **setjmp** call. The values of all variables (except register variables) that are accessible to the routine receiving control contain the values they had when **longjmp** was called. The values of register variables are unpredictable. The value returned by **setjmp** must be nonzero. If *value* is passed as 0, the value 1 is substituted in the actual return.
+A call to `setjmp` causes the current stack environment to be saved in *env*. A subsequent call to **longjmp** restores the saved environment and returns control to the point immediately following the corresponding `setjmp` call. Execution resumes as if *value* had just been returned by the `setjmp` call. The values of all variables (except register variables) that are accessible to the routine receiving control contain the values they had when **longjmp** was called. The values of register variables are unpredictable. The value returned by `setjmp` must be nonzero. If *value* is passed as 0, the value 1 is substituted in the actual return.
 
-Call **longjmp** before the function that called **setjmp** returns; otherwise the results are unpredictable.
+**Microsoft Specific**
+
+In Microsoft C++ code on Windows, **longjmp** uses the same stack-unwinding semantics as exception-handling code. It is safe to use in the same places that C++ exceptions can be raised. However, this usage is not portable, and comes with some important caveats.
+
+Only call **longjmp** before the function that called `setjmp` returns; otherwise the results are unpredictable.
 
 Observe the following restrictions when using **longjmp**:
 
-- Do not assume that the values of the register variables will remain the same. The values of register variables in the routine calling **setjmp** may not be restored to the proper values after **longjmp** is executed.
+- Do not assume that the values of the register variables will remain the same. The values of register variables in the routine calling `setjmp` may not be restored to the proper values after **longjmp** is executed.
+
+- Do not use **longjmp** to transfer control out of an interrupt-handling routine unless the interrupt is caused by a floating-point exception. In this case, a program may return from an interrupt handler via **longjmp** if it first reinitializes the floating-point math package by calling [_fpreset](fpreset.md).
+
+- Do not use **longjmp** to transfer control from a callback routine invoked directly or indirectly by Windows code.
 
-- Do not use **longjmp** to transfer control out of an interrupt-handling routine unless the interrupt is caused by a floating-point exception. In this case, a program may return from an interrupt handler via **longjmp** if it first reinitializes the floating-point math package by calling **_fpreset**.
+- If the code is compiled by using **/EHs** or **/EHsc** and the function that contains the **longjmp** call is **noexcept** then local objects in that function may not be destructed during the stack unwind.
 
-     **Note** Be careful when using **setjmp** and **longjmp** in C++ programs. Because these functions do not support C++ object semantics, it is safer to use the C++ exception-handling mechanism.
+**END Microsoft Specific**
+
+> [!NOTE]  
+> In portable C++ code, you can't assume `setjmp` and `longjmp` support C++ object semantics. Specifically, a `setjmp`/`longjmp` call pair has undefined behavior if replacing the `setjmp` and `longjmp` by **catch**
+and **throw** would invoke any non-trivial destructors for any automatic objects. In C++ programs, we recommend you use the C++ exception-handling mechanism.
 
 For more information, see [Using setjmp and longjmp](../../cpp/using-setjmp-longjmp.md).
 
@@ -62,15 +74,11 @@ For more information, see [Using setjmp and longjmp](../../cpp/using-setjmp-long
 
 For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md).
 
-## Libraries
-
-All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md).
-
 ## Example
 
 See the example for [_fpreset](fpreset.md).
 
 ## See also
 
-[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)<br/>
-[setjmp](setjmp.md)<br/>
+[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)  
+[setjmp](setjmp.md)  

docs/c-runtime-library/reference/longjmp.md

@@ -1,7 +1,7 @@
 ---
 title: "setjmp | Microsoft Docs"
 ms.custom: ""
-ms.date: "11/04/2016"
+ms.date: "08/14/2018"
 ms.technology: ["cpp-standard-libraries"]
 ms.topic: "reference"
 apiname: ["setjmp"]
@@ -29,22 +29,30 @@ int setjmp(
 
 ### Parameters
 
-*env*<br/>
+*env*  
 Variable in which environment is stored.
 
 ## Return Value
 
-Returns 0 after saving the stack environment. If **setjmp** returns as a result of a **longjmp** call, it returns the **value** argument of **longjmp**, or if the **value** argument of **longjmp** is 0, **setjmp** returns 1. There is no error return.
+Returns 0 after saving the stack environment. If **setjmp** returns as a result of a `longjmp` call, it returns the *value* argument of `longjmp`, or if the *value* argument of `longjmp` is 0, **setjmp** returns 1. There is no error return.
 
 ## Remarks
 
-The **setjmp** function saves a stack environment, which you can subsequently restore, using **longjmp**. When used together, **setjmp** and **longjmp** provide a way to execute a non-local **goto**. They are typically used to pass execution control to error-handling or recovery code in a previously called routine without using the normal calling or return conventions.
+The **setjmp** function saves a stack environment, which you can subsequently restore, using `longjmp`. When used together, **setjmp** and `longjmp` provide a way to execute a non-local **goto**. They are typically used to pass execution control to error-handling or recovery code in a previously called routine without using the normal calling or return conventions.
 
-A call to **setjmp** saves the current stack environment in *env*. A subsequent call to **longjmp** restores the saved environment and returns control to the point just after the corresponding **setjmp** call. All variables (except register variables) accessible to the routine receiving control contain the values they had when **longjmp** was called.
+A call to **setjmp** saves the current stack environment in *env*. A subsequent call to `longjmp` restores the saved environment and returns control to the point just after the corresponding **setjmp** call. All variables (except register variables) accessible to the routine receiving control contain the values they had when `longjmp` was called.
 
 It is not possible to use **setjmp** to jump from native to managed code.
 
-**Note** **setjmp** and **longjmp** do not support C++ object semantics. In C++ programs, use the C++ exception-handling mechanism.
+**Microsoft Specific**
+
+In Microsoft C++ code on Windows, **longjmp** uses the same stack-unwinding semantics as exception-handling code. It is safe to use in the same places that C++ exceptions can be raised. However, this usage is not portable, and comes with some important caveats. For details, see [longjmp](longjmp.md).
+
+**END Microsoft Specific**
+
+> [!NOTE]  
+> In portable C++ code, you can't assume `setjmp` and `longjmp` support C++ object semantics. Specifically, a `setjmp`/`longjmp` call pair has undefined behavior if replacing the `setjmp` and `longjmp` by **catch**
+and **throw** would invoke any non-trivial destructors for any automatic objects. In C++ programs, we recommend you use the C++ exception-handling mechanism.
 
 For more information, see [Using setjmp and longjmp](../../cpp/using-setjmp-longjmp.md).
 
@@ -62,6 +70,5 @@ See the example for [_fpreset](fpreset.md).
 
 ## See also
 
-[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)<br/>
-[longjmp](longjmp.md)<br/>
-[_setjmp3](../../c-runtime-library/setjmp3.md)<br/>
+[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)  
+[longjmp](longjmp.md)  

docs/c-runtime-library/reference/setjmp.md

@@ -256,7 +256,7 @@
 #### [Unhandled C++ Exceptions](unhandled-cpp-exceptions.md)
 #### [Mixing C (Structured) and C++ Exceptions](mixing-c-structured-and-cpp-exceptions.md)
 ##### [Using setjmp-longjmp](using-setjmp-longjmp.md)
-##### [Exception Handling Differences](exception-handling-differences.md)
+##### [Handle structured exceptions in C++](exception-handling-differences.md)
 ### [Structured Exception Handling (C/C++)](structured-exception-handling-c-cpp.md)
 #### [Writing an Exception Handler](writing-an-exception-handler.md)
 ##### [try-except Statement](try-except-statement.md)
@@ -269,7 +269,6 @@
 ##### [Cleaning up Resources](cleaning-up-resources.md)
 ##### [Timing of Exception Handling: A Summary](timing-of-exception-handling-a-summary.md)
 ##### [Restrictions on Termination Handlers](restrictions-on-termination-handlers.md)
-#### [Using Structured Exception Handling with C++](using-structured-exception-handling-with-cpp.md)
 ### [Transporting Exceptions Between Threads](transporting-exceptions-between-threads.md)
 ## [Assertion and User-Supplied Messages](assertion-and-user-supplied-messages-cpp.md)
 ### [static_assert](static-assert.md)