Home Library Learn Downloads Support Community
Sign in | United States - English | |
This topic has not yet been rated - Rate this topic

GenerateConsoleCtrlEvent function

Applies to: desktop apps only

Sends a specified signal to a console process group that shares the console associated with the calling process.

Syntax

Copy 
BOOL WINAPI GenerateConsoleCtrlEvent(
  __in  DWORD dwCtrlEvent,
  __in  DWORD dwProcessGroupId
);

Parameters

dwCtrlEvent [in]

The type of signal to be generated. This parameter can be one of the following values.

ValueMeaning
CTRL_C_EVENT
0

Generates a CTRL+C signal. This signal cannot be generated for process groups. If dwProcessGroupId is nonzero, this function will succeed, but the CTRL+C signal will not be received by processes within the specified process group.

CTRL_BREAK_EVENT
1

Generates a CTRL+BREAK signal.

 

dwProcessGroupId [in]

The identifier of the process group to receive the signal. A process group is created when the CREATE_NEW_PROCESS_GROUP flag is specified in a call to the CreateProcess function. The process identifier of the new process is also the process group identifier of a new process group. The process group includes all processes that are descendants of the root process. Only those processes in the group that share the same console as the calling process receive the signal. In other words, if a process in the group creates a new console, that process does not receive the signal, nor do its descendants.

If this parameter is zero, the signal is generated in all processes that share the console of the calling process.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

GenerateConsoleCtrlEvent causes the control handler functions of processes in the target group to be called. All console processes have a default handler function that calls the ExitProcess function. A console process can use the SetConsoleCtrlHandler function to install or remove other handler functions.

SetConsoleCtrlHandler can also enable an inheritable attribute that causes the calling process to ignore CTRL+C signals. If GenerateConsoleCtrlEvent sends a CTRL+C signal to a process for which this attribute is enabled, the handler functions for that process are not called. CTRL+BREAK signals always cause the handler functions to be called.

Requirements

Minimum supported client

Windows 2000 Professional

Minimum supported server

Windows 2000 Server

Header
Wincon.h (include Windows.h)

Library
Kernel32.lib

DLL
Kernel32.dll

See also

Console Control Handlers
Console Functions
CreateProcess
ExitProcess
SetConsoleCtrlHandler

 

 

Send comments about this topic to Microsoft

Build date: 2/3/2012

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
Making a call to AllocConsole requires a new call to SetConsoleCtrlHandler
My process can optionally start as a service and it always kicks off child processes. Only my one parent process had to have the AllocConsole() added for the messaging to succeed. But, if your code had made a previous call to SetConsoleCtrlHandler(), calling AllocConsole() (having detected your process is being run as a service) will require an new call to SetConsoleCtrlHandler().
History
ERROR_INVALID_PARAMETER (87)
I don't have time to investigate this fully, but it seems like calling this method on a process that does not have an attached console will give ERROR_INVALID_PARAMETER (87).
History
Calling this function from a service
Apparently this function requires the calling code to be a console application as well as the target.

This is further complicated when using it in a Windows Service, as services do not seem to have consoles even if the EXE is marked as a Console application. Thus, I kept getting ERROR_INVALID_HANDLE when trying to call GenerateConsoleCtrlEvent. I fixed it by forcing console creation in the service with AllocConsole().
History