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