CreateJobObjectA function (winbase.h)
Creates or opens a job object.
Syntax
HANDLE CreateJobObjectA(
[in, optional] LPSECURITY_ATTRIBUTES lpJobAttributes,
[in, optional] LPCSTR lpName
);
Parameters
[in, optional] lpJobAttributes
A pointer to a SECURITY_ATTRIBUTES structure that specifies the security descriptor for the job object and determines whether child processes can inherit the returned handle. If lpJobAttributes is NULL, the job object gets a default security descriptor and the handle cannot be inherited. The ACLs in the default security descriptor for a job object come from the primary or impersonation token of the creator.
[in, optional] lpName
The name of the job. The name is limited to MAX_PATH characters. Name comparison is case-sensitive.
If lpName is NULL, the job is created without a name.
If lpName matches the name of an existing event, semaphore, mutex, waitable timer, or file-mapping object, the function fails and the GetLastError function returns ERROR_INVALID_HANDLE. This occurs because these objects share the same namespace.
The object can be created in a private namespace. For more information, see Object Namespaces.
Terminal Services: The name can have a "Global" or "Local" prefix to explicitly create the object in the global or session namespace. The remainder of the name can contain any character except the backslash character (\). For more information, see Kernel Object Namespaces.
Return value
If the function succeeds, the return value is a handle to the job object. The handle has the JOB_OBJECT_ALL_ACCESS access right. If the object existed before the function call, the function returns a handle to the existing job object and GetLastError returns ERROR_ALREADY_EXISTS.
If the function fails, the return value is NULL. To get extended error information, call GetLastError.
Remarks
When a job is created, its accounting information is initialized to zero, all limits are inactive, and there are no associated processes. To assign a process to a job object, use the AssignProcessToJobObject function. To set limits for a job, use the SetInformationJobObject function. To query accounting information, use the QueryInformationJobObject function.
All processes associated with a job must run in the same session. A job is associated with the session of the first process to be assigned to the job.
Windows Server 2003 and Windows XP: A job is associated with the session of the process that created it.
To close a job object handle, use the CloseHandle function. The job is destroyed when its last handle has been closed and all associated processes have exited. However, if the job has the JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE flag specified, closing the last job object handle terminates all associated processes and then destroys the job object itself.
To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | winbase.h (include Windows.h, Jobapi2.h) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |