home *** CD-ROM | disk | FTP | other *** search
/ H4CK3R 4 / hacker04 / 04_HACK04.ISO / darwin / darwinx86.iso / usr / include / mach / mach_port.defs < prev    next >
Encoding:
Text File  |  2001-09-30  |  12.7 KB  |  457 lines
  1. /*
  2.  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
  3.  *
  4.  * @APPLE_LICENSE_HEADER_START@
  5.  * 
  6.  * The contents of this file constitute Original Code as defined in and
  7.  * are subject to the Apple Public Source License Version 1.1 (the
  8.  * "License").  You may not use this file except in compliance with the
  9.  * License.  Please obtain a copy of the License at
  10.  * http://www.apple.com/publicsource and read it before using this file.
  11.  * 
  12.  * This Original Code and all software distributed under the License are
  13.  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14.  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15.  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16.  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17.  * License for the specific language governing rights and limitations
  18.  * under the License.
  19.  * 
  20.  * @APPLE_LICENSE_HEADER_END@
  21.  */
  22. /*
  23.  * @OSF_FREE_COPYRIGHT@
  24.  */
  25. /* 
  26.  * Mach Operating System
  27.  * Copyright (c) 1991,1990,1989 Carnegie Mellon University
  28.  * All Rights Reserved.
  29.  * 
  30.  * Permission to use, copy, modify and distribute this software and its
  31.  * documentation is hereby granted, provided that both the copyright
  32.  * notice and this permission notice appear in all copies of the
  33.  * software, derivative works or modified versions, and any portions
  34.  * thereof, and that both notices appear in supporting documentation.
  35.  * 
  36.  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
  37.  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
  38.  * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  39.  * 
  40.  * Carnegie Mellon requests users of this software to return to
  41.  * 
  42.  *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
  43.  *  School of Computer Science
  44.  *  Carnegie Mellon University
  45.  *  Pittsburgh PA 15213-3890
  46.  * 
  47.  * any improvements or extensions that they make and grant Carnegie Mellon
  48.  * the rights to redistribute these changes.
  49.  */
  50. /*
  51.  */
  52. /*
  53.  *    File:    mach/mach_port.defs
  54.  *    Author:    Rich Draves
  55.  *
  56.  *    Exported kernel calls.
  57.  */
  58.  
  59. subsystem
  60. #if    KERNEL_SERVER
  61.       KernelServer
  62. #endif    KERNEL_SERVER
  63.       mach_port 3200;
  64.  
  65. #include <mach/std_types.defs>
  66. #include <mach/mach_types.defs>
  67. #include <mach_debug/mach_debug_types.defs>
  68.  
  69. /*
  70.  *    Returns the set of port and port set names
  71.  *    to which the target task has access, along with
  72.  *    the type (set or port) for each name.
  73.  */
  74.  
  75. routine mach_port_names(
  76.         task        : ipc_space_t;
  77.     out    names        : mach_port_name_array_t;
  78.     out    types        : mach_port_type_array_t);
  79.  
  80. /*
  81.  *    Returns the type (set or port) for the port name
  82.  *    within the target task.  Also indicates whether
  83.  *    there is a dead-name request for the name.
  84.  */
  85.  
  86. routine mach_port_type(
  87.         task        : ipc_space_t;
  88.         name        : mach_port_name_t;
  89.     out    ptype        : mach_port_type_t);
  90.  
  91. /*
  92.  *    Changes the name by which a port (or port set) is known to
  93.  *    the target task.  The new name can't be in use.  The
  94.  *    old name becomes available for recycling.
  95.  */
  96.  
  97. routine mach_port_rename(
  98.         task        : ipc_space_t;
  99.         old_name    : mach_port_name_t;
  100.         new_name    : mach_port_name_t);
  101.  
  102. /*
  103.  *    Allocates the specified kind of object, with the given name.
  104.  *    The right must be one of
  105.  *        MACH_PORT_RIGHT_RECEIVE
  106.  *        MACH_PORT_RIGHT_PORT_SET
  107.  *        MACH_PORT_RIGHT_DEAD_NAME
  108.  *    New port sets are empty.  New ports don't have any
  109.  *    send/send-once rights or queued messages.  The make-send
  110.  *    count is zero and their queue limit is MACH_PORT_QLIMIT_DEFAULT.
  111.  *    New sets, ports, and dead names have one user reference.
  112.  */
  113.  
  114. routine mach_port_allocate_name(
  115.         task        : ipc_space_t;
  116.         right        : mach_port_right_t;
  117.         name        : mach_port_name_t);
  118.  
  119. /*
  120.  *    Allocates the specified kind of object.
  121.  *    The right must be one of
  122.  *        MACH_PORT_RIGHT_RECEIVE
  123.  *        MACH_PORT_RIGHT_PORT_SET
  124.  *        MACH_PORT_RIGHT_DEAD_NAME
  125.  *    Like port_allocate_name, but the kernel picks a name.
  126.  *    It can use any name not associated with a right.
  127.  */
  128.  
  129. routine mach_port_allocate(
  130.         task        : ipc_space_t;
  131.         right        : mach_port_right_t;
  132.     out    name        : mach_port_name_t);
  133.  
  134. /*
  135.  *    Destroys all rights associated with the name and makes it
  136.  *    available for recycling immediately.  The name can be a
  137.  *    port (possibly with multiple user refs), a port set, or
  138.  *    a dead name (again, with multiple user refs).
  139.  */
  140.  
  141. routine mach_port_destroy(
  142.         task        : ipc_space_t;
  143.         name        : mach_port_name_t);
  144.  
  145. /*
  146.  *    Releases one send/send-once/dead-name user ref.
  147.  *    Just like mach_port_mod_refs -1, but deduces the
  148.  *    correct type of right.  This allows a user task
  149.  *    to release a ref for a port without worrying
  150.  *    about whether the port has died or not.
  151.  */
  152.  
  153. routine mach_port_deallocate(
  154.         task        : ipc_space_t;
  155.         name        : mach_port_name_t);
  156.  
  157. /*
  158.  *    A port set always has one user ref.
  159.  *    A send-once right always has one user ref.
  160.  *    A dead name always has one or more user refs.
  161.  *    A send right always has one or more user refs.
  162.  *    A receive right always has one user ref.
  163.  *    The right must be one of
  164.  *        MACH_PORT_RIGHT_RECEIVE
  165.  *        MACH_PORT_RIGHT_PORT_SET
  166.  *        MACH_PORT_RIGHT_DEAD_NAME
  167.  *        MACH_PORT_RIGHT_SEND
  168.  *        MACH_PORT_RIGHT_SEND_ONCE
  169.  */
  170.  
  171. routine mach_port_get_refs(
  172.         task        : ipc_space_t;
  173.         name        : mach_port_name_t;
  174.         right        : mach_port_right_t;
  175.     out    refs        : mach_port_urefs_t);
  176.  
  177. /*
  178.  *    The delta is a signed change to the task's
  179.  *    user ref count for the right.  Only dead names
  180.  *    and send rights can have a positive delta.
  181.  *    The resulting user ref count can't be negative.
  182.  *    If it is zero, the right is deallocated.
  183.  *    If the name isn't a composite right, it becomes
  184.  *    available for recycling.  The right must be one of
  185.  *        MACH_PORT_RIGHT_RECEIVE
  186.  *        MACH_PORT_RIGHT_PORT_SET
  187.  *        MACH_PORT_RIGHT_DEAD_NAME
  188.  *        MACH_PORT_RIGHT_SEND
  189.  *        MACH_PORT_RIGHT_SEND_ONCE
  190.  */
  191.  
  192. routine mach_port_mod_refs(
  193.         task        : ipc_space_t;
  194.         name        : mach_port_name_t;
  195.         right        : mach_port_right_t;
  196.         delta        : mach_port_delta_t);
  197.  
  198. /*
  199.  *      Allocates a new receive right, and associates it with the
  200.  *    specified RPC subsystem attributes.
  201.  */
  202. routine mach_port_allocate_subsystem(
  203.         task        : ipc_space_t;
  204.         subsys        : subsystem_t;
  205.     out    name        : mach_port_name_t);
  206.  
  207. /*
  208.  *    Only valid for receive rights.
  209.  *    Sets the make-send count for the port.
  210.  */
  211. routine mach_port_set_mscount(
  212.         task        : ipc_space_t;
  213.         name        : mach_port_name_t;
  214.         mscount        : mach_port_mscount_t);
  215.  
  216. /*
  217.  *    Only valid for port sets.  Returns a list of
  218.  *    the members.
  219.  */
  220.  
  221. routine mach_port_get_set_status(
  222.         task        : ipc_space_t;
  223.         name        : mach_port_name_t;
  224.     out    members        : mach_port_name_array_t);
  225.  
  226. /*
  227.  *    Puts the member port (the task must have receive rights)
  228.  *    into the after port set.  (Or removes it from any port set
  229.  *    if after is MACH_PORT_NULL.)  If the port is already in
  230.  *    a set, does an atomic move.
  231.  */
  232.  
  233. routine mach_port_move_member(
  234.         task        : ipc_space_t;
  235.         member        : mach_port_name_t;
  236.         after        : mach_port_name_t);
  237.  
  238. /*
  239.  *    Requests a notification from the kernel.  The request
  240.  *    must supply the send-once right which is used for
  241.  *    the notification.  If a send-once right was previously
  242.  *    registered, it is returned.  The msg_id must be one of
  243.  *        MACH_NOTIFY_PORT_DESTROYED (receive rights)
  244.  *        MACH_NOTIFY_DEAD_NAME (send/receive/send-once rights)
  245.  *        MACH_NOTIFY_NO_SENDERS (receive rights)
  246.  *
  247.  *    The sync value specifies whether a notification should
  248.  *    get sent immediately, if appropriate.  The exact meaning
  249.  *    depends on the notification:
  250.  *        MACH_NOTIFY_PORT_DESTROYED: must be zero.
  251.  *        MACH_NOTIFY_DEAD_NAME: if non-zero, then name can be dead,
  252.  *            and the notification gets sent immediately.
  253.  *            If zero, then name can't be dead.
  254.  *        MACH_NOTIFY_NO_SENDERS: the notification gets sent
  255.  *            immediately if the current mscount is greater
  256.  *            than or equal to the sync value and there are no
  257.  *            extant send rights.
  258.  */
  259.  
  260. routine mach_port_request_notification(
  261.         task        : ipc_space_t;
  262.         name        : mach_port_name_t;
  263.         msgid        : mach_msg_id_t;
  264.         sync        : mach_port_mscount_t;
  265.         notify        : mach_port_send_once_t;
  266.     out    previous    : mach_port_move_send_once_t);
  267.  
  268. /*
  269.  *    Inserts the specified rights into the target task,
  270.  *    using the specified name.  If inserting send/receive
  271.  *    rights and the task already has send/receive rights
  272.  *    for the port, then the names must agree.  In any case,
  273.  *    the task gains a user ref for the port.
  274.  */
  275.  
  276. routine mach_port_insert_right(
  277.         task        : ipc_space_t;
  278.         name        : mach_port_name_t;
  279.         poly        : mach_port_poly_t);
  280.  
  281. /*
  282.  *    Returns the specified right for the named port
  283.  *    in the target task, extracting that right from
  284.  *    the target task.  The target task loses a user
  285.  *    ref and the name may be available for recycling.
  286.  *    msgt_name must be one of
  287.  *        MACH_MSG_TYPE_MOVE_RECEIVE
  288.  *        MACH_MSG_TYPE_COPY_SEND
  289.  *        MACH_MSG_TYPE_MAKE_SEND
  290.  *        MACH_MSG_TYPE_MOVE_SEND
  291.  *        MACH_MSG_TYPE_MAKE_SEND_ONCE
  292.  *        MACH_MSG_TYPE_MOVE_SEND_ONCE
  293.  */
  294.  
  295. routine mach_port_extract_right(
  296.         task        : ipc_space_t;
  297.         name        : mach_port_name_t;
  298.         msgt_name    : mach_msg_type_name_t;
  299.     out    poly        : mach_port_poly_t);
  300.  
  301. /*
  302.  *    Only valid for receive rights.
  303.  *    Sets the sequence number for the port.
  304.  */
  305.  
  306. routine mach_port_set_seqno(
  307.         task        : ipc_space_t;
  308.         name        : mach_port_name_t;
  309.         seqno        : mach_port_seqno_t);
  310.  
  311. /*
  312.  *      Returns information about a port.
  313.  */
  314.  
  315. routine mach_port_get_attributes(
  316.         task        : ipc_space_t;
  317.         name        : mach_port_name_t;
  318.         flavor        : mach_port_flavor_t;
  319.     out    port_info_out    : mach_port_info_t, CountInOut);
  320.  
  321. /*
  322.  *      Set attributes of a port
  323.  */
  324.  
  325. routine mach_port_set_attributes(
  326.         task        : ipc_space_t;
  327.         name        : mach_port_name_t;
  328.         flavor        : mach_port_flavor_t;
  329.         port_info    : mach_port_info_t);
  330.  
  331.  
  332. /*
  333.  *    Allocates the specified kind of object, qos version.
  334.  *    The right must be
  335.  *        MACH_PORT_RIGHT_RECEIVE
  336.  *    Like port_allocate_name, but the kernel picks a name.
  337.  *    It can use any name not associated with a right.
  338.  */
  339.  
  340. routine mach_port_allocate_qos(
  341.         task        : ipc_space_t;
  342.         right        : mach_port_right_t;
  343.     inout    qos        : mach_port_qos_t;
  344.     out    name        : mach_port_name_t);
  345.  
  346. /*
  347.  *    Generic interface to allocation various kinds of ports.
  348.  *    Should never be called directly by users (at least not
  349.  *    unless they are exceedingly masochistic).
  350.  */
  351.  
  352. routine mach_port_allocate_full(
  353.         task        : ipc_space_t;
  354.         right        : mach_port_right_t;
  355.         subs        : subsystem_t;
  356.     inout    qos        : mach_port_qos_t;
  357.     inout    name        : mach_port_name_t);
  358.  
  359.  
  360. /*
  361.  *    Pre-expand task port name space.
  362.  */
  363. routine task_set_port_space(
  364.         task        : ipc_space_t;
  365.         table_entries    : int);
  366.  
  367.  
  368. /*
  369.  *    Returns the exact number of extant send rights
  370.  *    for the given receive right.
  371.  *      This call is only valid on MACH_IPC_DEBUG kernels.
  372.  *      Otherwise, KERN_FAILURE is returned.
  373.  */
  374. routine    mach_port_get_srights(
  375.         task        : ipc_space_t;
  376.         name        : mach_port_name_t;
  377.     out    srights        : mach_port_rights_t);
  378.  
  379.  
  380. /*
  381.  *    Returns information about an IPC space.
  382.  *      This call is only valid on MACH_IPC_DEBUG kernels.
  383.  *      Otherwise, KERN_FAILURE is returned.
  384.  */
  385. routine mach_port_space_info(
  386.         task        : ipc_space_t;
  387.     out    info        : ipc_info_space_t;
  388.     out    table_info    : ipc_info_name_array_t,
  389.                     Dealloc;
  390.     out    tree_info    : ipc_info_tree_name_array_t,
  391.                     Dealloc);
  392.  
  393. /*
  394.  *    Returns information about the dead-name requests
  395.  *    registered with the named receive right.
  396.  *      This call is only valid on MACH_IPC_DEBUG kernels.
  397.  *      Otherwise, KERN_FAILURE is returned.
  398.  */
  399. routine mach_port_dnrequest_info(
  400.         task        : ipc_space_t;
  401.         name        : mach_port_name_t;
  402.     out    total        : unsigned;    /* total size of table */
  403.     out    used        : unsigned);    /* amount used */
  404.  
  405. /*
  406.  *    Return the type and address of the kernel object
  407.  *    that the given send/receive right represents.
  408.  *      This call is only valid on MACH_IPC_DEBUG kernels.
  409.  *      Otherwise, KERN_FAILURE is returned.
  410.  */
  411. routine    mach_port_kernel_object(
  412.         task        : ipc_space_t;
  413.         name        : mach_port_name_t;
  414.     out    object_type    : unsigned;
  415.     out    object_addr    : vm_offset_t);
  416.  
  417.  
  418. /*
  419.  *    Inserts the specified rights into the portset identified
  420.  *    by the <task, pset> pair.  The results of passing in the
  421.  *    Poly argument via the supplied disposition must yield a
  422.  *    receive right.
  423.  *
  424.  *    If the <task,pset> pair does not represent a valid portset
  425.  *    KERN_INVALID_RIGHT is returned.
  426.  *    
  427.  *    If the passed in name argument does not represent a receive
  428.  *    right, KERN_INVALID_CAPABILITY will be returned.
  429.  *
  430.  *    If the port represented by the receive right is already in
  431.  *    the portset, KERN_ALREADY_IN_SET is returned.
  432.  */
  433. routine mach_port_insert_member(
  434.         task        : ipc_space_t;
  435.         name        : mach_port_name_t;
  436.         pset        : mach_port_name_t);
  437.  
  438. /*
  439.  *    Extracts the specified right from the named portset
  440.  *    in the target task.  
  441.  *    the target task.  The target task loses a user
  442.  *    ref and the name may be available for recycling.
  443.  *    msgt_name must be one of
  444.  *        MACH_MSG_TYPE_MOVE_RECEIVE
  445.  *        MACH_MSG_TYPE_COPY_SEND
  446.  *        MACH_MSG_TYPE_MAKE_SEND
  447.  *        MACH_MSG_TYPE_MOVE_SEND
  448.  *        MACH_MSG_TYPE_MAKE_SEND_ONCE
  449.  *        MACH_MSG_TYPE_MOVE_SEND_ONCE
  450.  */
  451.  
  452. routine mach_port_extract_member(
  453.         task        : ipc_space_t;
  454.         name        : mach_port_name_t;
  455.         pset        : mach_port_name_t);
  456.  
  457.