mach/mach_port.h

The mach_port_names returns information about task 's port name space. It returns task's currently active names, which represent some port, port set, or dead name right. For each name, it also returns what type of rights task holds (the same information returned by mach_port_type). Note that when a call to mach_port_names returns, the number of entries in the two output arrays (names and types) are equal (namesCnt equals typesCnt). The fact that this interface returns two separate counts is an artifact of the Mach Interface Generator.

Notes. This interface is machine word length specific because of the port name parameter and the returned port names.

The mach_port_type function returns information about task 's rights for a specific name in its port name space. The returned ptype is a bit-mask indicating what rights task holds with this name. The bit-mask is composed of the following bits: MACH_PORT_TYPE_SEND The name denotes send rights. MACH_PORT_TYPE_RECEIVE The name denotes a receive right. MACH_PORT_TYPE_SEND_ONCE The name denotes a send-once right. MACH_PORT_TYPE_PORT_SET The name denotes a port set. MACH_PORT_TYPE_DEAD_NAME The name is a dead name. MACH_PORT_TYPE_DNREQUEST A dead-name request has been registered for the right.

Notes. This interface is machine word length specific because of the port name parameter.

The mach_port_allocate_name function creates a new right in the specified task, with a specified name for the new right.

Notes. This interface is machine word length specific because of the port name parameter.

The mach_port_allocate function creates a new right in the specified task. The new right's name is returned in name. Ports that are allocated via this call do not support the full set of Mach port semantics; in particular, the kernel will not provide no-more-senders notification service requests on such ports. Any attempt to request no-more-senders notification service will generate an error. Use the mach_port_allocate_full interface to allocate ports that support the full set of Mach port semantics.

Notes. This interface is machine word length specific because of the port name parameter.

The mach_port_destroy function de-allocates all rights denoted by a name. The name becomes immediately available for reuse. For most purposes, mach_port_mod_refs and mach_port_deallocate are preferable. If name denotes a port set, then all members of the port set are implicitly removed from the port set. If name denotes a receive right that is a member of a port set, the receive right is implicitly removed from the port set. Remaining messages queued to the port are destroyed and extant send and send-once rights turn into dead names. If those send and send-once rights have dead-name requests registered, then dead-name notifications are generated for them. If name denotes a send-once right, then the destruction of the send-once right produces a send-once notification for the port. If name denotes a send-once, send, and/or receive right, and it has a dead-name request registered, then a port-deleted notification is generated (as opposed to a dead-name notification).

Notes. This interface is machine word length specific because of the port name parameter.

The mach_port_deallocate function releases a user reference for a right. It is an alternate form of mach_port_mod_refs that allows a task to release a user reference for a send or send-once right without failing if the port has died and the right is now actually a dead name. If name denotes a dead name, send right, or send-once right, then the right loses one user reference. If it only had one user reference, then the right is destroyed. If name does not denote an element in the port name space, the function returns success.

Notes. This interface is machine word length specific because of the port name parameter.

The mach_port_get_refs function returns the number of user references a task has for a right. If name denotes a right, but not the type of right specified, then zero is returned. Otherwise a positive number of user references is returned. Note a name may simultaneously denote send and receive rights. The number of references for send-once rights is always one.

Notes. This interface is machine word length specific because of the port name parameter.

The mach_port_mod_refs function requests that the number of user references a task has for a right be changed. This results in the right being destroyed, if the number of user references is changed to zero. The name parameter should denote the specified right. The number of user references for the right is changed by the amount delta, subject to the following restrictions: port sets, receive rights, and send-once rights may only have one user reference. The resulting number of user references can't be negative. If the resulting number of user references is zero, the effect is to de-allocate the right. For dead names and send rights, there is an implementation-defined maximum number of user references. If the call destroys the right, then the effect is as described for mach_port_destroy, with the exception that mach_port_destroy simultaneously destroys all the rights denoted by a name, while mach_port_mod_refs can only destroy one right. The name will be available for reuse if it only denoted the one right.

Notes. This interface is machine word length specific because of the port name parameter.

The mach_port_set_mscount function changes the make-send count of task 's receive right named name. A port's make-send count specifies the number of send rights that have been generated via the port's receive right. A port's make-send count is set to zero when the port is first allocated; the count is reset to zero each time the port's receive right is transferred via a Mach message.

Notes. This interface is machine word length specific because of the port name parameter.

The mach_port_get_set_status function returns the individual port right names for all port rights contained in the specified port set. The members parameter is an array that is automatically allocated when the reply message is received. Note that vm_deallocate should be used to free the array. Note that this interface, unlike others such as task_threads, returns a collection of port right names, NOT a collection of port rights themselves. In other words, this function does not insert port rights into the caller's port right name space; consequently, a call to mach_port_get_set_status does not affect the reference count of each port right within the target port set.

Notes. This interface is machine word length specific because of the port name parameter and the returned port names.

The mach_port_move_member function moves a receive right into a port set. If the receive right is already a member of any other port sets, it is removed from those sets first. If the port set is MACH_PORT_NULL, then the receive right is not put into a port set, but removed from all its current port sets.

Notes. This interface is machine word length specific because of the port name parameter.

