CreateJobObject

The CreateJobObject function creates or opens a job object.

HANDLE CreateJobObject(
  LPSECURITY_ATTRIBUTES lpJobAttributes,  // SD
  LPCTSTR lpName                          // job name 
);

Parameters

lpJobAttributes

[in] 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

[in] Pointer to a null-terminated string specifying 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 name space.

Terminal Services: The name can have a "Global\" or "Local\" prefix to explicitly create the object in the global or session name space. The remainder of the name can contain any character except the backslash character (\). For more information, see Kernel Object Name Spaces.

Windows 2000: On Windows 2000 systems without Terminal Services running, the "Global\" and "Local\" prefixes are ignored. The remainder of the name can contain any character except the backslash character.

Return Values

If the function succeeds, the return value is a handle to the job object. The handle has JOB_OBJECT_ALL_ACCESS 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 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, use the AssignProcessToJobObject function. To set limits for a job, use the SetInformationJobObject function. To query accounting information, use the QueryInformationJobObject function.

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

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

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