Creates or opens a job object.

Syntax

HANDLE WINAPI CreateJobObject(
  __in_opt  LPSECURITY_ATTRIBUTES lpJobAttributes,
  __in_opt  LPCTSTR lpName
);

Parameters

lpJobAttributes [in, optional]

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.

lpName [in, optional]

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.

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 name space. The remainder of the name can contain any character except the backslash character (\). For more information, see Kernel Object Namespaces.

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

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/2000:  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

See Also

AssignProcessToJobObject

CloseHandle

Job Objects

Process and Thread Functions

QueryInformationJobObject

SECURITY_ATTRIBUTES

SetInformationJobObject

Send comments about this topic to Microsoft

Build date: 7/2/2009