osfmk/mach/message.h

   1 /*
   2  * Copyright (c) 2000-2005 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28 /*
  29  * @OSF_COPYRIGHT@
  30  */
  31 /*
  32  * Mach Operating System
  33  * Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University
  34  * All Rights Reserved.
  35  *
  36  * Permission to use, copy, modify and distribute this software and its
  37  * documentation is hereby granted, provided that both the copyright
  38  * notice and this permission notice appear in all copies of the
  39  * software, derivative works or modified versions, and any portions
  40  * thereof, and that both notices appear in supporting documentation.
  41  *
  42  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
  43  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
  44  * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  45  *
  46  * Carnegie Mellon requests users of this software to return to
  47  *
  48  *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
  49  *  School of Computer Science
  50  *  Carnegie Mellon University
  51  *  Pittsburgh PA 15213-3890
  52  *
  53  * any improvements or extensions that they make and grant Carnegie Mellon
  54  * the rights to redistribute these changes.
  55  */
  56 /*
  57  */
  58 /*
  59  *      File:   mach/message.h
  60  *
  61  *      Mach IPC message and primitive function definitions.
  62  */
  63
  64 #ifndef _MACH_MESSAGE_H_
  65 #define _MACH_MESSAGE_H_
  66
  67 #include <stdint.h>
  68 #include <mach/port.h>
  69 #include <mach/boolean.h>
  70 #include <mach/kern_return.h>
  71 #include <mach/machine/vm_types.h>
  72
  73 #include <sys/cdefs.h>
  74
  75 /*
  76  *  The timeout mechanism uses mach_msg_timeout_t values,
  77  *  passed by value.  The timeout units are milliseconds.
  78  *  It is controlled with the MACH_SEND_TIMEOUT
  79  *  and MACH_RCV_TIMEOUT options.
  80  */
  81
  82 typedef natural_t mach_msg_timeout_t;
  83
  84 /*
  85  *  The value to be used when there is no timeout.
  86  *  (No MACH_SEND_TIMEOUT/MACH_RCV_TIMEOUT option.)
  87  */
  88
  89 #define MACH_MSG_TIMEOUT_NONE           ((mach_msg_timeout_t) 0)
  90
  91 /*
  92  *  The kernel uses MACH_MSGH_BITS_COMPLEX as a hint.  It it isn't on, it
  93  *  assumes the body of the message doesn't contain port rights or OOL
  94  *  data.  The field is set in received messages.  A user task must
  95  *  use caution in interpreting the body of a message if the bit isn't
  96  *  on, because the mach_msg_type's in the body might "lie" about the
  97  *  contents.  If the bit isn't on, but the mach_msg_types
  98  *  in the body specify rights or OOL data, the behavior is undefined.
  99  *  (Ie, an error may or may not be produced.)
 100  *
 101  *  The value of MACH_MSGH_BITS_REMOTE determines the interpretation
 102  *  of the msgh_remote_port field.  It is handled like a msgt_name.
 103  *
 104  *  The value of MACH_MSGH_BITS_LOCAL determines the interpretation
 105  *  of the msgh_local_port field.  It is handled like a msgt_name.
 106  *
 107  *  MACH_MSGH_BITS() combines two MACH_MSG_TYPE_* values, for the remote
 108  *  and local fields, into a single value suitable for msgh_bits.
 109  *
 110  *  MACH_MSGH_BITS_CIRCULAR should be zero; is is used internally.
 111  *
 112  *  The unused bits should be zero and are reserved for the kernel
 113  *  or for future interface expansion.
 114  */
 115
 116 #define MACH_MSGH_BITS_ZERO             0x00000000
 117 #define MACH_MSGH_BITS_REMOTE_MASK      0x000000ff
 118 #define MACH_MSGH_BITS_LOCAL_MASK       0x0000ff00
 119 #define MACH_MSGH_BITS_COMPLEX          0x80000000U
 120 #define MACH_MSGH_BITS_USER             0x8000ffffU
 121
 122 #define MACH_MSGH_BITS_CIRCULAR         0x40000000      /* internal use only */
 123 #define MACH_MSGH_BITS_USED             0xc000ffffU
 124
 125 #define MACH_MSGH_BITS_PORTS_MASK                               \
 126                 (MACH_MSGH_BITS_REMOTE_MASK|MACH_MSGH_BITS_LOCAL_MASK)
 127
 128 #define MACH_MSGH_BITS(remote, local)                           \
 129                 ((remote) | ((local) << 8))
 130 #define MACH_MSGH_BITS_REMOTE(bits)                             \
 131                 ((bits) & MACH_MSGH_BITS_REMOTE_MASK)
 132 #define MACH_MSGH_BITS_LOCAL(bits)                              \
 133                 (((bits) & MACH_MSGH_BITS_LOCAL_MASK) >> 8)
 134 #define MACH_MSGH_BITS_PORTS(bits)                              \
 135                 ((bits) & MACH_MSGH_BITS_PORTS_MASK)
 136 #define MACH_MSGH_BITS_OTHER(bits)                              \
 137                 ((bits) &~ MACH_MSGH_BITS_PORTS_MASK)
 138
 139 /*
 140  *  Every message starts with a message header.
 141  *  Following the message header are zero or more pairs of
 142  *  type descriptors (mach_msg_type_t/mach_msg_type_long_t) and
 143  *  data values.  The size of the message must be specified in bytes,
 144  *  and includes the message header, type descriptors, inline
 145  *  data, and inline pointer for out-of-line data.
 146  *
 147  *  The msgh_remote_port field specifies the destination of the message.
 148  *  It must specify a valid send or send-once right for a port.
 149  *
 150  *  The msgh_local_port field specifies a "reply port".  Normally,
 151  *  This field carries a send-once right that the receiver will use
 152  *  to reply to the message.  It may carry the values MACH_PORT_NULL,
 153  *  MACH_PORT_DEAD, a send-once right, or a send right.
 154  *
 155  *  The msgh_seqno field carries a sequence number associated with the
 156  *  received-from port.  A port's sequence number is incremented every
 157  *  time a message is received from it.  In sent messages, the field's
 158  *  value is ignored.
 159  *
 160  *  The msgh_id field is uninterpreted by the message primitives.
 161  *  It normally carries information specifying the format
 162  *  or meaning of the message.
 163  */
 164
 165 typedef unsigned int mach_msg_bits_t;
 166 typedef natural_t mach_msg_size_t;
 167 typedef integer_t mach_msg_id_t;
 168
 169
 170 #define MACH_MSG_SIZE_NULL (mach_msg_size_t *) 0
 171
 172 typedef unsigned int mach_msg_type_name_t;
 173
 174 #define MACH_MSG_TYPE_MOVE_RECEIVE      16      /* Must hold receive rights */
 175 #define MACH_MSG_TYPE_MOVE_SEND         17      /* Must hold send rights */
 176 #define MACH_MSG_TYPE_MOVE_SEND_ONCE    18      /* Must hold sendonce rights */
 177 #define MACH_MSG_TYPE_COPY_SEND         19      /* Must hold send rights */
 178 #define MACH_MSG_TYPE_MAKE_SEND         20      /* Must hold receive rights */
 179 #define MACH_MSG_TYPE_MAKE_SEND_ONCE    21      /* Must hold receive rights */
 180 #define MACH_MSG_TYPE_COPY_RECEIVE      22      /* Must hold receive rights */
 181
 182 typedef unsigned int mach_msg_copy_options_t;
 183
 184 #define MACH_MSG_PHYSICAL_COPY          0
 185 #define MACH_MSG_VIRTUAL_COPY           1
 186 #define MACH_MSG_ALLOCATE               2
 187 #define MACH_MSG_OVERWRITE              3
 188 #ifdef  MACH_KERNEL
 189 #define MACH_MSG_KALLOC_COPY_T          4
 190 #endif  /* MACH_KERNEL */
 191
 192 typedef unsigned int mach_msg_descriptor_type_t;
 193
 194 #define MACH_MSG_PORT_DESCRIPTOR                0
 195 #define MACH_MSG_OOL_DESCRIPTOR                 1
 196 #define MACH_MSG_OOL_PORTS_DESCRIPTOR           2
 197 #define MACH_MSG_OOL_VOLATILE_DESCRIPTOR        3
 198
 199 #pragma pack(4)
 200
 201 typedef struct
 202 {
 203   natural_t                     pad1;
 204   mach_msg_size_t               pad2;
 205   unsigned int                  pad3 : 24;
 206   mach_msg_descriptor_type_t    type : 8;
 207 } mach_msg_type_descriptor_t;
 208
 209 typedef struct
 210 {
 211   mach_port_t                   name;
 212   mach_msg_size_t               pad1;
 213   unsigned int                  pad2 : 16;
 214   mach_msg_type_name_t          disposition : 8;
 215   mach_msg_descriptor_type_t    type : 8;
 216 } mach_msg_port_descriptor_t;
 217
 218 typedef struct
 219 {
 220   uint32_t                      address;
 221   mach_msg_size_t               size;
 222   boolean_t                     deallocate: 8;
 223   mach_msg_copy_options_t       copy: 8;
 224   unsigned int                  pad1: 8;
 225   mach_msg_descriptor_type_t    type: 8;
 226 } mach_msg_ool_descriptor32_t;
 227
 228 typedef struct
 229 {
 230   uint64_t                      address;
 231   boolean_t                     deallocate: 8;
 232   mach_msg_copy_options_t       copy: 8;
 233   unsigned int                  pad1: 8;
 234   mach_msg_descriptor_type_t    type: 8;
 235   mach_msg_size_t               size;
 236 } mach_msg_ool_descriptor64_t;
 237
 238 typedef struct
 239 {
 240   void*                         address;
 241 #if !defined(__LP64__)
 242   mach_msg_size_t               size;
 243 #endif
 244   boolean_t                     deallocate: 8;
 245   mach_msg_copy_options_t       copy: 8;
 246   unsigned int                  pad1: 8;
 247   mach_msg_descriptor_type_t    type: 8;
 248 #if defined(__LP64__)
 249   mach_msg_size_t               size;
 250 #endif
 251 } mach_msg_ool_descriptor_t;
 252
 253 typedef struct
 254 {
 255   uint32_t                      address;
 256   mach_msg_size_t               count;
 257   boolean_t                     deallocate: 8;
 258   mach_msg_copy_options_t       copy: 8;
 259   mach_msg_type_name_t          disposition : 8;
 260   mach_msg_descriptor_type_t    type : 8;
 261 } mach_msg_ool_ports_descriptor32_t;
 262
 263 typedef struct
 264 {
 265   uint64_t                      address;
 266   boolean_t                     deallocate: 8;
 267   mach_msg_copy_options_t       copy: 8;
 268   mach_msg_type_name_t          disposition : 8;
 269   mach_msg_descriptor_type_t    type : 8;
 270   mach_msg_size_t               count;
 271 } mach_msg_ool_ports_descriptor64_t;
 272
 273 typedef struct
 274 {
 275   void*                         address;
 276 #if !defined(__LP64__)
 277   mach_msg_size_t               count;
 278 #endif
 279   boolean_t                     deallocate: 8;
 280   mach_msg_copy_options_t       copy: 8;
 281   mach_msg_type_name_t          disposition : 8;
 282   mach_msg_descriptor_type_t    type : 8;
 283 #if defined(__LP64__)
 284   mach_msg_size_t               count;
 285 #endif
 286 } mach_msg_ool_ports_descriptor_t;
 287
 288 /*
 289  * LP64support - This union definition is not really
 290  * appropriate in LP64 mode because not all descriptors
 291  * are of the same size in that environment.
 292  */
 293 typedef union
 294 {
 295   mach_msg_port_descriptor_t            port;
 296   mach_msg_ool_descriptor_t             out_of_line;
 297   mach_msg_ool_ports_descriptor_t       ool_ports;
 298   mach_msg_type_descriptor_t            type;
 299 } mach_msg_descriptor_t;
 300
 301 typedef struct
 302 {
 303         mach_msg_size_t msgh_descriptor_count;
 304 } mach_msg_body_t;
 305
 306 #define MACH_MSG_BODY_NULL (mach_msg_body_t *) 0
 307 #define MACH_MSG_DESCRIPTOR_NULL (mach_msg_descriptor_t *) 0
 308
 309 typedef struct
 310 {
 311   mach_msg_bits_t       msgh_bits;
 312   mach_msg_size_t       msgh_size;
 313   mach_port_t           msgh_remote_port;
 314   mach_port_t           msgh_local_port;
 315   mach_msg_size_t       msgh_reserved;
 316   mach_msg_id_t         msgh_id;
 317 } mach_msg_header_t;
 318
 319 #define MACH_MSG_NULL (mach_msg_header_t *) 0
 320
 321 typedef struct
 322 {
 323         mach_msg_header_t       header;
 324         mach_msg_body_t         body;
 325 } mach_msg_base_t;
 326
 327 typedef unsigned int mach_msg_trailer_type_t;
 328
 329 #define MACH_MSG_TRAILER_FORMAT_0       0
 330
 331 typedef unsigned int mach_msg_trailer_size_t;
 332
 333 typedef struct
 334 {
 335   mach_msg_trailer_type_t       msgh_trailer_type;
 336   mach_msg_trailer_size_t       msgh_trailer_size;
 337 } mach_msg_trailer_t;
 338
 339 typedef struct
 340 {
 341   mach_msg_trailer_type_t       msgh_trailer_type;
 342   mach_msg_trailer_size_t       msgh_trailer_size;
 343   mach_port_seqno_t             msgh_seqno;
 344 } mach_msg_seqno_trailer_t;
 345
 346 typedef struct
 347 {
 348   unsigned int                  val[2];
 349 } security_token_t;
 350
 351 typedef struct
 352 {
 353   mach_msg_trailer_type_t       msgh_trailer_type;
 354   mach_msg_trailer_size_t       msgh_trailer_size;
 355   mach_port_seqno_t             msgh_seqno;
 356   security_token_t              msgh_sender;
 357 } mach_msg_security_trailer_t;
 358
 359 /*
 360  * The audit token is an opaque token which identifies
 361  * Mach tasks and senders of Mach messages as subjects
 362  * to the BSM audit system.  Only the appropriate BSM
 363  * library routines should be used to interpret the
 364  * contents of the audit token as the representation
 365  * of the subject identity within the token may change
 366  * over time.
 367  */
 368 typedef struct
 369 {
 370   unsigned int                  val[8];
 371 } audit_token_t;
 372
 373 typedef struct
 374 {
 375   mach_msg_trailer_type_t       msgh_trailer_type;
 376   mach_msg_trailer_size_t       msgh_trailer_size;
 377   mach_port_seqno_t             msgh_seqno;
 378   security_token_t              msgh_sender;
 379   audit_token_t                 msgh_audit;
 380 } mach_msg_audit_trailer_t;
 381
 382 #define MACH_MSG_TRAILER_MINIMUM_SIZE  sizeof(mach_msg_trailer_t)
 383
 384 /*
 385  * These values can change from release to release - but clearly
 386  * code cannot request additional trailer elements one was not
 387  * compiled to understand.  Therefore, it is safe to use this
 388  * constant when the same module specified the receive options.
 389  * Otherwise, you run the risk that the options requested by
 390  * another module may exceed the local modules notion of
 391  * MAX_TRAILER_SIZE.
 392  */
 393 typedef mach_msg_audit_trailer_t mach_msg_max_trailer_t;
 394 #define MAX_TRAILER_SIZE sizeof(mach_msg_max_trailer_t)
 395
 396 /*
 397  * Legacy requirements keep us from ever updating these defines (even
 398  * when the format_0 trailers gain new option data fields in the future).
 399  * Therefore, they shouldn't be used going forward.  Instead, the sizes
 400  * should be compared against the specific element size requested using
 401  * REQUESTED_TRAILER_SIZE.
 402  */
 403 typedef mach_msg_security_trailer_t mach_msg_format_0_trailer_t;
 404 #define MACH_MSG_TRAILER_FORMAT_0_SIZE sizeof(mach_msg_format_0_trailer_t)
 405
 406 #define   KERNEL_SECURITY_TOKEN_VALUE  { {0, 1} }
 407 extern security_token_t KERNEL_SECURITY_TOKEN;
 408
 409 #define   KERNEL_AUDIT_TOKEN_VALUE  { {0, 0, 0, 0, 0, 0, 0, 0} }
 410 extern audit_token_t KERNEL_AUDIT_TOKEN;
 411
 412 typedef integer_t mach_msg_options_t;
 413
 414 typedef struct
 415 {
 416   mach_msg_header_t     header;
 417 } mach_msg_empty_send_t;
 418
 419 typedef struct
 420 {
 421   mach_msg_header_t     header;
 422   mach_msg_trailer_t    trailer;
 423 } mach_msg_empty_rcv_t;
 424
 425 typedef union
 426 {
 427   mach_msg_empty_send_t send;
 428   mach_msg_empty_rcv_t  rcv;
 429 } mach_msg_empty_t;
 430
 431 #pragma pack()
 432
 433 /* utility to round the message size - will become machine dependent */
 434 #define round_msg(x)    (((mach_msg_size_t)(x) + sizeof (natural_t) - 1) & \
 435                                 ~(sizeof (natural_t) - 1))
 436
 437 /*
 438  *  There is no fixed upper bound to the size of Mach messages.
 439  */
 440
 441 #define MACH_MSG_SIZE_MAX       ((mach_msg_size_t) ~0)
 442
 443 /*
 444  *  Compatibility definitions, for code written
 445  *  when there was a msgh_kind instead of msgh_seqno.
 446  */
 447 #define MACH_MSGH_KIND_NORMAL           0x00000000
 448 #define MACH_MSGH_KIND_NOTIFICATION     0x00000001
 449 #define msgh_kind                       msgh_seqno
 450 #define mach_msg_kind_t                 mach_port_seqno_t
 451
 452 /*
 453  *  The msgt_number field specifies the number of data elements.
 454  *  The msgt_size field specifies the size of each data element, in bits.
 455  *  The msgt_name field specifies the type of each data element.
 456  *  If msgt_inline is TRUE, the data follows the type descriptor
 457  *  in the body of the message.  If msgt_inline is FALSE, then a pointer
 458  *  to the data should follow the type descriptor, and the data is
 459  *  sent out-of-line.  In this case, if msgt_deallocate is TRUE,
 460  *  then the out-of-line data is moved (instead of copied) into the message.
 461  *  If msgt_longform is TRUE, then the type descriptor is actually
 462  *  a mach_msg_type_long_t.
 463  *
 464  *  The actual amount of inline data following the descriptor must
 465  *  a multiple of the word size.  For out-of-line data, this is a
 466  *  pointer.  For inline data, the supplied data size (calculated
 467  *  from msgt_number/msgt_size) is rounded up.  This guarantees
 468  *  that type descriptors always fall on word boundaries.
 469  *
 470  *  For port rights, msgt_size must be 8*sizeof(mach_port_t).
 471  *  If the data is inline, msgt_deallocate should be FALSE.
 472  *  The msgt_unused bit should be zero.
 473  *  The msgt_name, msgt_size, msgt_number fields in
 474  *  a mach_msg_type_long_t should be zero.
 475  */
 476
 477 typedef natural_t mach_msg_type_size_t;
 478 typedef natural_t mach_msg_type_number_t;
 479
 480 /*
 481  *  Values received/carried in messages.  Tells the receiver what
 482  *  sort of port right he now has.
 483  *
 484  *  MACH_MSG_TYPE_PORT_NAME is used to transfer a port name
 485  *  which should remain uninterpreted by the kernel.  (Port rights
 486  *  are not transferred, just the port name.)
 487  */
 488
 489 #define MACH_MSG_TYPE_PORT_NONE         0
 490
 491 #define MACH_MSG_TYPE_PORT_NAME         15
 492 #define MACH_MSG_TYPE_PORT_RECEIVE      MACH_MSG_TYPE_MOVE_RECEIVE
 493 #define MACH_MSG_TYPE_PORT_SEND         MACH_MSG_TYPE_MOVE_SEND
 494 #define MACH_MSG_TYPE_PORT_SEND_ONCE    MACH_MSG_TYPE_MOVE_SEND_ONCE
 495
 496 #define MACH_MSG_TYPE_LAST              22              /* Last assigned */
 497
 498 /*
 499  *  A dummy value.  Mostly used to indicate that the actual value
 500  *  will be filled in later, dynamically.
 501  */
 502
 503 #define MACH_MSG_TYPE_POLYMORPHIC       ((mach_msg_type_name_t) -1)
 504
 505 /*
 506  *      Is a given item a port type?
 507  */
 508
 509 #define MACH_MSG_TYPE_PORT_ANY(x)                       \
 510         (((x) >= MACH_MSG_TYPE_MOVE_RECEIVE) &&         \
 511          ((x) <= MACH_MSG_TYPE_MAKE_SEND_ONCE))
 512
 513 #define MACH_MSG_TYPE_PORT_ANY_SEND(x)                  \
 514         (((x) >= MACH_MSG_TYPE_MOVE_SEND) &&            \
 515          ((x) <= MACH_MSG_TYPE_MAKE_SEND_ONCE))
 516
 517 #define MACH_MSG_TYPE_PORT_ANY_RIGHT(x)                 \
 518         (((x) >= MACH_MSG_TYPE_MOVE_RECEIVE) &&         \
 519          ((x) <= MACH_MSG_TYPE_MOVE_SEND_ONCE))
 520
 521 typedef integer_t mach_msg_option_t;
 522
 523 #define MACH_MSG_OPTION_NONE    0x00000000
 524
 525 #define MACH_SEND_MSG           0x00000001
 526 #define MACH_RCV_MSG            0x00000002
 527 #define MACH_RCV_LARGE          0x00000004
 528
 529 #define MACH_SEND_TIMEOUT       0x00000010
 530 #define MACH_SEND_INTERRUPT     0x00000040      /* libmach implements */
 531 #define MACH_SEND_CANCEL        0x00000080
 532 #define MACH_SEND_ALWAYS        0x00010000      /* internal use only */
 533 #define MACH_SEND_TRAILER       0x00020000
 534
 535 #define MACH_RCV_TIMEOUT        0x00000100
 536 #define MACH_RCV_NOTIFY         0x00000200
 537 #define MACH_RCV_INTERRUPT      0x00000400      /* libmach implements */
 538 #define MACH_RCV_OVERWRITE      0x00001000
 539
 540 /*
 541  * NOTE: a 0x00------ RCV mask implies to ask for
 542  * a MACH_MSG_TRAILER_FORMAT_0 with 0 Elements,
 543  * which is equivalent to a mach_msg_trailer_t.
 544  */
 545 #define MACH_RCV_TRAILER_NULL   0
 546 #define MACH_RCV_TRAILER_SEQNO  1
 547 #define MACH_RCV_TRAILER_SENDER 2
 548 #define MACH_RCV_TRAILER_AUDIT  3
 549
 550 #define MACH_RCV_TRAILER_TYPE(x)     (((x) & 0xf) << 28)
 551 #define MACH_RCV_TRAILER_ELEMENTS(x) (((x) & 0xf) << 24)
 552 #define MACH_RCV_TRAILER_MASK        ((0xff << 24))
 553
 554 #define GET_RCV_ELEMENTS(y) (((y) >> 24) & 0xf)
 555 #define REQUESTED_TRAILER_SIZE(y)                               \
 556         ((mach_msg_trailer_size_t)                              \
 557          ((GET_RCV_ELEMENTS(y) == MACH_RCV_TRAILER_NULL) ?      \
 558           sizeof(mach_msg_trailer_t) :                          \
 559           ((GET_RCV_ELEMENTS(y) == MACH_RCV_TRAILER_SEQNO) ?    \
 560            sizeof(mach_msg_seqno_trailer_t) :                   \
 561           ((GET_RCV_ELEMENTS(y) == MACH_RCV_TRAILER_SENDER) ?   \
 562            sizeof(mach_msg_security_trailer_t) :                \
 563            sizeof(mach_msg_audit_trailer_t)))))
 564 /*
 565  *  Much code assumes that mach_msg_return_t == kern_return_t.
 566  *  This definition is useful for descriptive purposes.
 567  *
 568  *  See <mach/error.h> for the format of error codes.
 569  *  IPC errors are system 4.  Send errors are subsystem 0;
 570  *  receive errors are subsystem 1.  The code field is always non-zero.
 571  *  The high bits of the code field communicate extra information
 572  *  for some error codes.  MACH_MSG_MASK masks off these special bits.
 573  */
 574
 575 typedef kern_return_t mach_msg_return_t;
 576
 577 #define MACH_MSG_SUCCESS                0x00000000
 578
 579
 580 #define MACH_MSG_MASK                   0x00003e00
 581                 /* All special error code bits defined below. */
 582 #define MACH_MSG_IPC_SPACE              0x00002000
 583                 /* No room in IPC name space for another capability name. */
 584 #define MACH_MSG_VM_SPACE               0x00001000
 585                 /* No room in VM address space for out-of-line memory. */
 586 #define MACH_MSG_IPC_KERNEL             0x00000800
 587                 /* Kernel resource shortage handling an IPC capability. */
 588 #define MACH_MSG_VM_KERNEL              0x00000400
 589                 /* Kernel resource shortage handling out-of-line memory. */
 590
 591 #define MACH_SEND_IN_PROGRESS           0x10000001
 592                 /* Thread is waiting to send.  (Internal use only.) */
 593 #define MACH_SEND_INVALID_DATA          0x10000002
 594                 /* Bogus in-line data. */
 595 #define MACH_SEND_INVALID_DEST          0x10000003
 596                 /* Bogus destination port. */
 597 #define MACH_SEND_TIMED_OUT             0x10000004
 598                 /* Message not sent before timeout expired. */
 599 #define MACH_SEND_INTERRUPTED           0x10000007
 600                 /* Software interrupt. */
 601 #define MACH_SEND_MSG_TOO_SMALL         0x10000008
 602                 /* Data doesn't contain a complete message. */
 603 #define MACH_SEND_INVALID_REPLY         0x10000009
 604                 /* Bogus reply port. */
 605 #define MACH_SEND_INVALID_RIGHT         0x1000000a
 606                 /* Bogus port rights in the message body. */
 607 #define MACH_SEND_INVALID_NOTIFY        0x1000000b
 608                 /* Bogus notify port argument. */
 609 #define MACH_SEND_INVALID_MEMORY        0x1000000c
 610                 /* Invalid out-of-line memory pointer. */
 611 #define MACH_SEND_NO_BUFFER             0x1000000d
 612                 /* No message buffer is available. */
 613 #define MACH_SEND_TOO_LARGE             0x1000000e
 614                 /* Send is too large for port */
 615 #define MACH_SEND_INVALID_TYPE          0x1000000f
 616                 /* Invalid msg-type specification. */
 617 #define MACH_SEND_INVALID_HEADER        0x10000010
 618                 /* A field in the header had a bad value. */
 619 #define MACH_SEND_INVALID_TRAILER       0x10000011
 620                 /* The trailer to be sent does not match kernel format. */
 621 #define MACH_SEND_INVALID_RT_OOL_SIZE   0x10000015
 622                 /* compatibility: no longer a returned error */
 623
 624 #define MACH_RCV_IN_PROGRESS            0x10004001
 625                 /* Thread is waiting for receive.  (Internal use only.) */
 626 #define MACH_RCV_INVALID_NAME           0x10004002
 627                 /* Bogus name for receive port/port-set. */
 628 #define MACH_RCV_TIMED_OUT              0x10004003
 629                 /* Didn't get a message within the timeout value. */
 630 #define MACH_RCV_TOO_LARGE              0x10004004
 631                 /* Message buffer is not large enough for inline data. */
 632 #define MACH_RCV_INTERRUPTED            0x10004005
 633                 /* Software interrupt. */
 634 #define MACH_RCV_PORT_CHANGED           0x10004006
 635                 /* compatibility: no longer a returned error */
 636 #define MACH_RCV_INVALID_NOTIFY         0x10004007
 637                 /* Bogus notify port argument. */
 638 #define MACH_RCV_INVALID_DATA           0x10004008
 639                 /* Bogus message buffer for inline data. */
 640 #define MACH_RCV_PORT_DIED              0x10004009
 641                 /* Port/set was sent away/died during receive. */
 642 #define MACH_RCV_IN_SET                 0x1000400a
 643                 /* compatibility: no longer a returned error */
 644 #define MACH_RCV_HEADER_ERROR           0x1000400b
 645                 /* Error receiving message header.  See special bits. */
 646 #define MACH_RCV_BODY_ERROR             0x1000400c
 647                 /* Error receiving message body.  See special bits. */
 648 #define MACH_RCV_INVALID_TYPE           0x1000400d
 649                 /* Invalid msg-type specification in scatter list. */
 650 #define MACH_RCV_SCATTER_SMALL          0x1000400e
 651                 /* Out-of-line overwrite region is not large enough */
 652 #define MACH_RCV_INVALID_TRAILER        0x1000400f
 653                 /* trailer type or number of trailer elements not supported */
 654 #define MACH_RCV_IN_PROGRESS_TIMED      0x10004011
 655                 /* Waiting for receive with timeout. (Internal use only.) */
 656
 657
 658 __BEGIN_DECLS
 659
 660 /*
 661  *      Routine:        mach_msg_overwrite
 662  *      Purpose:
 663  *              Send and/or receive a message.  If the message operation
 664  *              is interrupted, and the user did not request an indication
 665  *              of that fact, then restart the appropriate parts of the
 666  *              operation silently (trap version does not restart).
 667  *
 668  *              Distinct send and receive buffers may be specified.  If
 669  *              no separate receive buffer is specified, the msg parameter
 670  *              will be used for both send and receive operations.
 671  *
 672  *              In addition to a distinct receive buffer, that buffer may
 673  *              already contain scatter control information to direct the
 674  *              receiving of the message.
 675  */
 676
 677 extern mach_msg_return_t        mach_msg_overwrite(
 678                                         mach_msg_header_t *msg,
 679                                         mach_msg_option_t option,
 680                                         mach_msg_size_t send_size,
 681                                         mach_msg_size_t rcv_size,
 682                                         mach_port_name_t rcv_name,
 683                                         mach_msg_timeout_t timeout,
 684                                         mach_port_name_t notify,
 685                                         mach_msg_header_t *rcv_msg,
 686                                         mach_msg_size_t rcv_limit);
 687
 688 #ifndef KERNEL
 689
 690 /*
 691  *      Routine:        mach_msg
 692  *      Purpose:
 693  *              Send and/or receive a message.  If the message operation
 694  *              is interrupted, and the user did not request an indication
 695  *              of that fact, then restart the appropriate parts of the
 696  *              operation silently (trap version does not restart).
 697  */
 698 extern mach_msg_return_t        mach_msg(
 699                                         mach_msg_header_t *msg,
 700                                         mach_msg_option_t option,
 701                                         mach_msg_size_t send_size,
 702                                         mach_msg_size_t rcv_size,
 703                                         mach_port_name_t rcv_name,
 704                                         mach_msg_timeout_t timeout,
 705                                         mach_port_name_t notify);
 706
 707 #endif  /* KERNEL */
 708
 709 __END_DECLS
 710
 711 #endif  /* _MACH_MESSAGE_H_ */