Skip to content

Commit dba8154

Browse files
v-shilsv-shils
authored
Merge pull request #3235 from TylerMSFT/twhitney-github2367
fix github issue 2367
2 parents 851f82a + bd39e25 commit dba8154

File tree

1 file changed

+52
-49
lines changed
  • docs/c-runtime-library/reference

1 file changed

+52
-49
lines changed

‎docs/c-runtime-library/reference/cwait.md

+52-49
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
title: "_cwait"
3-
ms.date: "4/2/2020"
3+
description: "API reference for the Microsoft Visual C runtime `_cwait()` function."
4+
ms.date: "10/23/2020"
45
api_name: ["_cwait", "_o__cwait"]
56
api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"]
67
api_type: ["DLLExport"]
@@ -28,43 +29,43 @@ intptr_t _cwait(
2829

2930
### Parameters
3031

31-
*termstat*<br/>
32-
Pointer to a buffer where the result code of the specified process will be stored, or **NULL**.
32+
*`termstat`*\
33+
Pointer to a buffer where the result code of the specified process will be stored, or **`NULL`**.
3334

34-
*procHandle*<br/>
35+
*`procHandle`*\
3536
The handle to the process to wait on (that is, the process that has to terminate before **_cwait** can return).
3637

37-
*action*<br/>
38-
NULL: Ignored by Windows operating system applications; for other applications: action code to perform on *procHandle*.
38+
*`action`*\
39+
**`NULL`**: Ignored by Windows operating system applications; for other applications: action code to perform on *`procHandle`*.
3940

4041
## Return Value
4142

42-
When the specified process has successfully completed, returns the handle of the specified process and sets *termstat* to the result code that's returned by the specified process. Otherwise, returns -1 and sets **errno** as follows.
43+
When the specified process has successfully completed, returns the handle of the specified process and sets *`termstat`* to the result code that's returned by the specified process. Otherwise, returns -1 and sets **`errno`** as follows.
4344

4445
|Value|Description|
4546
|-----------|-----------------|
46-
|**ECHILD**|No specified process exists, *procHandle* is invalid, or the call to the [GetExitCodeProcess](/windows/win32/api/processthreadsapi/nf-processthreadsapi-getexitcodeprocess) or [WaitForSingleObject](/windows/win32/api/synchapi/nf-synchapi-waitforsingleobject) API failed.|
47-
|**EINVAL**|*action* is invalid.|
47+
|**`ECHILD`**|No specified process exists, *`procHandle`* is invalid, or the call to the [`GetExitCodeProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-getexitcodeprocess) or [`WaitForSingleObject`](/windows/win32/api/synchapi/nf-synchapi-waitforsingleobject) API failed.|
48+
|**`EINVAL`**|*`action`* is invalid.|
4849

49-
For more information about these and other return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md).
50+
For more information about these and other return codes, see [`errno, _doserrno, _sys_errlist, and _sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md).
5051

5152
## Remarks
5253

53-
The **_cwait** function waits for the termination of the process ID of the specified process that's provided by *procHandle*. The value of *procHandle* that's passed to **_cwait** should be the value that's returned by the call to the [_spawn](../../c-runtime-library/spawn-wspawn-functions.md) function that created the specified process. If the process ID terminates before **_cwait** is called, **_cwait** returns immediately. **_cwait** can be used by any process to wait for any other known process for which a valid handle (*procHandle*) exists.
54+
The **`_cwait`** function waits for the termination of the process ID of the specified process that's provided by *`procHandle`*. The value of *`procHandle`* that's passed to **`_cwait`** should be the value that's returned by the call to the [`_spawn`](../../c-runtime-library/spawn-wspawn-functions.md) function that created the specified process. If the process ID terminates before **`_cwait`** is called, **`_cwait`** returns immediately. **`_cwait`** can be used by any process to wait for any other known process for which a valid handle (*`procHandle`*) exists.
5455

55-
*termstat* points to a buffer where the return code of the specified process will be stored. The value of *termstat* indicates whether the specified process terminated normally by calling the Windows [ExitProcess](/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitprocess) API. **ExitProcess** is called internally if the specified process calls **exit** or **_exit**, returns from **main**, or reaches the end of **main**. For more information about the value that's passed back through *termstat*, see [GetExitCodeProcess](/windows/win32/api/processthreadsapi/nf-processthreadsapi-getexitcodeprocess). If **_cwait** is called by using a **NULL** value for *termstat*, the return code of the specified process is not stored.
56+
*`termstat`* points to a buffer where the return code of the specified process will be stored. The value of *`termstat`* indicates whether the specified process terminated normally by calling the Windows [`ExitProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitprocess) API. **`ExitProcess`** is called internally if the specified process calls **`exit`** or **`_exit`**, returns from **`main`**, or reaches the end of **`main`**. For more information about the value that's passed back through *`termstat`*, see [GetExitCodeProcess](/windows/win32/api/processthreadsapi/nf-processthreadsapi-getexitcodeprocess). If **`_cwait`** is called by using a **`NULL`** value for *`termstat`*, the return code of the specified process isn't stored.
5657

57-
The *action* parameter is ignored by the Windows operating system because parent-child relationships are not implemented in these environments.
58+
The *`action`* parameter is ignored by the Windows operating system because parent-child relationships aren't implemented in these environments.
5859

59-
Unless *procHandle* is -1 or -2 (handles to the current process or thread), the handle will be closed. Therefore, in this situation, do not use the returned handle.
60+
Unless *`procHandle`* is -1 or -2 (handles to the current process or thread), the handle will be closed. In this situation, don't use the returned handle.
6061

6162
By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md).
6263

6364
## Requirements
6465

6566
|Routine|Required header|Optional header|
6667
|-------------|---------------------|---------------------|
67-
|**_cwait**|\<process.h>|\<errno.h>|
68+
|**`_cwait`**|\<process.h>|\<errno.h>|
6869

6970
For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md).
7071

@@ -89,44 +90,46 @@ For more compatibility information, see [Compatibility](../../c-runtime-library/
8990

9091
struct PROCESS
9192
{
92-
int nPid;
93-
char name[40];
93+
intptr_t hProcess;
94+
char name[40];
9495
} process[4] = { { 0, "Ann" }, { 0, "Beth" }, { 0, "Carl" }, { 0, "Dave" } };
9596

96-
int main( int argc, char *argv[] )
97+
int main(int argc, char* argv[])
9798
{
98-
int termstat, c;
99-
unsigned int number;
100-
101-
srand( (unsigned)time( NULL ) ); // Seed randomizer
102-
103-
// If no arguments, this is the calling process
104-
if ( argc == 1 )
105-
{
106-
// Spawn processes in numeric order
107-
for ( c = 0; c < 4; c++ ) {
108-
_flushall();
109-
process[c].nPid = _spawnl( _P_NOWAIT, argv[0], argv[0],
110-
process[c].name, NULL );
111-
}
112-
113-
// Wait for randomly specified process, and respond when done
114-
c = getrandom( 0, 3 );
115-
printf( "Come here, %s.\n", process[c].name );
116-
_cwait( &termstat, process[c].nPid, _WAIT_CHILD );
117-
printf( "Thank you, %s.\n", process[c].name );
118-
119-
}
120-
// If there are arguments, this must be a spawned process
121-
else
122-
{
123-
// Delay for a period that's determined by process number
124-
Sleep( (argv[1][0] - 'A' + 1) * 1000L );
125-
printf( "Hi, Dad. It's %s.\n", argv[1] );
126-
}
99+
int termstat, c;
100+
unsigned int number;
101+
102+
srand((unsigned)time(NULL)); // Seed randomizer
103+
104+
// If no arguments, this is the calling process
105+
if (argc == 1)
106+
{
107+
// Spawn processes in numeric order
108+
for (c = 0; c < 4; c++) {
109+
_flushall();
110+
process[c].hProcess = _spawnl(_P_NOWAIT, argv[0], argv[0],
111+
process[c].name, NULL);
112+
}
113+
114+
// Wait for randomly specified process, and respond when done
115+
c = getrandom(0, 3);
116+
printf("Come here, %s.\n", process[c].name);
117+
_cwait(&termstat, process[c].hProcess, _WAIT_CHILD);
118+
printf("Thank you, %s.\n", process[c].name);
119+
120+
}
121+
// If there are arguments, this must be a spawned process
122+
else
123+
{
124+
// Delay for a period that's determined by process number
125+
Sleep((argv[1][0] - 'A' + 1) * 1000L);
126+
printf("Hi, Dad. It's %s.\n", argv[1]);
127+
}
127128
}
128129
```
129130
131+
The order of the output varies from run to run.
132+
130133
```Output
131134
Hi, Dad. It's Ann.
132135
Come here, Ann.
@@ -138,5 +141,5 @@ Hi, Dad. It's Dave.
138141

139142
## See also
140143

141-
[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)<br/>
142-
[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)<br/>
144+
[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)\
145+
[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)

0 commit comments

Comments
 (0)