AssignProcessToJobObject

The AssignProcessToJobObject function associates a process with an existing job object.

BOOL AssignProcessToJobObject(
  HANDLE hJob,     // handle to job
  HANDLE hProcess  // handle to process
);

Parameters

hJob

[in] Handle to the job object to which the process will be associated. The CreateJobObject or OpenJobObject function returns this handle. The handle must have the JOB_OBJECT_ASSIGN_PROCESS access right associated with it. For more information, see Job Object Security and Access Rights.

hProcess

[in] Handle to the process to associate with the job object. The process must not already be assigned to a job. The handle must have PROCESS_SET_QUOTA and PROCESS_TERMINATE access to the process. For more information, see Process Security and Access Rights.

Terminal Services: All processes within a job must run within the same session.

Return Values

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

After you associate a process with a job object using AssignProcessToJobObject, the process is subject to the limits set for the job. To set limits for a job, use the SetInformationJobObject function.

If the job has a user-mode time limit, and the time limit has been exhausted, AssignProcessToJobObject fails and the specified process is terminated. If the time limit would be exceeded by associating the process, AssignProcessToJobObject still succeeds. However, the time limit violation will be reported. If the job has an active process limit, and the limit would be exceeded by associating this process, AssignProcessToJobObject fails, and the specified process is terminated.

Memory operations performed by a process associated with a job that has a memory limit are subject to the memory limit. Memory operations performed by the process before it was associated with the job are not examined by AssignProcessToJobObject.

If the process is already running and the job has security limitations, AssignProcessToJobObject may fail. For example, if the primary token of the process contains the local administrators group, but the job object has the security limitation JOB_OBJECT_SECURITY_NO_ADMIN, the function fails. If the job has the security limitation JOB_OBJECT_SECURITY_ONLY_TOKEN, the process must be created suspended. To create a suspended process, call the CreateProcess function with the CREATE_SUSPENDED flag.

A process can be associated only with a single job. A process inherits limits from the job it is associated with and adds its accounting information to the job. If a process is associated with a job, all processes it creates are associated with that job by default. To create a process that is not part of the same job, call the CreateProcess function with the CREATE_BREAKAWAY_FROM_JOB flag.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.

See Also

Processes and Threads Overview, Process and Thread Functions, Processes and Threads Overview, CreateJobObject, CreateProcess, OpenJobObject, SetInformationJobObject