The mach_port_request_notification function registers a request for a notification and supplies a send-once right that the notification will use. It is an atomic swap, returning the previously registered send-once right (or MACH_PORT_NULL for none). A notification request may be cancelled by providing MACH_PORT_NULL. The variant argument takes the following values: MACH_NOTIFY_PORT_DESTROYED sync must be zero. The name must specify a receive right, and the call requests a port-destroyed notification for the receive right. If the receive right were to have been destroyed, for instance by mach_port_destroy, then instead the receive right will be sent in a port-destroyed notification to the registered send-once right. MACH_NOTIFY_DEAD_NAME The call requests a dead-name notification. name specifies send, receive, or send-once rights for a port. If the port is destroyed (and the right remains, becoming a dead name), then a dead-name notification which carries the name of the right will be sent to the registered send-once right. If sync is non-zero, the name may specify a dead name, and a dead-name notification is immediately generated. Whenever a dead-name notification is generated, the user reference count of the dead name is incremented. For example, a send right with two user refs has a registered dead-name request. If the port is destroyed, the send right turns into a dead name with three user refs (instead of two), and a dead-name notification is generated. If the name is made available for reuse, perhaps because of mach_port_destroy or mach_port_mod_refs, or the name denotes a send-once right which has a message sent to it, then the registered send-once right is used to generate a port-deleted notification instead. MACH_NOTIFY_NO_SENDERS The call requests a no-senders notification. name must specify a receive right. If the receive right's make-send count is greater than or equal to the sync value, and it has no extant send rights, than an immediate no-senders notification is generated. Otherwise the notification is generated when the receive right next loses its last extant send right. In either case, any previously registered send-once right is returned. The no-senders notification carries the value the port's make-send count had when it was generated. The make-send count is incremented whenever a send right is made directly from a receive right. The make-send count is reset to zero when the receive right is carried in a message. When moving a receive right, no-senders notifications are canceled, with a send-once notification sent to indicate the cancelation.

Notes. This interface is machine word length specific because of the port name parameter.

The mach_port_insert_right function inserts into task the caller's right for a port, using a specified name for the right in the target task. The specified name can't be one of the reserved values MACH_PORT_NULL or MACH_PORT_DEAD. The right can't be MACH_PORT_NULL or MACH_PORT_DEAD. The argument right_type specifies a right to be inserted and how that right should be extracted from the caller. It should be a value appropriate for mach_msg. If right_type is MACH_MSG_TYPE_MAKE_SEND, MACH_MSG_TYPE_MOVE_SEND, or MACH_MSG_TYPE_COPY_SEND, then a send right is inserted. If the target already holds send or receive rights for the port, then name should denote those rights in the target. Otherwise, name should be unused in the target. If the target already has send rights, then those send rights gain an additional user reference. Otherwise, the target gains a send right, with a user reference count of one. If right_type is MACH_MSG_TYPE_MAKE_SEND_ONCE or MACH_MSG_TYPE_MOVE_SEND_ONCE, then a send-once right is inserted. The name should be unused in the target. The target gains a send-once right. If right_type is MACH_MSG_TYPE_MOVE_RECEIVE, then a receive right is inserted. If the target already holds send rights for the port, then name should denote those rights in the target. Otherwise, name should be unused in the target. The receive right is moved into the target task.

Notes. This interface is machine word length specific because of the port name parameter.

The mach_port_extract_right function extracts a port right from the target task and returns it to the caller as if the task sent the right voluntarily, using desired_type as the disposition for the right. See mach_msg. The returned value of acquired_type will be MACH_MSG_TYPE_PORT_SEND if a send right is extracted, MACH_MSG_TYPE_PORT_RECEIVE if a receive right is extracted, and MACH_MSG_TYPE_PORT_SEND_ONCE if a send-once right is extracted.

Notes. This interface is machine word length specific because of the port name parameter.

The mach_port_set_seqno function changes the sequence number of task 's receive right named name. (Each port is associated with a sequence number attribute that can be used to track the order in which messages sent to the port are received. A port's sequence number is initially set to zero and is incremented each time a message is received from the port. A port's sequence number is automatically reset to zero each time the port's receive right migrates.)

Notes. This interface is machine word length specific because of the port name parameter.

The mach_port_get_attributes function returns an information structure of type flavor.

Notes. This interface is machine word length specific because of the port name parameter in the MACH_PORT_RECEIVE_STATUS structure return.

The mach_port_set_attributes function sets attributes of type flavor.

Notes. This interface is machine word length specific because of the port name parameter.

The mach_port_allocate_qos function allocates a port with caller-specified "quality of service" characteristics with or without a caller-specified name; in other words, the caller may specify a desired name or it may let the kernel generate the name. The new port is capable of supporting full Mach port semantics (i.e no-more-senders notification can be requested on the port).

Notes. This interface is machine word length specific because of the port name parameter.

The mach_port_allocate_full function creates a new right in the specified task. The new right's name is returned via the name parameter. The new port supports the full set of Mach port semantics (i.e. no_more_senders detection will work, if requested).

Notes. This interface is machine word length specific because of the port name parameter.

The task_set_port_space function preallocates the specified number of entries in the specified task's IPC name space.