CreateJobObject

[This is preliminary documentation and subject to change.]

The CreateJobObject function creates a job object.

HANDLE CreateJobObject(
  LPSECURITY_ATTRIBUTES lpJobAttributes,
  LPCTSTR lpName
);
 

Parameters

lpJobAttributes

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.

lpName

Pointer to a null-terminated string specifying the name of the job object. The name is limited to MAX_PATH characters, and can contain any character except the backslash (\) character. Name comparison is case-sensitive.

If lpName is NULL, the job object 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 name space.

Return Values

If the function succeeds, the return value is a handle to the job object. The handle provides full access to the job object. 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 object is created, its accounting information is initialized to zero, all limits are inactive, and there are no associated processes. To associate a process with a job object, use the AssignProcessToJobObject function. To set limits for a job object, use the SetInformationJobObject function. To query accounting information, use the QueryInformationJobObject function.

To close a job object handle, use the CloseHandle function. The job object is destroyed when its last handle has been closed. If there are running processes still associated with the job object when it is destroyed, they will continue to run even after the job object is destroyed.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use kernel32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Processes and Threads Overview, Process and Thread Functions, AssignProcessToJobObject, CloseHandle, QueryInformationJobObject, SECURITY_ATTRIBUTES, SetInformationJobObject