home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / NextDeveloper / Headers / mach / mach_port.defs < prev    next >
Text File  |  1994-11-14  |  10KB  |  342 lines
  1. /* 
  2.  * Mach Operating System
  3.  * Copyright (c) 1991,1990,1989 Carnegie Mellon University
  4.  * All Rights Reserved.
  5.  * 
  6.  * Permission to use, copy, modify and distribute this software and its
  7.  * documentation is hereby granted, provided that both the copyright
  8.  * notice and this permission notice appear in all copies of the
  9.  * software, derivative works or modified versions, and any portions
  10.  * thereof, and that both notices appear in supporting documentation.
  11.  * 
  12.  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
  13.  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
  14.  * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  15.  * 
  16.  * Carnegie Mellon requests users of this software to return to
  17.  * 
  18.  *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
  19.  *  School of Computer Science
  20.  *  Carnegie Mellon University
  21.  *  Pittsburgh PA 15213-3890
  22.  * 
  23.  * any improvements or extensions that they make and grant Carnegie Mellon
  24.  * the rights to redistribute these changes.
  25.  */
  26. /*
  27.  * HISTORY
  28.  * $Log:    mach_port.defs,v $
  29.  * Revision 2.6  92/01/14  16:45:25  rpd
  30.  *     Changed mach_port_{name,type}_array_t usages to remain compatible,
  31.  *     because the definition of the types changed incompatibly.
  32.  *     [92/01/13            rpd]
  33.  * 
  34.  * Revision 2.5  91/08/28  11:15:13  jsb
  35.  *     Added mach_port_set_seqno.  Moved mach_port_get_receive_status
  36.  *     to a new id, renaming the old call old_mach_port_get_receive_status.
  37.  *     [91/08/09            rpd]
  38.  * 
  39.  * Revision 2.4  91/05/14  16:54:47  mrt
  40.  *     Correcting copyright
  41.  * 
  42.  * Revision 2.3  91/02/05  17:33:31  mrt
  43.  *     Changed to new Mach copyright
  44.  *     [91/02/01  17:18:11  mrt]
  45.  * 
  46.  * Revision 2.2  90/06/02  14:58:25  rpd
  47.  *     Modified mach_port_get_receive_status to return
  48.  *     a status structure (mach_port_status_t).
  49.  *     Updated mach_port_set_qlimit comment.
  50.  *     [90/05/13            rpd]
  51.  *     Created for new IPC.
  52.  *     [90/03/26  23:45:32  rpd]
  53.  * 
  54.  */
  55. /*
  56.  *    File:    mach/mach_port.defs
  57.  *    Author:    Rich Draves
  58.  *
  59.  *    Copyright (c) 1989 Richard P. Draves, Jr.
  60.  *
  61.  *    Exported kernel calls.
  62.  */
  63.  
  64. subsystem
  65. #if    KERNEL_SERVER
  66.       KernelServer
  67. #endif    KERNEL_SERVER
  68.                mach_port 3200;
  69.  
  70. #include <mach/std_types.defs>
  71. #include <mach/mach_types.defs>
  72.  
  73. /*
  74.  *    Returns the set of port and port set names
  75.  *    to which the target task has access, along with
  76.  *    the type (set or port) for each name.
  77.  */
  78.  
  79. routine mach_port_names(
  80.         task        : ipc_space_t;
  81.     out    names        : mach_port_name_array_t =
  82.                     ^array[] of mach_port_name_t
  83.                     ctype: mach_port_array_t;
  84.     out    types        : mach_port_type_array_t =
  85.                     ^array[] of mach_port_type_t);
  86.  
  87. /*
  88.  *    Returns the type (set or port) for the port name
  89.  *    within the target task.  Also indicates whether
  90.  *    there is a dead-name request for the name.
  91.  */
  92.  
  93. routine mach_port_type(
  94.         task        : ipc_space_t;
  95.         name        : mach_port_name_t;
  96.     out    ptype        : mach_port_type_t);
  97.  
  98. /*
  99.  *    Changes the name by which a port (or port set) is known to
  100.  *    the target task.  The new name can't be in use.  The
  101.  *    old name becomes available for recycling.
  102.  */
  103.  
  104. routine mach_port_rename(
  105.         task        : ipc_space_t;
  106.         old_name    : mach_port_name_t;
  107.         new_name    : mach_port_name_t);
  108.  
  109. /*
  110.  *    Allocates the specified kind of object, with the given name.
  111.  *    The right must be one of
  112.  *        MACH_PORT_RIGHT_RECEIVE
  113.  *        MACH_PORT_RIGHT_PORT_SET
  114.  *        MACH_PORT_RIGHT_DEAD_NAME
  115.  *    New port sets are empty.  New ports don't have any
  116.  *    send/send-once rights or queued messages.  The make-send
  117.  *    count is zero and their queue limit is MACH_PORT_QLIMIT_DEFAULT.
  118.  *    New sets, ports, and dead names have one user reference.
  119.  */
  120.  
  121. routine mach_port_allocate_name(
  122.         task        : ipc_space_t;
  123.         right        : mach_port_right_t;
  124.         name        : mach_port_name_t);
  125.  
  126. /*
  127.  *    Allocates the specified kind of object.
  128.  *    The right must be one of
  129.  *        MACH_PORT_RIGHT_RECEIVE
  130.  *        MACH_PORT_RIGHT_PORT_SET
  131.  *        MACH_PORT_RIGHT_DEAD_NAME
  132.  *    Like port_allocate_name, but the kernel picks a name.
  133.  *    It can use any name not associated with a right.
  134.  */
  135.  
  136. routine mach_port_allocate(
  137.         task        : ipc_space_t;
  138.         right        : mach_port_right_t;
  139.     out    name        : mach_port_name_t);
  140.  
  141. /*
  142.  *    Destroys all rights associated with the name and makes it
  143.  *    available for recycling immediately.  The name can be a
  144.  *    port (possibly with multiple user refs), a port set, or
  145.  *    a dead name (again, with multiple user refs).
  146.  */
  147.  
  148. routine mach_port_destroy(
  149.         task        : ipc_space_t;
  150.         name        : mach_port_name_t);
  151.  
  152. /*
  153.  *    Releases one send/send-once/dead-name user ref.
  154.  *    Just like mach_port_mod_refs -1, but deduces the
  155.  *    correct type of right.  This allows a user task
  156.  *    to release a ref for a port without worrying
  157.  *    about whether the port has died or not.
  158.  */
  159.  
  160. routine mach_port_deallocate(
  161.         task        : ipc_space_t;
  162.         name        : mach_port_name_t);
  163.  
  164. /*
  165.  *    A port set always has one user ref.
  166.  *    A send-once right always has one user ref.
  167.  *    A dead name always has one or more user refs.
  168.  *    A send right always has one or more user refs.
  169.  *    A receive right always has one user ref.
  170.  *    The right must be one of
  171.  *        MACH_PORT_RIGHT_RECEIVE
  172.  *        MACH_PORT_RIGHT_PORT_SET
  173.  *        MACH_PORT_RIGHT_DEAD_NAME
  174.  *        MACH_PORT_RIGHT_SEND
  175.  *        MACH_PORT_RIGHT_SEND_ONCE
  176.  */
  177.  
  178. routine mach_port_get_refs(
  179.         task        : ipc_space_t;
  180.         name        : mach_port_name_t;
  181.         right        : mach_port_right_t;
  182.     out    refs        : mach_port_urefs_t);
  183.  
  184. /*
  185.  *    The delta is a signed change to the task's
  186.  *    user ref count for the right.  Only dead names
  187.  *    and send rights can have a positive delta.
  188.  *    The resulting user ref count can't be negative.
  189.  *    If it is zero, the right is deallocated.
  190.  *    If the name isn't a composite right, it becomes
  191.  *    available for recycling.  The right must be one of
  192.  *        MACH_PORT_RIGHT_RECEIVE
  193.  *        MACH_PORT_RIGHT_PORT_SET
  194.  *        MACH_PORT_RIGHT_DEAD_NAME
  195.  *        MACH_PORT_RIGHT_SEND
  196.  *        MACH_PORT_RIGHT_SEND_ONCE
  197.  */
  198.  
  199. routine mach_port_mod_refs(
  200.         task        : ipc_space_t;
  201.         name        : mach_port_name_t;
  202.         right        : mach_port_right_t;
  203.         delta        : mach_port_delta_t);
  204.  
  205. /*
  206.  *    Temporary compatibility call.
  207.  */
  208.  
  209. routine old_mach_port_get_receive_status(
  210.         task        : ipc_space_t;
  211.         name        : mach_port_name_t;
  212.     out    status        : old_mach_port_status_t);
  213.  
  214. /*
  215.  *    Only valid for receive rights.
  216.  *    Sets the queue-limit for the port.
  217.  *    The limit must be
  218.  *        1 <= qlimit <= MACH_PORT_QLIMIT_MAX
  219.  */
  220.  
  221. routine mach_port_set_qlimit(
  222.         task        : ipc_space_t;
  223.         name        : mach_port_name_t;
  224.         qlimit        : mach_port_msgcount_t);
  225.  
  226. /*
  227.  *    Only valid for receive rights.
  228.  *    Sets the make-send count for the port.
  229.  */
  230.  
  231. routine mach_port_set_mscount(
  232.         task        : ipc_space_t;
  233.         name        : mach_port_name_t;
  234.         mscount        : mach_port_mscount_t);
  235.  
  236. /*
  237.  *    Only valid for port sets.  Returns a list of
  238.  *    the members.
  239.  */
  240.  
  241. routine mach_port_get_set_status(
  242.         task        : ipc_space_t;
  243.         name        : mach_port_name_t;
  244.     out    members        : mach_port_name_array_t =
  245.                     ^array[] of mach_port_name_t
  246.                     ctype: mach_port_array_t);
  247.  
  248. /*
  249.  *    Puts the member port (the task must have receive rights)
  250.  *    into the after port set.  (Or removes it from any port set
  251.  *    if after is MACH_PORT_NULL.)  If the port is already in
  252.  *    a set, does an atomic move.
  253.  */
  254.  
  255. routine mach_port_move_member(
  256.         task        : ipc_space_t;
  257.         member        : mach_port_name_t;
  258.         after        : mach_port_name_t);
  259.  
  260. /*
  261.  *    Requests a notification from the kernel.  The request
  262.  *    must supply the send-once right which is used for
  263.  *    the notification.  If a send-once right was previously
  264.  *    registered, it is returned.  The msg_id must be one of
  265.  *        MACH_NOTIFY_PORT_DESTROYED (receive rights)
  266.  *        MACH_NOTIFY_DEAD_NAME (send/receive/send-once rights)
  267.  *        MACH_NOTIFY_NO_SENDERS (receive rights)
  268.  *
  269.  *    The sync value specifies whether a notification should
  270.  *    get sent immediately, if appropriate.  The exact meaning
  271.  *    depends on the notification:
  272.  *        MACH_NOTIFY_PORT_DESTROYED: must be zero.
  273.  *        MACH_NOTIFY_DEAD_NAME: if non-zero, then name can be dead,
  274.  *            and the notification gets sent immediately.
  275.  *            If zero, then name can't be dead.
  276.  *        MACH_NOTIFY_NO_SENDERS: the notification gets sent
  277.  *            immediately if the current mscount is greater
  278.  *            than or equal to the sync value and there are no
  279.  *            extant send rights.
  280.  */
  281.  
  282. routine mach_port_request_notification(
  283.         task        : ipc_space_t;
  284.         name        : mach_port_name_t;
  285.         id        : mach_msg_id_t;
  286.         sync        : mach_port_mscount_t;
  287.         notify        : mach_port_send_once_t;
  288.     out    previous    : mach_port_send_once_t);
  289.  
  290. /*
  291.  *    Inserts the specified rights into the target task,
  292.  *    using the specified name.  If inserting send/receive
  293.  *    rights and the task already has send/receive rights
  294.  *    for the port, then the names must agree.  In any case,
  295.  *    the task gains a user ref for the port.
  296.  */
  297.  
  298. routine mach_port_insert_right(
  299.         task        : ipc_space_t;
  300.         name        : mach_port_name_t;
  301.         poly        : mach_port_poly_t);
  302.  
  303. /*
  304.  *    Returns the specified right for the named port
  305.  *    in the target task, extracting that right from
  306.  *    the target task.  The target task loses a user
  307.  *    ref and the name may be available for recycling.
  308.  *    msgt_name must be one of
  309.  *        MACH_MSG_TYPE_MOVE_RECEIVE
  310.  *        MACH_MSG_TYPE_COPY_SEND
  311.  *        MACH_MSG_TYPE_MAKE_SEND
  312.  *        MACH_MSG_TYPE_MOVE_SEND
  313.  *        MACH_MSG_TYPE_MAKE_SEND_ONCE
  314.  *        MACH_MSG_TYPE_MOVE_SEND_ONCE
  315.  */
  316.  
  317. routine mach_port_extract_right(
  318.         task        : ipc_space_t;
  319.         name        : mach_port_name_t;
  320.         msgt_name    : mach_msg_type_name_t;
  321.     out    poly        : mach_port_poly_t);
  322.  
  323. /*
  324.  *    The task must have receive rights for the named port.
  325.  *    Returns a status structure (see mach/port.h).
  326.  */
  327.  
  328. routine mach_port_get_receive_status(
  329.         task        : ipc_space_t;
  330.         name        : mach_port_name_t;
  331.     out    status        : mach_port_status_t);
  332.  
  333. /*
  334.  *    Only valid for receive rights.
  335.  *    Sets the sequence number for the port.
  336.  */
  337.  
  338. routine mach_port_set_seqno(
  339.         task        : ipc_space_t;
  340.         name        : mach_port_name_t;
  341.         seqno        : mach_port_seqno_t);
  342.