7.2.3 Task Information

Function: task_t mach_task_self ()

The mach_task_self system call returns the calling thread’s task port.

mach_task_self has an effect equivalent to receiving a send right for the task port. mach_task_self returns the name of the send right. In particular, successive calls will increase the calling task’s user-reference count for the send right.

As a special exception, the kernel will overrun the user reference count of the task name port, so that this function can not fail for that reason. Because of this, the user should not deallocate the port right if an overrun might have happened. Otherwise the reference count could drop to zero and the send right be destroyed while the user still expects to be able to use it. As the kernel does not make use of the number of extant send rights anyway, this is safe to do (the task port itself is not destroyed, even when there are no send rights anymore).

The function returns MACH_PORT_NULL if a resource shortage prevented the reception of the send right, MACH_PORT_NULL if the task port is currently null, MACH_PORT_DEAD if the task port is currently dead.

Function: kern_return_t task_threads (task_t target_task, thread_array_t *thread_list, mach_msg_type_number_t *thread_count)

The function task_threads gets send rights to the kernel port for each thread contained in target_task. thread_list is an array that is created as a result of this call. The caller may wish to vm_deallocate this array when the data is no longer needed.

The function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if target_task is not a task.

Function: kern_return_t task_info (task_t target_task, int flavor, task_info_t task_info, mach_msg_type_number_t *task_info_count)

The function task_info returns the selected information array for a task, as specified by flavor. task_info is an array of integers that is supplied by the caller, and filled with specified information. task_info_count is supplied as the maximum number of integers in task_info. On return, it contains the actual number of integers in task_info. The maximum number of integers returned by any flavor is TASK_INFO_MAX.

The type of information returned is defined by flavor, which can be one of the following:

TASK_BASIC_INFO

The function returns basic information about the task, as defined by task_basic_info_t. This includes the user and system time and memory consumption. The number of integers returned is TASK_BASIC_INFO_COUNT.

TASK_EVENTS_INFO

The function returns information about events for the task as defined by thread_sched_info_t. This includes statistics about virtual memory and IPC events like pageouts, pageins and messages sent and received. The number of integers returned is TASK_EVENTS_INFO_COUNT.

TASK_THREAD_TIMES_INFO

The function returns information about the total time for live threads as defined by task_thread_times_info_t. The number of integers returned is TASK_THREAD_TIMES_INFO_COUNT.

The function returns KERN_SUCCESS if the call succeeded and KERN_INVALID_ARGUMENT if target_task is not a thread or flavor is not recognized. The function returns MIG_ARRAY_TOO_LARGE if the returned info array is too large for task_info. In this case, task_info is filled as much as possible and task_infoCnt is set to the number of elements that would have been returned if there were enough room.

Data type: struct task_basic_info

This structure is returned in task_info by the task_info function and provides basic information about the task. You can cast a variable of type task_info_t to a pointer of this type if you provided it as the task_info parameter for the TASK_BASIC_INFO flavor of task_info. It has the following members:

integer_t suspend_count

suspend count for task

integer_t base_priority

base scheduling priority

vm_size_t virtual_size

number of virtual pages

vm_size_t resident_size

number of resident pages

time_value_t user_time

total user run time for terminated threads

time_value_t system_time

total system run time for terminated threads

time_value_t creation_time

creation time stamp

Data type: task_basic_info_t

This is a pointer to a struct task_basic_info.

Data type: struct task_events_info

This structure is returned in task_info by the task_info function and provides event statistics for the task. You can cast a variable of type task_info_t to a pointer of this type if you provided it as the task_info parameter for the TASK_EVENTS_INFO flavor of task_info. It has the following members:

natural_t faults

number of page faults

natural_t zero_fills

number of zero fill pages

natural_t reactivations

number of reactivated pages

natural_t pageins

number of actual pageins

natural_t cow_faults

number of copy-on-write faults

natural_t messages_sent

number of messages sent

natural_t messages_received

number of messages received

Data type: task_events_info_t

This is a pointer to a struct task_events_info.

Data type: struct task_thread_times_info

This structure is returned in task_info by the task_info function and provides event statistics for the task. You can cast a variable of type task_info_t to a pointer of this type if you provided it as the task_info parameter for the TASK_THREAD_TIMES_INFO flavor of task_info. It has the following members:

time_value_t user_time

total user run time for live threads

time_value_t system_time

total system run time for live threads

Data type: task_thread_times_info_t

This is a pointer to a struct task_thread_times_info.

Function: kern_return_t task_set_name (task_t target_task, kernel_debug_name_t name)

The function task_set_name sets the name of target_task to name, truncating it if necessary.

This is a debugging aid. The name is used in diagnostic messages printed by the kernel.

The function returns KERN_SUCCESS if the call succeeded.