-/*\r
- ---------------------------------------------------------------------------\r
- Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved.\r
-\r
- LICENSE TERMS\r
-\r
- The free distribution and use of this software in both source and binary\r
- form is allowed (with or without changes) provided that:\r
-\r
- 1. distributions of this source code include the above copyright\r
- notice, this list of conditions and the following disclaimer;\r
-\r
- 2. distributions in binary form include the above copyright\r
- notice, this list of conditions and the following disclaimer\r
- in the documentation and/or other associated materials;\r
-\r
- 3. the copyright holder's name is not used to endorse products\r
- built using this software without specific written permission.\r
-\r
- ALTERNATIVELY, provided that this notice is retained in full, this product\r
- may be distributed under the terms of the GNU General Public License (GPL),\r
- in which case the provisions of the GPL apply INSTEAD OF those given above.\r
-\r
- DISCLAIMER\r
-\r
- This software is provided 'as is' with no explicit or implied warranties\r
- in respect of its properties, including, but not limited to, correctness\r
- and/or fitness for purpose.\r
- ---------------------------------------------------------------------------\r
- Issue 28/01/2004\r
-\r
- This file contains the definitions required to use AES in C. See aesopt.h\r
- for optimisation details.\r
-*/\r
-\r
-#if !defined( _AES_H )\r
-#define _AES_H\r
-\r
-/* This include is used to find 8 & 32 bit unsigned integer types */\r
-#include <machine/limits.h>\r
-\r
-#if defined(__cplusplus)\r
-extern "C"\r
-{\r
-#endif\r
-\r
-#define AES_128 /* define if AES with 128 bit keys is needed */\r
-#define AES_192 /* define if AES with 192 bit keys is needed */\r
-#define AES_256 /* define if AES with 256 bit keys is needed */\r
-#define AES_VAR /* define if a variable key size is needed */\r
-\r
-/* The following must also be set in assembler files if being used */\r
-\r
-#define AES_ENCRYPT /* if support for encryption is needed */\r
-#define AES_DECRYPT /* if support for decryption is needed */\r
-//#define AES_ERR_CHK /* for parameter checks & error return codes */\r
-\r
-#if UCHAR_MAX == 0xff /* an unsigned 8 bit type */\r
- typedef unsigned char aes_08t;\r
-#else\r
-# error Please define aes_08t as an 8-bit unsigned integer type in aes.h\r
-#endif\r
-\r
-#if UINT_MAX == 4294967295 /* an unsigned 32 bit type */\r
- typedef unsigned int aes_32t;\r
-#elif ULONG_MAX == 4294967295ul\r
- typedef unsigned long aes_32t;\r
-#else\r
-# error Please define aes_32t as a 32-bit unsigned integer type in aes.h\r
-#endif\r
-\r
-#define AES_BLOCK_SIZE 16 /* the AES block size in bytes */\r
-#define N_COLS 4 /* the number of columns in the state */\r
-\r
-/* The key schedule length is 11, 13 or 15 16-byte blocks for 128, */\r
-/* 192 or 256-bit keys respectively. That is 176, 208 or 240 bytes */\r
-/* or 44, 52 or 60 32-bit words. For simplicity this code allocates */\r
-/* the maximum 60 word array for the key schedule for all key sizes */\r
-\r
-#if defined( AES_VAR ) || defined( AES_256 )\r
-#define KS_LENGTH 60\r
-#elif defined( AES_192 )\r
-#define KS_LENGTH 52\r
-#else\r
-#define KS_LENGTH 44\r
-#endif\r
-\r
-#if defined( AES_ERR_CHK )\r
-#define aes_ret int\r
-#define aes_good 0\r
-#define aes_error -1\r
-#else\r
-#define aes_ret void\r
-#endif\r
-\r
-#if !defined( AES_DLL ) /* implement normal/DLL functions */\r
-#define aes_rval aes_ret\r
-#else\r
-#define aes_rval aes_ret __declspec(dllexport) _stdcall\r
-#endif\r
-\r
-typedef struct\r
-{ aes_32t ks[KS_LENGTH];\r
- aes_32t rn;\r
-} aes_encrypt_ctx;\r
-\r
-typedef struct\r
-{ aes_32t ks[KS_LENGTH];\r
- aes_32t rn;\r
-} aes_decrypt_ctx;\r
-\r
-typedef struct\r
-{ \r
- aes_decrypt_ctx decrypt;\r
- aes_encrypt_ctx encrypt;\r
-} aes_ctx;\r
-\r
-\r
-/* This routine must be called before first use if non-static */\r
-/* tables are being used */\r
-\r
-void gen_tabs(void);\r
-\r
-/* The key length (klen) is input in bytes when it is in the range */\r
-/* 16 <= klen <= 32 or in bits when in the range 128 <= klen <= 256 */\r
-\r
-#if defined( AES_ENCRYPT )\r
-\r
-#if defined(AES_128) || defined(AES_VAR)\r
-aes_rval aes_encrypt_key128(const unsigned char *in_key, aes_encrypt_ctx cx[1]);\r
-#endif\r
-\r
-#if defined(AES_192) || defined(AES_VAR)\r
-aes_rval aes_encrypt_key192(const unsigned char *in_key, aes_encrypt_ctx cx[1]);\r
-#endif\r
-\r
-#if defined(AES_256) || defined(AES_VAR)\r
-aes_rval aes_encrypt_key256(const unsigned char *in_key, aes_encrypt_ctx cx[1]);\r
-#endif\r
-\r
-#if defined(AES_VAR)\r
-aes_rval aes_encrypt_key(const unsigned char *in_key, int key_len, aes_encrypt_ctx cx[1]);\r
-#endif\r
-\r
-aes_rval aes_encrypt_cbc(const unsigned char *in_blk, const unsigned char *in_iv, unsigned int num_blk,\r
- unsigned char *out_blk, const aes_encrypt_ctx cx[1]);\r
-#endif\r
-\r
-#if defined( AES_DECRYPT )\r
-\r
-#if defined(AES_128) || defined(AES_VAR)\r
-aes_rval aes_decrypt_key128(const unsigned char *in_key, aes_decrypt_ctx cx[1]);\r
-#endif\r
-\r
-#if defined(AES_192) || defined(AES_VAR)\r
-aes_rval aes_decrypt_key192(const unsigned char *in_key, aes_decrypt_ctx cx[1]);\r
-#endif\r
-\r
-#if defined(AES_256) || defined(AES_VAR)\r
-aes_rval aes_decrypt_key256(const unsigned char *in_key, aes_decrypt_ctx cx[1]);\r
-#endif\r
-\r
-#if defined(AES_VAR)\r
-aes_rval aes_decrypt_key(const unsigned char *in_key, int key_len, aes_decrypt_ctx cx[1]);\r
-#endif\r
-\r
-aes_rval aes_decrypt_cbc(const unsigned char *in_blk, const unsigned char *in_iv, unsigned int num_blk,\r
- unsigned char *out_blk, const aes_decrypt_ctx cx[1]);\r
-#endif\r
-\r
-#if defined(__cplusplus)\r
-}\r
-#endif\r
-\r
-#endif\r
+/*
+ ---------------------------------------------------------------------------
+ Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved.
+
+ LICENSE TERMS
+
+ The free distribution and use of this software in both source and binary
+ form is allowed (with or without changes) provided that:
+
+ 1. distributions of this source code include the above copyright
+ notice, this list of conditions and the following disclaimer;
+
+ 2. distributions in binary form include the above copyright
+ notice, this list of conditions and the following disclaimer
+ in the documentation and/or other associated materials;
+
+ 3. the copyright holder's name is not used to endorse products
+ built using this software without specific written permission.
+
+ ALTERNATIVELY, provided that this notice is retained in full, this product
+ may be distributed under the terms of the GNU General Public License (GPL),
+ in which case the provisions of the GPL apply INSTEAD OF those given above.
+
+ DISCLAIMER
+
+ This software is provided 'as is' with no explicit or implied warranties
+ in respect of its properties, including, but not limited to, correctness
+ and/or fitness for purpose.
+ ---------------------------------------------------------------------------
+ Issue 28/01/2004
+
+ This file contains the definitions required to use AES in C. See aesopt.h
+ for optimisation details.
+*/
+
+#if !defined( _AES_H )
+#define _AES_H
+
+/* This include is used to find 8 & 32 bit unsigned integer types */
+#include <machine/limits.h>
+
+#if defined(__cplusplus)
+extern "C"
+{
+#endif
+
+#define AES_128 /* define if AES with 128 bit keys is needed */
+#define AES_192 /* define if AES with 192 bit keys is needed */
+#define AES_256 /* define if AES with 256 bit keys is needed */
+#define AES_VAR /* define if a variable key size is needed */
+
+/* The following must also be set in assembler files if being used */
+
+#define AES_ENCRYPT /* if support for encryption is needed */
+#define AES_DECRYPT /* if support for decryption is needed */
+//#define AES_ERR_CHK /* for parameter checks & error return codes */
+
+#if UCHAR_MAX == 0xff /* an unsigned 8 bit type */
+ typedef unsigned char aes_08t;
+#else
+# error Please define aes_08t as an 8-bit unsigned integer type in aes.h
+#endif
+
+#if UINT_MAX == 4294967295 /* an unsigned 32 bit type */
+ typedef unsigned int aes_32t;
+#elif ULONG_MAX == 4294967295ul
+ typedef unsigned long aes_32t;
+#else
+# error Please define aes_32t as a 32-bit unsigned integer type in aes.h
+#endif
+
+#define AES_BLOCK_SIZE 16 /* the AES block size in bytes */
+#define N_COLS 4 /* the number of columns in the state */
+
+/* The key schedule length is 11, 13 or 15 16-byte blocks for 128, */
+/* 192 or 256-bit keys respectively. That is 176, 208 or 240 bytes */
+/* or 44, 52 or 60 32-bit words. For simplicity this code allocates */
+/* the maximum 60 word array for the key schedule for all key sizes */
+
+#if defined( AES_VAR ) || defined( AES_256 )
+#define KS_LENGTH 60
+#elif defined( AES_192 )
+#define KS_LENGTH 52
+#else
+#define KS_LENGTH 44
+#endif
+
+#if defined( AES_ERR_CHK )
+#define aes_ret int
+#define aes_good 0
+#define aes_error -1
+#else
+#define aes_ret void
+#endif
+
+#if !defined( AES_DLL ) /* implement normal/DLL functions */
+#define aes_rval aes_ret
+#else
+#define aes_rval aes_ret __declspec(dllexport) _stdcall
+#endif
+
+typedef struct
+{ aes_32t ks[KS_LENGTH];
+ aes_32t rn;
+} aes_encrypt_ctx;
+
+typedef struct
+{ aes_32t ks[KS_LENGTH];
+ aes_32t rn;
+} aes_decrypt_ctx;
+
+typedef struct
+{
+ aes_decrypt_ctx decrypt;
+ aes_encrypt_ctx encrypt;
+} aes_ctx;
+
+
+/* This routine must be called before first use if non-static */
+/* tables are being used */
+
+void gen_tabs(void);
+
+/* The key length (klen) is input in bytes when it is in the range */
+/* 16 <= klen <= 32 or in bits when in the range 128 <= klen <= 256 */
+
+#if defined( AES_ENCRYPT )
+
+#if defined(AES_128) || defined(AES_VAR)
+aes_rval aes_encrypt_key128(const unsigned char *in_key, aes_encrypt_ctx cx[1]);
+#endif
+
+#if defined(AES_192) || defined(AES_VAR)
+aes_rval aes_encrypt_key192(const unsigned char *in_key, aes_encrypt_ctx cx[1]);
+#endif
+
+#if defined(AES_256) || defined(AES_VAR)
+aes_rval aes_encrypt_key256(const unsigned char *in_key, aes_encrypt_ctx cx[1]);
+#endif
+
+#if defined(AES_VAR)
+aes_rval aes_encrypt_key(const unsigned char *in_key, int key_len, aes_encrypt_ctx cx[1]);
+#endif
+
+aes_rval aes_encrypt_cbc(const unsigned char *in_blk, const unsigned char *in_iv, unsigned int num_blk,
+ unsigned char *out_blk, const aes_encrypt_ctx cx[1]);
+#endif
+
+#if defined( AES_DECRYPT )
+
+#if defined(AES_128) || defined(AES_VAR)
+aes_rval aes_decrypt_key128(const unsigned char *in_key, aes_decrypt_ctx cx[1]);
+#endif
+
+#if defined(AES_192) || defined(AES_VAR)
+aes_rval aes_decrypt_key192(const unsigned char *in_key, aes_decrypt_ctx cx[1]);
+#endif
+
+#if defined(AES_256) || defined(AES_VAR)
+aes_rval aes_decrypt_key256(const unsigned char *in_key, aes_decrypt_ctx cx[1]);
+#endif
+
+#if defined(AES_VAR)
+aes_rval aes_decrypt_key(const unsigned char *in_key, int key_len, aes_decrypt_ctx cx[1]);
+#endif
+
+aes_rval aes_decrypt_cbc(const unsigned char *in_blk, const unsigned char *in_iv, unsigned int num_blk,
+ unsigned char *out_blk, const aes_decrypt_ctx cx[1]);
+#endif
+
+#if defined(__cplusplus)
+}
+#endif
+
+#endif
-/*\r
- ---------------------------------------------------------------------------\r
- Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved.\r
-\r
- LICENSE TERMS\r
-\r
- The free distribution and use of this software in both source and binary\r
- form is allowed (with or without changes) provided that:\r
-\r
- 1. distributions of this source code include the above copyright\r
- notice, this list of conditions and the following disclaimer;\r
-\r
- 2. distributions in binary form include the above copyright\r
- notice, this list of conditions and the following disclaimer\r
- in the documentation and/or other associated materials;\r
-\r
- 3. the copyright holder's name is not used to endorse products\r
- built using this software without specific written permission.\r
-\r
- ALTERNATIVELY, provided that this notice is retained in full, this product\r
- may be distributed under the terms of the GNU General Public License (GPL),\r
- in which case the provisions of the GPL apply INSTEAD OF those given above.\r
-\r
- DISCLAIMER\r
-\r
- This software is provided 'as is' with no explicit or implied warranties\r
- in respect of its properties, including, but not limited to, correctness\r
- and/or fitness for purpose.\r
- ---------------------------------------------------------------------------\r
- Issue 28/01/2004\r
-\r
- This file contains the code for implementing encryption and decryption\r
- for AES (Rijndael) for block and key sizes of 16, 24 and 32 bytes. It\r
- can optionally be replaced by code written in assembler using NASM. For\r
- further details see the file aesopt.h\r
-*/\r
-\r
-#include "aesopt.h"\r
-#include "aestab.h"\r
-\r
-#if defined(__cplusplus)\r
-extern "C"\r
-{\r
-#endif\r
-\r
-#define ki(y,x,k,c) (s(y,c) = s(x, c) ^ (k)[c])\r
-#define xo(y,x,c) (s(y,c) ^= s(x, c))\r
-#define si(y,x,c) (s(y,c) = word_in(x, c))\r
-#define so(y,x,c) word_out(y, c, s(x,c))\r
-\r
-#if defined(ARRAYS)\r
-#define locals(y,x) x[4],y[4]\r
-#else\r
-#define locals(y,x) x##0,x##1,x##2,x##3,y##0,y##1,y##2,y##3\r
-#endif\r
-\r
-#define dtables(tab) const aes_32t *tab##0, *tab##1, *tab##2, *tab##3\r
-#define itables(tab) tab##0 = tab[0]; tab##1 = tab[1]; tab##2 = tab[2]; tab##3 = tab[3]\r
-\r
-#define l_copy(y, x) s(y,0) = s(x,0); s(y,1) = s(x,1); \\r
- s(y,2) = s(x,2); s(y,3) = s(x,3);\r
-\r
-#define key_in(y,x,k) ki(y,x,k,0); ki(y,x,k,1); ki(y,x,k,2); ki(y,x,k,3)\r
-#define cbc(y,x) xo(y,x,0); xo(y,x,1); xo(y,x,2); xo(y,x,3)\r
-#define state_in(y,x) si(y,x,0); si(y,x,1); si(y,x,2); si(y,x,3)\r
-#define state_out(y,x) so(y,x,0); so(y,x,1); so(y,x,2); so(y,x,3)\r
-#define round(rm,y,x,k) rm(y,x,k,0); rm(y,x,k,1); rm(y,x,k,2); rm(y,x,k,3)\r
-\r
-#if defined(ENCRYPTION) && !defined(AES_ASM)\r
-\r
-/* Visual C++ .Net v7.1 provides the fastest encryption code when using\r
- Pentium optimiation with small code but this is poor for decryption\r
- so we need to control this with the following VC++ pragmas\r
-*/\r
-\r
-#if defined(_MSC_VER)\r
-#pragma optimize( "s", on )\r
-#endif\r
-\r
-/* Given the column (c) of the output state variable, the following\r
- macros give the input state variables which are needed in its\r
- computation for each row (r) of the state. All the alternative\r
- macros give the same end values but expand into different ways\r
- of calculating these values. In particular the complex macro\r
- used for dynamically variable block sizes is designed to expand\r
- to a compile time constant whenever possible but will expand to\r
- conditional clauses on some branches (I am grateful to Frank\r
- Yellin for this construction)\r
-*/\r
-\r
-#define fwd_var(x,r,c)\\r
- ( r == 0 ? ( c == 0 ? s(x,0) : c == 1 ? s(x,1) : c == 2 ? s(x,2) : s(x,3))\\r
- : r == 1 ? ( c == 0 ? s(x,1) : c == 1 ? s(x,2) : c == 2 ? s(x,3) : s(x,0))\\r
- : r == 2 ? ( c == 0 ? s(x,2) : c == 1 ? s(x,3) : c == 2 ? s(x,0) : s(x,1))\\r
- : ( c == 0 ? s(x,3) : c == 1 ? s(x,0) : c == 2 ? s(x,1) : s(x,2)))\r
-\r
-#if defined(FT4_SET)\r
-#undef dec_fmvars\r
-# if defined(ENC_ROUND_CACHE_TABLES)\r
-#define fwd_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_cached_tables(x,t_fn,fwd_var,rf1,c))\r
-# else\r
-#define fwd_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_tables(x,t_fn,fwd_var,rf1,c))\r
-# endif\r
-#elif defined(FT1_SET)\r
-#undef dec_fmvars\r
-#define fwd_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ one_table(x,upr,t_fn,fwd_var,rf1,c))\r
-#else\r
-#define fwd_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ fwd_mcol(no_table(x,t_sbox,fwd_var,rf1,c)))\r
-#endif\r
-\r
-#if defined(FL4_SET)\r
-# if defined(LAST_ENC_ROUND_CACHE_TABLES)\r
-#define fwd_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_cached_tables(x,t_fl,fwd_var,rf1,c))\r
-# else\r
-#define fwd_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_tables(x,t_fl,fwd_var,rf1,c))\r
-# endif\r
-#elif defined(FL1_SET)\r
-#define fwd_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ one_table(x,ups,t_fl,fwd_var,rf1,c))\r
-#else\r
-#define fwd_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ no_table(x,t_sbox,fwd_var,rf1,c))\r
-#endif\r
-\r
-aes_rval aes_encrypt_cbc(const unsigned char *in, const unsigned char *in_iv, unsigned int num_blk,\r
- unsigned char *out, const aes_encrypt_ctx cx[1])\r
-{ aes_32t locals(b0, b1);\r
- const aes_32t *kp;\r
- const aes_32t *kptr = cx->ks;\r
-#if defined(ENC_ROUND_CACHE_TABLES)\r
- dtables(t_fn);\r
-#endif\r
-#if defined(LAST_ENC_ROUND_CACHE_TABLES)\r
- dtables(t_fl);\r
-#endif\r
-\r
-#if defined( dec_fmvars )\r
- dec_fmvars; /* declare variables for fwd_mcol() if needed */\r
-#endif\r
-\r
-#if defined( AES_ERR_CHK )\r
- if( cx->rn != 10 && cx->rn != 12 && cx->rn != 14 )\r
- return aes_error;\r
-#endif\r
-\r
- // Load IV into b0.\r
- state_in(b0, in_iv);\r
-\r
- for (;num_blk; in += AES_BLOCK_SIZE, out += AES_BLOCK_SIZE, --num_blk)\r
- {\r
- kp = kptr;\r
-#if 0\r
- // Read the plaintext into b1\r
- state_in(b1, in);\r
- // Do the CBC with b0 which is either the iv or the ciphertext of the previous block.\r
- cbc(b1, b0);\r
-\r
- // Xor b1 with the key schedule to get things started.\r
- key_in(b0, b1, kp);\r
-#else\r
- // Since xor is associative we mess with the ordering here to get the loads started early\r
- key_in(b1, b0, kp); // Xor b0(IV) with the key schedule and assign to b1\r
- state_in(b0, in); // Load block into b0\r
- cbc(b0, b1); // Xor b0 with b1 and store in b0\r
-#endif\r
-\r
-#if defined(ENC_ROUND_CACHE_TABLES)\r
- itables(t_fn);\r
-#endif\r
-\r
-#if (ENC_UNROLL == FULL)\r
-\r
- switch(cx->rn)\r
- {\r
- case 14:\r
- round(fwd_rnd, b1, b0, kp + 1 * N_COLS);\r
- round(fwd_rnd, b0, b1, kp + 2 * N_COLS);\r
- kp += 2 * N_COLS;\r
- case 12:\r
- round(fwd_rnd, b1, b0, kp + 1 * N_COLS);\r
- round(fwd_rnd, b0, b1, kp + 2 * N_COLS);\r
- kp += 2 * N_COLS;\r
- case 10:\r
- default:\r
- round(fwd_rnd, b1, b0, kp + 1 * N_COLS);\r
- round(fwd_rnd, b0, b1, kp + 2 * N_COLS);\r
- round(fwd_rnd, b1, b0, kp + 3 * N_COLS);\r
- round(fwd_rnd, b0, b1, kp + 4 * N_COLS);\r
- round(fwd_rnd, b1, b0, kp + 5 * N_COLS);\r
- round(fwd_rnd, b0, b1, kp + 6 * N_COLS);\r
- round(fwd_rnd, b1, b0, kp + 7 * N_COLS);\r
- round(fwd_rnd, b0, b1, kp + 8 * N_COLS);\r
- round(fwd_rnd, b1, b0, kp + 9 * N_COLS);\r
-#if defined(LAST_ENC_ROUND_CACHE_TABLES)\r
- itables(t_fl);\r
-#endif\r
- round(fwd_lrnd, b0, b1, kp +10 * N_COLS);\r
- }\r
-\r
-#else\r
-\r
- { aes_32t rnd;\r
-#if (ENC_UNROLL == PARTIAL)\r
- for(rnd = 0; rnd < (cx->rn >> 1) - 1; ++rnd)\r
- {\r
- kp += N_COLS;\r
- round(fwd_rnd, b1, b0, kp);\r
- kp += N_COLS;\r
- round(fwd_rnd, b0, b1, kp);\r
- }\r
- kp += N_COLS;\r
- round(fwd_rnd, b1, b0, kp);\r
-#else\r
- for(rnd = 0; rnd < cx->rn - 1; ++rnd)\r
- {\r
- kp += N_COLS;\r
- round(fwd_rnd, b1, b0, kp);\r
- l_copy(b0, b1);\r
- }\r
-#endif\r
-#if defined(LAST_ENC_ROUND_CACHE_TABLES)\r
- itables(t_fl);\r
-#endif\r
- kp += N_COLS;\r
- round(fwd_lrnd, b0, b1, kp);\r
- }\r
-#endif\r
- \r
- state_out(out, b0);\r
- }\r
-\r
-#if defined( AES_ERR_CHK )\r
- return aes_good;\r
-#endif\r
-}\r
-\r
-#endif\r
-\r
-#if defined(DECRYPTION) && !defined(AES_ASM)\r
-\r
-/* Visual C++ .Net v7.1 provides the fastest encryption code when using\r
- Pentium optimiation with small code but this is poor for decryption\r
- so we need to control this with the following VC++ pragmas\r
-*/\r
-\r
-#if defined(_MSC_VER)\r
-#pragma optimize( "t", on )\r
-#endif\r
-\r
-/* Given the column (c) of the output state variable, the following\r
- macros give the input state variables which are needed in its\r
- computation for each row (r) of the state. All the alternative\r
- macros give the same end values but expand into different ways\r
- of calculating these values. In particular the complex macro\r
- used for dynamically variable block sizes is designed to expand\r
- to a compile time constant whenever possible but will expand to\r
- conditional clauses on some branches (I am grateful to Frank\r
- Yellin for this construction)\r
-*/\r
-\r
-#define inv_var(x,r,c)\\r
- ( r == 0 ? ( c == 0 ? s(x,0) : c == 1 ? s(x,1) : c == 2 ? s(x,2) : s(x,3))\\r
- : r == 1 ? ( c == 0 ? s(x,3) : c == 1 ? s(x,0) : c == 2 ? s(x,1) : s(x,2))\\r
- : r == 2 ? ( c == 0 ? s(x,2) : c == 1 ? s(x,3) : c == 2 ? s(x,0) : s(x,1))\\r
- : ( c == 0 ? s(x,1) : c == 1 ? s(x,2) : c == 2 ? s(x,3) : s(x,0)))\r
-\r
-#if defined(IT4_SET)\r
-#undef dec_imvars\r
-# if defined(DEC_ROUND_CACHE_TABLES)\r
-#define inv_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_cached_tables(x,t_in,inv_var,rf1,c))\r
-# else\r
-#define inv_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_tables(x,t_in,inv_var,rf1,c))\r
-# endif\r
-#elif defined(IT1_SET)\r
-#undef dec_imvars\r
-#define inv_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ one_table(x,upr,t_in,inv_var,rf1,c))\r
-#else\r
-#define inv_rnd(y,x,k,c) (s(y,c) = inv_mcol((k)[c] ^ no_table(x,t_ibox,inv_var,rf1,c)))\r
-#endif\r
-\r
-#if defined(IL4_SET)\r
-# if defined(LAST_DEC_ROUND_CACHE_TABLES)\r
-#define inv_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_cached_tables(x,t_il,inv_var,rf1,c))\r
-# else\r
-#define inv_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_tables(x,t_il,inv_var,rf1,c))\r
-# endif\r
-#elif defined(IL1_SET)\r
-#define inv_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ one_table(x,ups,t_il,inv_var,rf1,c))\r
-#else\r
-#define inv_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ no_table(x,t_ibox,inv_var,rf1,c))\r
-#endif\r
-\r
-aes_rval aes_decrypt_cbc(const unsigned char *in, const unsigned char *in_iv, unsigned int num_blk,\r
- unsigned char *out, const aes_decrypt_ctx cx[1])\r
-{ aes_32t locals(b0, b1);\r
- const aes_32t *kptr = cx->ks + cx->rn * N_COLS;\r
- const aes_32t *kp;\r
-#if defined(DEC_ROUND_CACHE_TABLES)\r
- dtables(t_in);\r
-#endif\r
-#if defined(LAST_DEC_ROUND_CACHE_TABLES)\r
- dtables(t_il);\r
-#endif\r
-\r
-#if defined( dec_imvars )\r
- dec_imvars; /* declare variables for inv_mcol() if needed */\r
-#endif\r
- \r
-#if defined( AES_ERR_CHK )\r
- if( cx->rn != 10 && cx->rn != 12 && cx->rn != 14 )\r
- return aes_error;\r
-#endif\r
-\r
-#if defined(DEC_ROUND_CACHE_TABLES)\r
- itables(t_in);\r
-#endif \r
- \r
- in += AES_BLOCK_SIZE * (num_blk - 1);\r
- out += AES_BLOCK_SIZE * (num_blk - 1);\r
- // Load the last block's ciphertext into b1\r
- state_in(b1, in);\r
-\r
- for (;num_blk; out -= AES_BLOCK_SIZE, --num_blk)\r
- {\r
- kp = kptr;\r
- // Do the xor part of state_in, where b1 is the previous block's ciphertext.\r
- key_in(b0, b1, kp);\r
-\r
-#if (DEC_UNROLL == FULL)\r
- \r
- switch(cx->rn)\r
- {\r
- case 14:\r
- round(inv_rnd, b1, b0, kp - 1 * N_COLS);\r
- round(inv_rnd, b0, b1, kp - 2 * N_COLS);\r
- kp -= 2 * N_COLS;\r
- case 12:\r
- round(inv_rnd, b1, b0, kp - 1 * N_COLS);\r
- round(inv_rnd, b0, b1, kp - 2 * N_COLS);\r
- kp -= 2 * N_COLS;\r
- case 10:\r
- default:\r
- round(inv_rnd, b1, b0, kp - 1 * N_COLS);\r
- round(inv_rnd, b0, b1, kp - 2 * N_COLS);\r
- round(inv_rnd, b1, b0, kp - 3 * N_COLS);\r
- round(inv_rnd, b0, b1, kp - 4 * N_COLS);\r
- round(inv_rnd, b1, b0, kp - 5 * N_COLS);\r
- round(inv_rnd, b0, b1, kp - 6 * N_COLS);\r
- round(inv_rnd, b1, b0, kp - 7 * N_COLS);\r
- round(inv_rnd, b0, b1, kp - 8 * N_COLS);\r
- round(inv_rnd, b1, b0, kp - 9 * N_COLS);\r
-#if defined(LAST_DEC_ROUND_CACHE_TABLES)\r
- itables(t_il);\r
-#endif \r
- round(inv_lrnd, b0, b1, kp - 10 * N_COLS);\r
- }\r
-\r
-#else\r
- \r
- { aes_32t rnd;\r
-#if (DEC_UNROLL == PARTIAL)\r
- for(rnd = 0; rnd < (cx->rn >> 1) - 1; ++rnd)\r
- {\r
- kp -= N_COLS;\r
- round(inv_rnd, b1, b0, kp);\r
- kp -= N_COLS;\r
- round(inv_rnd, b0, b1, kp);\r
- }\r
- kp -= N_COLS;\r
- round(inv_rnd, b1, b0, kp);\r
-#else\r
- for(rnd = 0; rnd < cx->rn - 1; ++rnd)\r
- {\r
- kp -= N_COLS;\r
- round(inv_rnd, b1, b0, kp);\r
- l_copy(b0, b1);\r
- }\r
-#endif\r
-#if defined(LAST_DEC_ROUND_CACHE_TABLES)\r
- itables(t_il);\r
-#endif \r
- kp -= N_COLS;\r
- round(inv_lrnd, b0, b1, kp);\r
- }\r
-#endif\r
-\r
- if (num_blk == 1)\r
- {\r
- // We are doing the first block so we need the IV rather than the previous\r
- // block for CBC (there is no previous block)\r
- state_in(b1, in_iv);\r
- }\r
- else\r
- {\r
- in -= AES_BLOCK_SIZE;\r
- state_in(b1, in);\r
- }\r
-\r
- // Do the CBC with b1 which is either the IV or the ciphertext of the previous block.\r
- cbc(b0, b1);\r
-\r
- state_out(out, b0);\r
- }\r
-#if defined( AES_ERR_CHK )\r
- return aes_good;\r
-#endif\r
-}\r
-\r
-#endif\r
-\r
-#if defined(__cplusplus)\r
-}\r
-#endif\r
+/*
+ ---------------------------------------------------------------------------
+ Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved.
+
+ LICENSE TERMS
+
+ The free distribution and use of this software in both source and binary
+ form is allowed (with or without changes) provided that:
+
+ 1. distributions of this source code include the above copyright
+ notice, this list of conditions and the following disclaimer;
+
+ 2. distributions in binary form include the above copyright
+ notice, this list of conditions and the following disclaimer
+ in the documentation and/or other associated materials;
+
+ 3. the copyright holder's name is not used to endorse products
+ built using this software without specific written permission.
+
+ ALTERNATIVELY, provided that this notice is retained in full, this product
+ may be distributed under the terms of the GNU General Public License (GPL),
+ in which case the provisions of the GPL apply INSTEAD OF those given above.
+
+ DISCLAIMER
+
+ This software is provided 'as is' with no explicit or implied warranties
+ in respect of its properties, including, but not limited to, correctness
+ and/or fitness for purpose.
+ ---------------------------------------------------------------------------
+ Issue 28/01/2004
+
+ This file contains the code for implementing encryption and decryption
+ for AES (Rijndael) for block and key sizes of 16, 24 and 32 bytes. It
+ can optionally be replaced by code written in assembler using NASM. For
+ further details see the file aesopt.h
+*/
+
+#include "aesopt.h"
+#include "aestab.h"
+
+#if defined(__cplusplus)
+extern "C"
+{
+#endif
+
+#define ki(y,x,k,c) (s(y,c) = s(x, c) ^ (k)[c])
+#define xo(y,x,c) (s(y,c) ^= s(x, c))
+#define si(y,x,c) (s(y,c) = word_in(x, c))
+#define so(y,x,c) word_out(y, c, s(x,c))
+
+#if defined(ARRAYS)
+#define locals(y,x) x[4],y[4]
+#else
+#define locals(y,x) x##0,x##1,x##2,x##3,y##0,y##1,y##2,y##3
+#endif
+
+#define dtables(tab) const aes_32t *tab##0, *tab##1, *tab##2, *tab##3
+#define itables(tab) tab##0 = tab[0]; tab##1 = tab[1]; tab##2 = tab[2]; tab##3 = tab[3]
+
+#define l_copy(y, x) s(y,0) = s(x,0); s(y,1) = s(x,1); \
+ s(y,2) = s(x,2); s(y,3) = s(x,3);
+
+#define key_in(y,x,k) ki(y,x,k,0); ki(y,x,k,1); ki(y,x,k,2); ki(y,x,k,3)
+#define cbc(y,x) xo(y,x,0); xo(y,x,1); xo(y,x,2); xo(y,x,3)
+#define state_in(y,x) si(y,x,0); si(y,x,1); si(y,x,2); si(y,x,3)
+#define state_out(y,x) so(y,x,0); so(y,x,1); so(y,x,2); so(y,x,3)
+#define round(rm,y,x,k) rm(y,x,k,0); rm(y,x,k,1); rm(y,x,k,2); rm(y,x,k,3)
+
+#if defined(ENCRYPTION) && !defined(AES_ASM)
+
+/* Visual C++ .Net v7.1 provides the fastest encryption code when using
+ Pentium optimiation with small code but this is poor for decryption
+ so we need to control this with the following VC++ pragmas
+*/
+
+#if defined(_MSC_VER)
+#pragma optimize( "s", on )
+#endif
+
+/* Given the column (c) of the output state variable, the following
+ macros give the input state variables which are needed in its
+ computation for each row (r) of the state. All the alternative
+ macros give the same end values but expand into different ways
+ of calculating these values. In particular the complex macro
+ used for dynamically variable block sizes is designed to expand
+ to a compile time constant whenever possible but will expand to
+ conditional clauses on some branches (I am grateful to Frank
+ Yellin for this construction)
+*/
+
+#define fwd_var(x,r,c)\
+ ( r == 0 ? ( c == 0 ? s(x,0) : c == 1 ? s(x,1) : c == 2 ? s(x,2) : s(x,3))\
+ : r == 1 ? ( c == 0 ? s(x,1) : c == 1 ? s(x,2) : c == 2 ? s(x,3) : s(x,0))\
+ : r == 2 ? ( c == 0 ? s(x,2) : c == 1 ? s(x,3) : c == 2 ? s(x,0) : s(x,1))\
+ : ( c == 0 ? s(x,3) : c == 1 ? s(x,0) : c == 2 ? s(x,1) : s(x,2)))
+
+#if defined(FT4_SET)
+#undef dec_fmvars
+# if defined(ENC_ROUND_CACHE_TABLES)
+#define fwd_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_cached_tables(x,t_fn,fwd_var,rf1,c))
+# else
+#define fwd_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_tables(x,t_fn,fwd_var,rf1,c))
+# endif
+#elif defined(FT1_SET)
+#undef dec_fmvars
+#define fwd_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ one_table(x,upr,t_fn,fwd_var,rf1,c))
+#else
+#define fwd_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ fwd_mcol(no_table(x,t_sbox,fwd_var,rf1,c)))
+#endif
+
+#if defined(FL4_SET)
+# if defined(LAST_ENC_ROUND_CACHE_TABLES)
+#define fwd_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_cached_tables(x,t_fl,fwd_var,rf1,c))
+# else
+#define fwd_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_tables(x,t_fl,fwd_var,rf1,c))
+# endif
+#elif defined(FL1_SET)
+#define fwd_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ one_table(x,ups,t_fl,fwd_var,rf1,c))
+#else
+#define fwd_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ no_table(x,t_sbox,fwd_var,rf1,c))
+#endif
+
+aes_rval aes_encrypt_cbc(const unsigned char *in, const unsigned char *in_iv, unsigned int num_blk,
+ unsigned char *out, const aes_encrypt_ctx cx[1])
+{ aes_32t locals(b0, b1);
+ const aes_32t *kp;
+ const aes_32t *kptr = cx->ks;
+#if defined(ENC_ROUND_CACHE_TABLES)
+ dtables(t_fn);
+#endif
+#if defined(LAST_ENC_ROUND_CACHE_TABLES)
+ dtables(t_fl);
+#endif
+
+#if defined( dec_fmvars )
+ dec_fmvars; /* declare variables for fwd_mcol() if needed */
+#endif
+
+#if defined( AES_ERR_CHK )
+ if( cx->rn != 10 && cx->rn != 12 && cx->rn != 14 )
+ return aes_error;
+#endif
+
+ // Load IV into b0.
+ state_in(b0, in_iv);
+
+ for (;num_blk; in += AES_BLOCK_SIZE, out += AES_BLOCK_SIZE, --num_blk)
+ {
+ kp = kptr;
+#if 0
+ // Read the plaintext into b1
+ state_in(b1, in);
+ // Do the CBC with b0 which is either the iv or the ciphertext of the previous block.
+ cbc(b1, b0);
+
+ // Xor b1 with the key schedule to get things started.
+ key_in(b0, b1, kp);
+#else
+ // Since xor is associative we mess with the ordering here to get the loads started early
+ key_in(b1, b0, kp); // Xor b0(IV) with the key schedule and assign to b1
+ state_in(b0, in); // Load block into b0
+ cbc(b0, b1); // Xor b0 with b1 and store in b0
+#endif
+
+#if defined(ENC_ROUND_CACHE_TABLES)
+ itables(t_fn);
+#endif
+
+#if (ENC_UNROLL == FULL)
+
+ switch(cx->rn)
+ {
+ case 14:
+ round(fwd_rnd, b1, b0, kp + 1 * N_COLS);
+ round(fwd_rnd, b0, b1, kp + 2 * N_COLS);
+ kp += 2 * N_COLS;
+ case 12:
+ round(fwd_rnd, b1, b0, kp + 1 * N_COLS);
+ round(fwd_rnd, b0, b1, kp + 2 * N_COLS);
+ kp += 2 * N_COLS;
+ case 10:
+ default:
+ round(fwd_rnd, b1, b0, kp + 1 * N_COLS);
+ round(fwd_rnd, b0, b1, kp + 2 * N_COLS);
+ round(fwd_rnd, b1, b0, kp + 3 * N_COLS);
+ round(fwd_rnd, b0, b1, kp + 4 * N_COLS);
+ round(fwd_rnd, b1, b0, kp + 5 * N_COLS);
+ round(fwd_rnd, b0, b1, kp + 6 * N_COLS);
+ round(fwd_rnd, b1, b0, kp + 7 * N_COLS);
+ round(fwd_rnd, b0, b1, kp + 8 * N_COLS);
+ round(fwd_rnd, b1, b0, kp + 9 * N_COLS);
+#if defined(LAST_ENC_ROUND_CACHE_TABLES)
+ itables(t_fl);
+#endif
+ round(fwd_lrnd, b0, b1, kp +10 * N_COLS);
+ }
+
+#else
+
+ { aes_32t rnd;
+#if (ENC_UNROLL == PARTIAL)
+ for(rnd = 0; rnd < (cx->rn >> 1) - 1; ++rnd)
+ {
+ kp += N_COLS;
+ round(fwd_rnd, b1, b0, kp);
+ kp += N_COLS;
+ round(fwd_rnd, b0, b1, kp);
+ }
+ kp += N_COLS;
+ round(fwd_rnd, b1, b0, kp);
+#else
+ for(rnd = 0; rnd < cx->rn - 1; ++rnd)
+ {
+ kp += N_COLS;
+ round(fwd_rnd, b1, b0, kp);
+ l_copy(b0, b1);
+ }
+#endif
+#if defined(LAST_ENC_ROUND_CACHE_TABLES)
+ itables(t_fl);
+#endif
+ kp += N_COLS;
+ round(fwd_lrnd, b0, b1, kp);
+ }
+#endif
+
+ state_out(out, b0);
+ }
+
+#if defined( AES_ERR_CHK )
+ return aes_good;
+#endif
+}
+
+#endif
+
+#if defined(DECRYPTION) && !defined(AES_ASM)
+
+/* Visual C++ .Net v7.1 provides the fastest encryption code when using
+ Pentium optimiation with small code but this is poor for decryption
+ so we need to control this with the following VC++ pragmas
+*/
+
+#if defined(_MSC_VER)
+#pragma optimize( "t", on )
+#endif
+
+/* Given the column (c) of the output state variable, the following
+ macros give the input state variables which are needed in its
+ computation for each row (r) of the state. All the alternative
+ macros give the same end values but expand into different ways
+ of calculating these values. In particular the complex macro
+ used for dynamically variable block sizes is designed to expand
+ to a compile time constant whenever possible but will expand to
+ conditional clauses on some branches (I am grateful to Frank
+ Yellin for this construction)
+*/
+
+#define inv_var(x,r,c)\
+ ( r == 0 ? ( c == 0 ? s(x,0) : c == 1 ? s(x,1) : c == 2 ? s(x,2) : s(x,3))\
+ : r == 1 ? ( c == 0 ? s(x,3) : c == 1 ? s(x,0) : c == 2 ? s(x,1) : s(x,2))\
+ : r == 2 ? ( c == 0 ? s(x,2) : c == 1 ? s(x,3) : c == 2 ? s(x,0) : s(x,1))\
+ : ( c == 0 ? s(x,1) : c == 1 ? s(x,2) : c == 2 ? s(x,3) : s(x,0)))
+
+#if defined(IT4_SET)
+#undef dec_imvars
+# if defined(DEC_ROUND_CACHE_TABLES)
+#define inv_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_cached_tables(x,t_in,inv_var,rf1,c))
+# else
+#define inv_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_tables(x,t_in,inv_var,rf1,c))
+# endif
+#elif defined(IT1_SET)
+#undef dec_imvars
+#define inv_rnd(y,x,k,c) (s(y,c) = (k)[c] ^ one_table(x,upr,t_in,inv_var,rf1,c))
+#else
+#define inv_rnd(y,x,k,c) (s(y,c) = inv_mcol((k)[c] ^ no_table(x,t_ibox,inv_var,rf1,c)))
+#endif
+
+#if defined(IL4_SET)
+# if defined(LAST_DEC_ROUND_CACHE_TABLES)
+#define inv_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_cached_tables(x,t_il,inv_var,rf1,c))
+# else
+#define inv_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ four_tables(x,t_il,inv_var,rf1,c))
+# endif
+#elif defined(IL1_SET)
+#define inv_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ one_table(x,ups,t_il,inv_var,rf1,c))
+#else
+#define inv_lrnd(y,x,k,c) (s(y,c) = (k)[c] ^ no_table(x,t_ibox,inv_var,rf1,c))
+#endif
+
+aes_rval aes_decrypt_cbc(const unsigned char *in, const unsigned char *in_iv, unsigned int num_blk,
+ unsigned char *out, const aes_decrypt_ctx cx[1])
+{ aes_32t locals(b0, b1);
+ const aes_32t *kptr = cx->ks + cx->rn * N_COLS;
+ const aes_32t *kp;
+#if defined(DEC_ROUND_CACHE_TABLES)
+ dtables(t_in);
+#endif
+#if defined(LAST_DEC_ROUND_CACHE_TABLES)
+ dtables(t_il);
+#endif
+
+#if defined( dec_imvars )
+ dec_imvars; /* declare variables for inv_mcol() if needed */
+#endif
+
+#if defined( AES_ERR_CHK )
+ if( cx->rn != 10 && cx->rn != 12 && cx->rn != 14 )
+ return aes_error;
+#endif
+
+#if defined(DEC_ROUND_CACHE_TABLES)
+ itables(t_in);
+#endif
+
+ in += AES_BLOCK_SIZE * (num_blk - 1);
+ out += AES_BLOCK_SIZE * (num_blk - 1);
+ // Load the last block's ciphertext into b1
+ state_in(b1, in);
+
+ for (;num_blk; out -= AES_BLOCK_SIZE, --num_blk)
+ {
+ kp = kptr;
+ // Do the xor part of state_in, where b1 is the previous block's ciphertext.
+ key_in(b0, b1, kp);
+
+#if (DEC_UNROLL == FULL)
+
+ switch(cx->rn)
+ {
+ case 14:
+ round(inv_rnd, b1, b0, kp - 1 * N_COLS);
+ round(inv_rnd, b0, b1, kp - 2 * N_COLS);
+ kp -= 2 * N_COLS;
+ case 12:
+ round(inv_rnd, b1, b0, kp - 1 * N_COLS);
+ round(inv_rnd, b0, b1, kp - 2 * N_COLS);
+ kp -= 2 * N_COLS;
+ case 10:
+ default:
+ round(inv_rnd, b1, b0, kp - 1 * N_COLS);
+ round(inv_rnd, b0, b1, kp - 2 * N_COLS);
+ round(inv_rnd, b1, b0, kp - 3 * N_COLS);
+ round(inv_rnd, b0, b1, kp - 4 * N_COLS);
+ round(inv_rnd, b1, b0, kp - 5 * N_COLS);
+ round(inv_rnd, b0, b1, kp - 6 * N_COLS);
+ round(inv_rnd, b1, b0, kp - 7 * N_COLS);
+ round(inv_rnd, b0, b1, kp - 8 * N_COLS);
+ round(inv_rnd, b1, b0, kp - 9 * N_COLS);
+#if defined(LAST_DEC_ROUND_CACHE_TABLES)
+ itables(t_il);
+#endif
+ round(inv_lrnd, b0, b1, kp - 10 * N_COLS);
+ }
+
+#else
+
+ { aes_32t rnd;
+#if (DEC_UNROLL == PARTIAL)
+ for(rnd = 0; rnd < (cx->rn >> 1) - 1; ++rnd)
+ {
+ kp -= N_COLS;
+ round(inv_rnd, b1, b0, kp);
+ kp -= N_COLS;
+ round(inv_rnd, b0, b1, kp);
+ }
+ kp -= N_COLS;
+ round(inv_rnd, b1, b0, kp);
+#else
+ for(rnd = 0; rnd < cx->rn - 1; ++rnd)
+ {
+ kp -= N_COLS;
+ round(inv_rnd, b1, b0, kp);
+ l_copy(b0, b1);
+ }
+#endif
+#if defined(LAST_DEC_ROUND_CACHE_TABLES)
+ itables(t_il);
+#endif
+ kp -= N_COLS;
+ round(inv_lrnd, b0, b1, kp);
+ }
+#endif
+
+ if (num_blk == 1)
+ {
+ // We are doing the first block so we need the IV rather than the previous
+ // block for CBC (there is no previous block)
+ state_in(b1, in_iv);
+ }
+ else
+ {
+ in -= AES_BLOCK_SIZE;
+ state_in(b1, in);
+ }
+
+ // Do the CBC with b1 which is either the IV or the ciphertext of the previous block.
+ cbc(b0, b1);
+
+ state_out(out, b0);
+ }
+#if defined( AES_ERR_CHK )
+ return aes_good;
+#endif
+}
+
+#endif
+
+#if defined(__cplusplus)
+}
+#endif
-/*\r
- ---------------------------------------------------------------------------\r
- Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved.\r
-\r
- LICENSE TERMS\r
-\r
- The free distribution and use of this software in both source and binary\r
- form is allowed (with or without changes) provided that:\r
-\r
- 1. distributions of this source code include the above copyright\r
- notice, this list of conditions and the following disclaimer;\r
-\r
- 2. distributions in binary form include the above copyright\r
- notice, this list of conditions and the following disclaimer\r
- in the documentation and/or other associated materials;\r
-\r
- 3. the copyright holder's name is not used to endorse products\r
- built using this software without specific written permission.\r
-\r
- ALTERNATIVELY, provided that this notice is retained in full, this product\r
- may be distributed under the terms of the GNU General Public License (GPL),\r
- in which case the provisions of the GPL apply INSTEAD OF those given above.\r
-\r
- DISCLAIMER\r
-\r
- This software is provided 'as is' with no explicit or implied warranties\r
- in respect of its properties, including, but not limited to, correctness\r
- and/or fitness for purpose.\r
- ---------------------------------------------------------------------------\r
- Issue Date: 26/08/2003\r
-\r
- This file contains the code for implementing the key schedule for AES\r
- (Rijndael) for block and key sizes of 16, 24, and 32 bytes. See aesopt.h\r
- for further details including optimisation.\r
-*/\r
-\r
-#include "aesopt.h"\r
-#include "aestab.h"\r
-\r
-#if defined(__cplusplus)\r
-extern "C"\r
-{\r
-#endif\r
-\r
-/* Initialise the key schedule from the user supplied key. The key\r
- length can be specified in bytes, with legal values of 16, 24\r
- and 32, or in bits, with legal values of 128, 192 and 256. These\r
- values correspond with Nk values of 4, 6 and 8 respectively.\r
-\r
- The following macros implement a single cycle in the key\r
- schedule generation process. The number of cycles needed\r
- for each cx->n_col and nk value is:\r
-\r
- nk = 4 5 6 7 8\r
- ------------------------------\r
- cx->n_col = 4 10 9 8 7 7\r
- cx->n_col = 5 14 11 10 9 9\r
- cx->n_col = 6 19 15 12 11 11\r
- cx->n_col = 7 21 19 16 13 14\r
- cx->n_col = 8 29 23 19 17 14\r
-*/\r
-\r
-#define ke4(k,i) \\r
-{ k[4*(i)+4] = ss[0] ^= ls_box(ss[3],3) ^ t_use(r,c)[i]; k[4*(i)+5] = ss[1] ^= ss[0]; \\r
- k[4*(i)+6] = ss[2] ^= ss[1]; k[4*(i)+7] = ss[3] ^= ss[2]; \\r
-}\r
-#define kel4(k,i) \\r
-{ k[4*(i)+4] = ss[0] ^= ls_box(ss[3],3) ^ t_use(r,c)[i]; k[4*(i)+5] = ss[1] ^= ss[0]; \\r
- k[4*(i)+6] = ss[2] ^= ss[1]; k[4*(i)+7] = ss[3] ^= ss[2]; \\r
-}\r
-\r
-#define ke6(k,i) \\r
-{ k[6*(i)+ 6] = ss[0] ^= ls_box(ss[5],3) ^ t_use(r,c)[i]; k[6*(i)+ 7] = ss[1] ^= ss[0]; \\r
- k[6*(i)+ 8] = ss[2] ^= ss[1]; k[6*(i)+ 9] = ss[3] ^= ss[2]; \\r
- k[6*(i)+10] = ss[4] ^= ss[3]; k[6*(i)+11] = ss[5] ^= ss[4]; \\r
-}\r
-#define kel6(k,i) \\r
-{ k[6*(i)+ 6] = ss[0] ^= ls_box(ss[5],3) ^ t_use(r,c)[i]; k[6*(i)+ 7] = ss[1] ^= ss[0]; \\r
- k[6*(i)+ 8] = ss[2] ^= ss[1]; k[6*(i)+ 9] = ss[3] ^= ss[2]; \\r
-}\r
-\r
-#define ke8(k,i) \\r
-{ k[8*(i)+ 8] = ss[0] ^= ls_box(ss[7],3) ^ t_use(r,c)[i]; k[8*(i)+ 9] = ss[1] ^= ss[0]; \\r
- k[8*(i)+10] = ss[2] ^= ss[1]; k[8*(i)+11] = ss[3] ^= ss[2]; \\r
- k[8*(i)+12] = ss[4] ^= ls_box(ss[3],0); k[8*(i)+13] = ss[5] ^= ss[4]; \\r
- k[8*(i)+14] = ss[6] ^= ss[5]; k[8*(i)+15] = ss[7] ^= ss[6]; \\r
-}\r
-#define kel8(k,i) \\r
-{ k[8*(i)+ 8] = ss[0] ^= ls_box(ss[7],3) ^ t_use(r,c)[i]; k[8*(i)+ 9] = ss[1] ^= ss[0]; \\r
- k[8*(i)+10] = ss[2] ^= ss[1]; k[8*(i)+11] = ss[3] ^= ss[2]; \\r
-}\r
-\r
-#if defined(ENCRYPTION_KEY_SCHEDULE)\r
-\r
-#if defined(AES_128) || defined(AES_VAR)\r
-\r
-aes_rval aes_encrypt_key128(const unsigned char *key, aes_encrypt_ctx cx[1])\r
-{ aes_32t ss[4];\r
-\r
- cx->ks[0] = ss[0] = word_in(key, 0);\r
- cx->ks[1] = ss[1] = word_in(key, 1);\r
- cx->ks[2] = ss[2] = word_in(key, 2);\r
- cx->ks[3] = ss[3] = word_in(key, 3);\r
-\r
-#if ENC_UNROLL == NONE\r
- { aes_32t i;\r
-\r
- for(i = 0; i < ((11 * N_COLS - 5) / 4); ++i)\r
- ke4(cx->ks, i);\r
- }\r
-#else\r
- ke4(cx->ks, 0); ke4(cx->ks, 1);\r
- ke4(cx->ks, 2); ke4(cx->ks, 3);\r
- ke4(cx->ks, 4); ke4(cx->ks, 5);\r
- ke4(cx->ks, 6); ke4(cx->ks, 7);\r
- ke4(cx->ks, 8);\r
-#endif\r
- kel4(cx->ks, 9);\r
- cx->rn = 10;\r
-#if defined( AES_ERR_CHK )\r
- return aes_good;\r
-#endif\r
-}\r
-\r
-#endif\r
-\r
-#if defined(AES_192) || defined(AES_VAR)\r
-\r
-aes_rval aes_encrypt_key192(const unsigned char *key, aes_encrypt_ctx cx[1])\r
-{ aes_32t ss[6];\r
-\r
- cx->ks[0] = ss[0] = word_in(key, 0);\r
- cx->ks[1] = ss[1] = word_in(key, 1);\r
- cx->ks[2] = ss[2] = word_in(key, 2);\r
- cx->ks[3] = ss[3] = word_in(key, 3);\r
- cx->ks[4] = ss[4] = word_in(key, 4);\r
- cx->ks[5] = ss[5] = word_in(key, 5);\r
-\r
-#if ENC_UNROLL == NONE\r
- { aes_32t i;\r
-\r
- for(i = 0; i < (13 * N_COLS - 7) / 6; ++i)\r
- ke6(cx->ks, i);\r
- }\r
-#else\r
- ke6(cx->ks, 0); ke6(cx->ks, 1);\r
- ke6(cx->ks, 2); ke6(cx->ks, 3);\r
- ke6(cx->ks, 4); ke6(cx->ks, 5);\r
- ke6(cx->ks, 6);\r
-#endif\r
- kel6(cx->ks, 7);\r
- cx->rn = 12;\r
-#if defined( AES_ERR_CHK )\r
- return aes_good;\r
-#endif\r
-}\r
-\r
-#endif\r
-\r
-#if defined(AES_256) || defined(AES_VAR)\r
-\r
-aes_rval aes_encrypt_key256(const unsigned char *key, aes_encrypt_ctx cx[1])\r
-{ aes_32t ss[8];\r
-\r
- cx->ks[0] = ss[0] = word_in(key, 0);\r
- cx->ks[1] = ss[1] = word_in(key, 1);\r
- cx->ks[2] = ss[2] = word_in(key, 2);\r
- cx->ks[3] = ss[3] = word_in(key, 3);\r
- cx->ks[4] = ss[4] = word_in(key, 4);\r
- cx->ks[5] = ss[5] = word_in(key, 5);\r
- cx->ks[6] = ss[6] = word_in(key, 6);\r
- cx->ks[7] = ss[7] = word_in(key, 7);\r
-\r
-#if ENC_UNROLL == NONE\r
- { aes_32t i;\r
-\r
- for(i = 0; i < (15 * N_COLS - 9) / 8; ++i)\r
- ke8(cx->ks, i);\r
- }\r
-#else\r
- ke8(cx->ks, 0); ke8(cx->ks, 1);\r
- ke8(cx->ks, 2); ke8(cx->ks, 3);\r
- ke8(cx->ks, 4); ke8(cx->ks, 5);\r
-#endif\r
- kel8(cx->ks, 6);\r
- cx->rn = 14;\r
-#if defined( AES_ERR_CHK )\r
- return aes_good;\r
-#endif\r
-}\r
-\r
-#endif\r
-\r
-#if defined(AES_VAR)\r
-\r
-aes_rval aes_encrypt_key(const unsigned char *key, int key_len, aes_encrypt_ctx cx[1])\r
-{\r
- switch(key_len)\r
- {\r
-#if defined( AES_ERR_CHK )\r
- case 16: case 128: return aes_encrypt_key128(key, cx);\r
- case 24: case 192: return aes_encrypt_key192(key, cx);\r
- case 32: case 256: return aes_encrypt_key256(key, cx);\r
- default: return aes_error;\r
-#else\r
- case 16: case 128: aes_encrypt_key128(key, cx); return;\r
- case 24: case 192: aes_encrypt_key192(key, cx); return;\r
- case 32: case 256: aes_encrypt_key256(key, cx); return;\r
-#endif\r
- }\r
-}\r
-\r
-#endif\r
-\r
-#endif\r
-\r
-#if defined(DECRYPTION_KEY_SCHEDULE)\r
-\r
-#if DEC_ROUND == NO_TABLES\r
-#define ff(x) (x)\r
-#else\r
-#define ff(x) inv_mcol(x)\r
-#if defined( dec_imvars )\r
-#define d_vars dec_imvars\r
-#endif\r
-#endif\r
-\r
-#if 1\r
-#define kdf4(k,i) \\r
-{ ss[0] = ss[0] ^ ss[2] ^ ss[1] ^ ss[3]; ss[1] = ss[1] ^ ss[3]; ss[2] = ss[2] ^ ss[3]; ss[3] = ss[3]; \\r
- ss[4] = ls_box(ss[(i+3) % 4], 3) ^ t_use(r,c)[i]; ss[i % 4] ^= ss[4]; \\r
- ss[4] ^= k[4*(i)]; k[4*(i)+4] = ff(ss[4]); ss[4] ^= k[4*(i)+1]; k[4*(i)+5] = ff(ss[4]); \\r
- ss[4] ^= k[4*(i)+2]; k[4*(i)+6] = ff(ss[4]); ss[4] ^= k[4*(i)+3]; k[4*(i)+7] = ff(ss[4]); \\r
-}\r
-#define kd4(k,i) \\r
-{ ss[4] = ls_box(ss[(i+3) % 4], 3) ^ t_use(r,c)[i]; ss[i % 4] ^= ss[4]; ss[4] = ff(ss[4]); \\r
- k[4*(i)+4] = ss[4] ^= k[4*(i)]; k[4*(i)+5] = ss[4] ^= k[4*(i)+1]; \\r
- k[4*(i)+6] = ss[4] ^= k[4*(i)+2]; k[4*(i)+7] = ss[4] ^= k[4*(i)+3]; \\r
-}\r
-#define kdl4(k,i) \\r
-{ ss[4] = ls_box(ss[(i+3) % 4], 3) ^ t_use(r,c)[i]; ss[i % 4] ^= ss[4]; \\r
- k[4*(i)+4] = (ss[0] ^= ss[1]) ^ ss[2] ^ ss[3]; k[4*(i)+5] = ss[1] ^ ss[3]; \\r
- k[4*(i)+6] = ss[0]; k[4*(i)+7] = ss[1]; \\r
-}\r
-#else\r
-#define kdf4(k,i) \\r
-{ ss[0] ^= ls_box(ss[3],3) ^ t_use(r,c)[i]; k[4*(i)+ 4] = ff(ss[0]); ss[1] ^= ss[0]; k[4*(i)+ 5] = ff(ss[1]); \\r
- ss[2] ^= ss[1]; k[4*(i)+ 6] = ff(ss[2]); ss[3] ^= ss[2]; k[4*(i)+ 7] = ff(ss[3]); \\r
-}\r
-#define kd4(k,i) \\r
-{ ss[4] = ls_box(ss[3],3) ^ t_use(r,c)[i]; \\r
- ss[0] ^= ss[4]; ss[4] = ff(ss[4]); k[4*(i)+ 4] = ss[4] ^= k[4*(i)]; \\r
- ss[1] ^= ss[0]; k[4*(i)+ 5] = ss[4] ^= k[4*(i)+ 1]; \\r
- ss[2] ^= ss[1]; k[4*(i)+ 6] = ss[4] ^= k[4*(i)+ 2]; \\r
- ss[3] ^= ss[2]; k[4*(i)+ 7] = ss[4] ^= k[4*(i)+ 3]; \\r
-}\r
-#define kdl4(k,i) \\r
-{ ss[0] ^= ls_box(ss[3],3) ^ t_use(r,c)[i]; k[4*(i)+ 4] = ss[0]; ss[1] ^= ss[0]; k[4*(i)+ 5] = ss[1]; \\r
- ss[2] ^= ss[1]; k[4*(i)+ 6] = ss[2]; ss[3] ^= ss[2]; k[4*(i)+ 7] = ss[3]; \\r
-}\r
-#endif\r
-\r
-#define kdf6(k,i) \\r
-{ ss[0] ^= ls_box(ss[5],3) ^ t_use(r,c)[i]; k[6*(i)+ 6] = ff(ss[0]); ss[1] ^= ss[0]; k[6*(i)+ 7] = ff(ss[1]); \\r
- ss[2] ^= ss[1]; k[6*(i)+ 8] = ff(ss[2]); ss[3] ^= ss[2]; k[6*(i)+ 9] = ff(ss[3]); \\r
- ss[4] ^= ss[3]; k[6*(i)+10] = ff(ss[4]); ss[5] ^= ss[4]; k[6*(i)+11] = ff(ss[5]); \\r
-}\r
-#define kd6(k,i) \\r
-{ ss[6] = ls_box(ss[5],3) ^ t_use(r,c)[i]; \\r
- ss[0] ^= ss[6]; ss[6] = ff(ss[6]); k[6*(i)+ 6] = ss[6] ^= k[6*(i)]; \\r
- ss[1] ^= ss[0]; k[6*(i)+ 7] = ss[6] ^= k[6*(i)+ 1]; \\r
- ss[2] ^= ss[1]; k[6*(i)+ 8] = ss[6] ^= k[6*(i)+ 2]; \\r
- ss[3] ^= ss[2]; k[6*(i)+ 9] = ss[6] ^= k[6*(i)+ 3]; \\r
- ss[4] ^= ss[3]; k[6*(i)+10] = ss[6] ^= k[6*(i)+ 4]; \\r
- ss[5] ^= ss[4]; k[6*(i)+11] = ss[6] ^= k[6*(i)+ 5]; \\r
-}\r
-#define kdl6(k,i) \\r
-{ ss[0] ^= ls_box(ss[5],3) ^ t_use(r,c)[i]; k[6*(i)+ 6] = ss[0]; ss[1] ^= ss[0]; k[6*(i)+ 7] = ss[1]; \\r
- ss[2] ^= ss[1]; k[6*(i)+ 8] = ss[2]; ss[3] ^= ss[2]; k[6*(i)+ 9] = ss[3]; \\r
-}\r
-\r
-#define kdf8(k,i) \\r
-{ ss[0] ^= ls_box(ss[7],3) ^ t_use(r,c)[i]; k[8*(i)+ 8] = ff(ss[0]); ss[1] ^= ss[0]; k[8*(i)+ 9] = ff(ss[1]); \\r
- ss[2] ^= ss[1]; k[8*(i)+10] = ff(ss[2]); ss[3] ^= ss[2]; k[8*(i)+11] = ff(ss[3]); \\r
- ss[4] ^= ls_box(ss[3],0); k[8*(i)+12] = ff(ss[4]); ss[5] ^= ss[4]; k[8*(i)+13] = ff(ss[5]); \\r
- ss[6] ^= ss[5]; k[8*(i)+14] = ff(ss[6]); ss[7] ^= ss[6]; k[8*(i)+15] = ff(ss[7]); \\r
-}\r
-#define kd8(k,i) \\r
-{ aes_32t g = ls_box(ss[7],3) ^ t_use(r,c)[i]; \\r
- ss[0] ^= g; g = ff(g); k[8*(i)+ 8] = g ^= k[8*(i)]; \\r
- ss[1] ^= ss[0]; k[8*(i)+ 9] = g ^= k[8*(i)+ 1]; \\r
- ss[2] ^= ss[1]; k[8*(i)+10] = g ^= k[8*(i)+ 2]; \\r
- ss[3] ^= ss[2]; k[8*(i)+11] = g ^= k[8*(i)+ 3]; \\r
- g = ls_box(ss[3],0); \\r
- ss[4] ^= g; g = ff(g); k[8*(i)+12] = g ^= k[8*(i)+ 4]; \\r
- ss[5] ^= ss[4]; k[8*(i)+13] = g ^= k[8*(i)+ 5]; \\r
- ss[6] ^= ss[5]; k[8*(i)+14] = g ^= k[8*(i)+ 6]; \\r
- ss[7] ^= ss[6]; k[8*(i)+15] = g ^= k[8*(i)+ 7]; \\r
-}\r
-#define kdl8(k,i) \\r
-{ ss[0] ^= ls_box(ss[7],3) ^ t_use(r,c)[i]; k[8*(i)+ 8] = ss[0]; ss[1] ^= ss[0]; k[8*(i)+ 9] = ss[1]; \\r
- ss[2] ^= ss[1]; k[8*(i)+10] = ss[2]; ss[3] ^= ss[2]; k[8*(i)+11] = ss[3]; \\r
-}\r
-\r
-#if defined(AES_128) || defined(AES_VAR)\r
-\r
-aes_rval aes_decrypt_key128(const unsigned char *key, aes_decrypt_ctx cx[1])\r
-{ aes_32t ss[5];\r
-#if defined( d_vars )\r
- d_vars;\r
-#endif\r
- cx->ks[0] = ss[0] = word_in(key, 0);\r
- cx->ks[1] = ss[1] = word_in(key, 1);\r
- cx->ks[2] = ss[2] = word_in(key, 2);\r
- cx->ks[3] = ss[3] = word_in(key, 3);\r
-\r
-#if DEC_UNROLL == NONE\r
- { aes_32t i;\r
-\r
- for(i = 0; i < (11 * N_COLS - 5) / 4; ++i)\r
- ke4(cx->ks, i);\r
- kel4(cx->ks, 9);\r
-#if !(DEC_ROUND == NO_TABLES)\r
- for(i = N_COLS; i < 10 * N_COLS; ++i)\r
- cx->ks[i] = inv_mcol(cx->ks[i]);\r
-#endif\r
- }\r
-#else\r
- kdf4(cx->ks, 0); kd4(cx->ks, 1);\r
- kd4(cx->ks, 2); kd4(cx->ks, 3);\r
- kd4(cx->ks, 4); kd4(cx->ks, 5);\r
- kd4(cx->ks, 6); kd4(cx->ks, 7);\r
- kd4(cx->ks, 8); kdl4(cx->ks, 9);\r
-#endif\r
- cx->rn = 10;\r
-#if defined( AES_ERR_CHK )\r
- return aes_good;\r
-#endif\r
-}\r
-\r
-#endif\r
-\r
-#if defined(AES_192) || defined(AES_VAR)\r
-\r
-aes_rval aes_decrypt_key192(const unsigned char *key, aes_decrypt_ctx cx[1])\r
-{ aes_32t ss[7];\r
-#if defined( d_vars )\r
- d_vars;\r
-#endif\r
- cx->ks[0] = ss[0] = word_in(key, 0);\r
- cx->ks[1] = ss[1] = word_in(key, 1);\r
- cx->ks[2] = ss[2] = word_in(key, 2);\r
- cx->ks[3] = ss[3] = word_in(key, 3);\r
-\r
-#if DEC_UNROLL == NONE\r
- cx->ks[4] = ss[4] = word_in(key, 4);\r
- cx->ks[5] = ss[5] = word_in(key, 5);\r
- { aes_32t i;\r
-\r
- for(i = 0; i < (13 * N_COLS - 7) / 6; ++i)\r
- ke6(cx->ks, i);\r
- kel6(cx->ks, 7);\r
-#if !(DEC_ROUND == NO_TABLES)\r
- for(i = N_COLS; i < 12 * N_COLS; ++i)\r
- cx->ks[i] = inv_mcol(cx->ks[i]);\r
-#endif\r
- }\r
-#else\r
- cx->ks[4] = ff(ss[4] = word_in(key, 4));\r
- cx->ks[5] = ff(ss[5] = word_in(key, 5));\r
- kdf6(cx->ks, 0); kd6(cx->ks, 1);\r
- kd6(cx->ks, 2); kd6(cx->ks, 3);\r
- kd6(cx->ks, 4); kd6(cx->ks, 5);\r
- kd6(cx->ks, 6); kdl6(cx->ks, 7);\r
-#endif\r
- cx->rn = 12;\r
-#if defined( AES_ERR_CHK )\r
- return aes_good;\r
-#endif\r
-}\r
-\r
-#endif\r
-\r
-#if defined(AES_256) || defined(AES_VAR)\r
-\r
-aes_rval aes_decrypt_key256(const unsigned char *key, aes_decrypt_ctx cx[1])\r
-{ aes_32t ss[8];\r
-#if defined( d_vars )\r
- d_vars;\r
-#endif\r
- cx->ks[0] = ss[0] = word_in(key, 0);\r
- cx->ks[1] = ss[1] = word_in(key, 1);\r
- cx->ks[2] = ss[2] = word_in(key, 2);\r
- cx->ks[3] = ss[3] = word_in(key, 3);\r
-\r
-#if DEC_UNROLL == NONE\r
- cx->ks[4] = ss[4] = word_in(key, 4);\r
- cx->ks[5] = ss[5] = word_in(key, 5);\r
- cx->ks[6] = ss[6] = word_in(key, 6);\r
- cx->ks[7] = ss[7] = word_in(key, 7);\r
- { aes_32t i;\r
-\r
- for(i = 0; i < (15 * N_COLS - 9) / 8; ++i)\r
- ke8(cx->ks, i);\r
- kel8(cx->ks, i);\r
-#if !(DEC_ROUND == NO_TABLES)\r
- for(i = N_COLS; i < 14 * N_COLS; ++i)\r
- cx->ks[i] = inv_mcol(cx->ks[i]);\r
-\r
-#endif\r
- }\r
-#else\r
- cx->ks[4] = ff(ss[4] = word_in(key, 4));\r
- cx->ks[5] = ff(ss[5] = word_in(key, 5));\r
- cx->ks[6] = ff(ss[6] = word_in(key, 6));\r
- cx->ks[7] = ff(ss[7] = word_in(key, 7));\r
- kdf8(cx->ks, 0); kd8(cx->ks, 1);\r
- kd8(cx->ks, 2); kd8(cx->ks, 3);\r
- kd8(cx->ks, 4); kd8(cx->ks, 5);\r
- kdl8(cx->ks, 6);\r
-#endif\r
- cx->rn = 14;\r
-#if defined( AES_ERR_CHK )\r
- return aes_good;\r
-#endif\r
-}\r
-\r
-#endif\r
-\r
-#if defined(AES_VAR)\r
-\r
-aes_rval aes_decrypt_key(const unsigned char *key, int key_len, aes_decrypt_ctx cx[1])\r
-{\r
- switch(key_len)\r
- {\r
-#if defined( AES_ERR_CHK )\r
- case 16: case 128: return aes_decrypt_key128(key, cx);\r
- case 24: case 192: return aes_decrypt_key192(key, cx);\r
- case 32: case 256: return aes_decrypt_key256(key, cx);\r
- default: return aes_error;\r
-#else\r
- case 16: case 128: aes_decrypt_key128(key, cx); return;\r
- case 24: case 192: aes_decrypt_key192(key, cx); return;\r
- case 32: case 256: aes_decrypt_key256(key, cx); return;\r
-#endif\r
- }\r
-}\r
-\r
-#endif\r
-\r
-#endif\r
-\r
-#if defined(__cplusplus)\r
-}\r
-#endif\r
+/*
+ ---------------------------------------------------------------------------
+ Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved.
+
+ LICENSE TERMS
+
+ The free distribution and use of this software in both source and binary
+ form is allowed (with or without changes) provided that:
+
+ 1. distributions of this source code include the above copyright
+ notice, this list of conditions and the following disclaimer;
+
+ 2. distributions in binary form include the above copyright
+ notice, this list of conditions and the following disclaimer
+ in the documentation and/or other associated materials;
+
+ 3. the copyright holder's name is not used to endorse products
+ built using this software without specific written permission.
+
+ ALTERNATIVELY, provided that this notice is retained in full, this product
+ may be distributed under the terms of the GNU General Public License (GPL),
+ in which case the provisions of the GPL apply INSTEAD OF those given above.
+
+ DISCLAIMER
+
+ This software is provided 'as is' with no explicit or implied warranties
+ in respect of its properties, including, but not limited to, correctness
+ and/or fitness for purpose.
+ ---------------------------------------------------------------------------
+ Issue Date: 26/08/2003
+
+ This file contains the code for implementing the key schedule for AES
+ (Rijndael) for block and key sizes of 16, 24, and 32 bytes. See aesopt.h
+ for further details including optimisation.
+*/
+
+#include "aesopt.h"
+#include "aestab.h"
+
+#if defined(__cplusplus)
+extern "C"
+{
+#endif
+
+/* Initialise the key schedule from the user supplied key. The key
+ length can be specified in bytes, with legal values of 16, 24
+ and 32, or in bits, with legal values of 128, 192 and 256. These
+ values correspond with Nk values of 4, 6 and 8 respectively.
+
+ The following macros implement a single cycle in the key
+ schedule generation process. The number of cycles needed
+ for each cx->n_col and nk value is:
+
+ nk = 4 5 6 7 8
+ ------------------------------
+ cx->n_col = 4 10 9 8 7 7
+ cx->n_col = 5 14 11 10 9 9
+ cx->n_col = 6 19 15 12 11 11
+ cx->n_col = 7 21 19 16 13 14
+ cx->n_col = 8 29 23 19 17 14
+*/
+
+#define ke4(k,i) \
+{ k[4*(i)+4] = ss[0] ^= ls_box(ss[3],3) ^ t_use(r,c)[i]; k[4*(i)+5] = ss[1] ^= ss[0]; \
+ k[4*(i)+6] = ss[2] ^= ss[1]; k[4*(i)+7] = ss[3] ^= ss[2]; \
+}
+#define kel4(k,i) \
+{ k[4*(i)+4] = ss[0] ^= ls_box(ss[3],3) ^ t_use(r,c)[i]; k[4*(i)+5] = ss[1] ^= ss[0]; \
+ k[4*(i)+6] = ss[2] ^= ss[1]; k[4*(i)+7] = ss[3] ^= ss[2]; \
+}
+
+#define ke6(k,i) \
+{ k[6*(i)+ 6] = ss[0] ^= ls_box(ss[5],3) ^ t_use(r,c)[i]; k[6*(i)+ 7] = ss[1] ^= ss[0]; \
+ k[6*(i)+ 8] = ss[2] ^= ss[1]; k[6*(i)+ 9] = ss[3] ^= ss[2]; \
+ k[6*(i)+10] = ss[4] ^= ss[3]; k[6*(i)+11] = ss[5] ^= ss[4]; \
+}
+#define kel6(k,i) \
+{ k[6*(i)+ 6] = ss[0] ^= ls_box(ss[5],3) ^ t_use(r,c)[i]; k[6*(i)+ 7] = ss[1] ^= ss[0]; \
+ k[6*(i)+ 8] = ss[2] ^= ss[1]; k[6*(i)+ 9] = ss[3] ^= ss[2]; \
+}
+
+#define ke8(k,i) \
+{ k[8*(i)+ 8] = ss[0] ^= ls_box(ss[7],3) ^ t_use(r,c)[i]; k[8*(i)+ 9] = ss[1] ^= ss[0]; \
+ k[8*(i)+10] = ss[2] ^= ss[1]; k[8*(i)+11] = ss[3] ^= ss[2]; \
+ k[8*(i)+12] = ss[4] ^= ls_box(ss[3],0); k[8*(i)+13] = ss[5] ^= ss[4]; \
+ k[8*(i)+14] = ss[6] ^= ss[5]; k[8*(i)+15] = ss[7] ^= ss[6]; \
+}
+#define kel8(k,i) \
+{ k[8*(i)+ 8] = ss[0] ^= ls_box(ss[7],3) ^ t_use(r,c)[i]; k[8*(i)+ 9] = ss[1] ^= ss[0]; \
+ k[8*(i)+10] = ss[2] ^= ss[1]; k[8*(i)+11] = ss[3] ^= ss[2]; \
+}
+
+#if defined(ENCRYPTION_KEY_SCHEDULE)
+
+#if defined(AES_128) || defined(AES_VAR)
+
+aes_rval aes_encrypt_key128(const unsigned char *key, aes_encrypt_ctx cx[1])
+{ aes_32t ss[4];
+
+ cx->ks[0] = ss[0] = word_in(key, 0);
+ cx->ks[1] = ss[1] = word_in(key, 1);
+ cx->ks[2] = ss[2] = word_in(key, 2);
+ cx->ks[3] = ss[3] = word_in(key, 3);
+
+#if ENC_UNROLL == NONE
+ { aes_32t i;
+
+ for(i = 0; i < ((11 * N_COLS - 5) / 4); ++i)
+ ke4(cx->ks, i);
+ }
+#else
+ ke4(cx->ks, 0); ke4(cx->ks, 1);
+ ke4(cx->ks, 2); ke4(cx->ks, 3);
+ ke4(cx->ks, 4); ke4(cx->ks, 5);
+ ke4(cx->ks, 6); ke4(cx->ks, 7);
+ ke4(cx->ks, 8);
+#endif
+ kel4(cx->ks, 9);
+ cx->rn = 10;
+#if defined( AES_ERR_CHK )
+ return aes_good;
+#endif
+}
+
+#endif
+
+#if defined(AES_192) || defined(AES_VAR)
+
+aes_rval aes_encrypt_key192(const unsigned char *key, aes_encrypt_ctx cx[1])
+{ aes_32t ss[6];
+
+ cx->ks[0] = ss[0] = word_in(key, 0);
+ cx->ks[1] = ss[1] = word_in(key, 1);
+ cx->ks[2] = ss[2] = word_in(key, 2);
+ cx->ks[3] = ss[3] = word_in(key, 3);
+ cx->ks[4] = ss[4] = word_in(key, 4);
+ cx->ks[5] = ss[5] = word_in(key, 5);
+
+#if ENC_UNROLL == NONE
+ { aes_32t i;
+
+ for(i = 0; i < (13 * N_COLS - 7) / 6; ++i)
+ ke6(cx->ks, i);
+ }
+#else
+ ke6(cx->ks, 0); ke6(cx->ks, 1);
+ ke6(cx->ks, 2); ke6(cx->ks, 3);
+ ke6(cx->ks, 4); ke6(cx->ks, 5);
+ ke6(cx->ks, 6);
+#endif
+ kel6(cx->ks, 7);
+ cx->rn = 12;
+#if defined( AES_ERR_CHK )
+ return aes_good;
+#endif
+}
+
+#endif
+
+#if defined(AES_256) || defined(AES_VAR)
+
+aes_rval aes_encrypt_key256(const unsigned char *key, aes_encrypt_ctx cx[1])
+{ aes_32t ss[8];
+
+ cx->ks[0] = ss[0] = word_in(key, 0);
+ cx->ks[1] = ss[1] = word_in(key, 1);
+ cx->ks[2] = ss[2] = word_in(key, 2);
+ cx->ks[3] = ss[3] = word_in(key, 3);
+ cx->ks[4] = ss[4] = word_in(key, 4);
+ cx->ks[5] = ss[5] = word_in(key, 5);
+ cx->ks[6] = ss[6] = word_in(key, 6);
+ cx->ks[7] = ss[7] = word_in(key, 7);
+
+#if ENC_UNROLL == NONE
+ { aes_32t i;
+
+ for(i = 0; i < (15 * N_COLS - 9) / 8; ++i)
+ ke8(cx->ks, i);
+ }
+#else
+ ke8(cx->ks, 0); ke8(cx->ks, 1);
+ ke8(cx->ks, 2); ke8(cx->ks, 3);
+ ke8(cx->ks, 4); ke8(cx->ks, 5);
+#endif
+ kel8(cx->ks, 6);
+ cx->rn = 14;
+#if defined( AES_ERR_CHK )
+ return aes_good;
+#endif
+}
+
+#endif
+
+#if defined(AES_VAR)
+
+aes_rval aes_encrypt_key(const unsigned char *key, int key_len, aes_encrypt_ctx cx[1])
+{
+ switch(key_len)
+ {
+#if defined( AES_ERR_CHK )
+ case 16: case 128: return aes_encrypt_key128(key, cx);
+ case 24: case 192: return aes_encrypt_key192(key, cx);
+ case 32: case 256: return aes_encrypt_key256(key, cx);
+ default: return aes_error;
+#else
+ case 16: case 128: aes_encrypt_key128(key, cx); return;
+ case 24: case 192: aes_encrypt_key192(key, cx); return;
+ case 32: case 256: aes_encrypt_key256(key, cx); return;
+#endif
+ }
+}
+
+#endif
+
+#endif
+
+#if defined(DECRYPTION_KEY_SCHEDULE)
+
+#if DEC_ROUND == NO_TABLES
+#define ff(x) (x)
+#else
+#define ff(x) inv_mcol(x)
+#if defined( dec_imvars )
+#define d_vars dec_imvars
+#endif
+#endif
+
+#if 1
+#define kdf4(k,i) \
+{ ss[0] = ss[0] ^ ss[2] ^ ss[1] ^ ss[3]; ss[1] = ss[1] ^ ss[3]; ss[2] = ss[2] ^ ss[3]; ss[3] = ss[3]; \
+ ss[4] = ls_box(ss[(i+3) % 4], 3) ^ t_use(r,c)[i]; ss[i % 4] ^= ss[4]; \
+ ss[4] ^= k[4*(i)]; k[4*(i)+4] = ff(ss[4]); ss[4] ^= k[4*(i)+1]; k[4*(i)+5] = ff(ss[4]); \
+ ss[4] ^= k[4*(i)+2]; k[4*(i)+6] = ff(ss[4]); ss[4] ^= k[4*(i)+3]; k[4*(i)+7] = ff(ss[4]); \
+}
+#define kd4(k,i) \
+{ ss[4] = ls_box(ss[(i+3) % 4], 3) ^ t_use(r,c)[i]; ss[i % 4] ^= ss[4]; ss[4] = ff(ss[4]); \
+ k[4*(i)+4] = ss[4] ^= k[4*(i)]; k[4*(i)+5] = ss[4] ^= k[4*(i)+1]; \
+ k[4*(i)+6] = ss[4] ^= k[4*(i)+2]; k[4*(i)+7] = ss[4] ^= k[4*(i)+3]; \
+}
+#define kdl4(k,i) \
+{ ss[4] = ls_box(ss[(i+3) % 4], 3) ^ t_use(r,c)[i]; ss[i % 4] ^= ss[4]; \
+ k[4*(i)+4] = (ss[0] ^= ss[1]) ^ ss[2] ^ ss[3]; k[4*(i)+5] = ss[1] ^ ss[3]; \
+ k[4*(i)+6] = ss[0]; k[4*(i)+7] = ss[1]; \
+}
+#else
+#define kdf4(k,i) \
+{ ss[0] ^= ls_box(ss[3],3) ^ t_use(r,c)[i]; k[4*(i)+ 4] = ff(ss[0]); ss[1] ^= ss[0]; k[4*(i)+ 5] = ff(ss[1]); \
+ ss[2] ^= ss[1]; k[4*(i)+ 6] = ff(ss[2]); ss[3] ^= ss[2]; k[4*(i)+ 7] = ff(ss[3]); \
+}
+#define kd4(k,i) \
+{ ss[4] = ls_box(ss[3],3) ^ t_use(r,c)[i]; \
+ ss[0] ^= ss[4]; ss[4] = ff(ss[4]); k[4*(i)+ 4] = ss[4] ^= k[4*(i)]; \
+ ss[1] ^= ss[0]; k[4*(i)+ 5] = ss[4] ^= k[4*(i)+ 1]; \
+ ss[2] ^= ss[1]; k[4*(i)+ 6] = ss[4] ^= k[4*(i)+ 2]; \
+ ss[3] ^= ss[2]; k[4*(i)+ 7] = ss[4] ^= k[4*(i)+ 3]; \
+}
+#define kdl4(k,i) \
+{ ss[0] ^= ls_box(ss[3],3) ^ t_use(r,c)[i]; k[4*(i)+ 4] = ss[0]; ss[1] ^= ss[0]; k[4*(i)+ 5] = ss[1]; \
+ ss[2] ^= ss[1]; k[4*(i)+ 6] = ss[2]; ss[3] ^= ss[2]; k[4*(i)+ 7] = ss[3]; \
+}
+#endif
+
+#define kdf6(k,i) \
+{ ss[0] ^= ls_box(ss[5],3) ^ t_use(r,c)[i]; k[6*(i)+ 6] = ff(ss[0]); ss[1] ^= ss[0]; k[6*(i)+ 7] = ff(ss[1]); \
+ ss[2] ^= ss[1]; k[6*(i)+ 8] = ff(ss[2]); ss[3] ^= ss[2]; k[6*(i)+ 9] = ff(ss[3]); \
+ ss[4] ^= ss[3]; k[6*(i)+10] = ff(ss[4]); ss[5] ^= ss[4]; k[6*(i)+11] = ff(ss[5]); \
+}
+#define kd6(k,i) \
+{ ss[6] = ls_box(ss[5],3) ^ t_use(r,c)[i]; \
+ ss[0] ^= ss[6]; ss[6] = ff(ss[6]); k[6*(i)+ 6] = ss[6] ^= k[6*(i)]; \
+ ss[1] ^= ss[0]; k[6*(i)+ 7] = ss[6] ^= k[6*(i)+ 1]; \
+ ss[2] ^= ss[1]; k[6*(i)+ 8] = ss[6] ^= k[6*(i)+ 2]; \
+ ss[3] ^= ss[2]; k[6*(i)+ 9] = ss[6] ^= k[6*(i)+ 3]; \
+ ss[4] ^= ss[3]; k[6*(i)+10] = ss[6] ^= k[6*(i)+ 4]; \
+ ss[5] ^= ss[4]; k[6*(i)+11] = ss[6] ^= k[6*(i)+ 5]; \
+}
+#define kdl6(k,i) \
+{ ss[0] ^= ls_box(ss[5],3) ^ t_use(r,c)[i]; k[6*(i)+ 6] = ss[0]; ss[1] ^= ss[0]; k[6*(i)+ 7] = ss[1]; \
+ ss[2] ^= ss[1]; k[6*(i)+ 8] = ss[2]; ss[3] ^= ss[2]; k[6*(i)+ 9] = ss[3]; \
+}
+
+#define kdf8(k,i) \
+{ ss[0] ^= ls_box(ss[7],3) ^ t_use(r,c)[i]; k[8*(i)+ 8] = ff(ss[0]); ss[1] ^= ss[0]; k[8*(i)+ 9] = ff(ss[1]); \
+ ss[2] ^= ss[1]; k[8*(i)+10] = ff(ss[2]); ss[3] ^= ss[2]; k[8*(i)+11] = ff(ss[3]); \
+ ss[4] ^= ls_box(ss[3],0); k[8*(i)+12] = ff(ss[4]); ss[5] ^= ss[4]; k[8*(i)+13] = ff(ss[5]); \
+ ss[6] ^= ss[5]; k[8*(i)+14] = ff(ss[6]); ss[7] ^= ss[6]; k[8*(i)+15] = ff(ss[7]); \
+}
+#define kd8(k,i) \
+{ aes_32t g = ls_box(ss[7],3) ^ t_use(r,c)[i]; \
+ ss[0] ^= g; g = ff(g); k[8*(i)+ 8] = g ^= k[8*(i)]; \
+ ss[1] ^= ss[0]; k[8*(i)+ 9] = g ^= k[8*(i)+ 1]; \
+ ss[2] ^= ss[1]; k[8*(i)+10] = g ^= k[8*(i)+ 2]; \
+ ss[3] ^= ss[2]; k[8*(i)+11] = g ^= k[8*(i)+ 3]; \
+ g = ls_box(ss[3],0); \
+ ss[4] ^= g; g = ff(g); k[8*(i)+12] = g ^= k[8*(i)+ 4]; \
+ ss[5] ^= ss[4]; k[8*(i)+13] = g ^= k[8*(i)+ 5]; \
+ ss[6] ^= ss[5]; k[8*(i)+14] = g ^= k[8*(i)+ 6]; \
+ ss[7] ^= ss[6]; k[8*(i)+15] = g ^= k[8*(i)+ 7]; \
+}
+#define kdl8(k,i) \
+{ ss[0] ^= ls_box(ss[7],3) ^ t_use(r,c)[i]; k[8*(i)+ 8] = ss[0]; ss[1] ^= ss[0]; k[8*(i)+ 9] = ss[1]; \
+ ss[2] ^= ss[1]; k[8*(i)+10] = ss[2]; ss[3] ^= ss[2]; k[8*(i)+11] = ss[3]; \
+}
+
+#if defined(AES_128) || defined(AES_VAR)
+
+aes_rval aes_decrypt_key128(const unsigned char *key, aes_decrypt_ctx cx[1])
+{ aes_32t ss[5];
+#if defined( d_vars )
+ d_vars;
+#endif
+ cx->ks[0] = ss[0] = word_in(key, 0);
+ cx->ks[1] = ss[1] = word_in(key, 1);
+ cx->ks[2] = ss[2] = word_in(key, 2);
+ cx->ks[3] = ss[3] = word_in(key, 3);
+
+#if DEC_UNROLL == NONE
+ { aes_32t i;
+
+ for(i = 0; i < (11 * N_COLS - 5) / 4; ++i)
+ ke4(cx->ks, i);
+ kel4(cx->ks, 9);
+#if !(DEC_ROUND == NO_TABLES)
+ for(i = N_COLS; i < 10 * N_COLS; ++i)
+ cx->ks[i] = inv_mcol(cx->ks[i]);
+#endif
+ }
+#else
+ kdf4(cx->ks, 0); kd4(cx->ks, 1);
+ kd4(cx->ks, 2); kd4(cx->ks, 3);
+ kd4(cx->ks, 4); kd4(cx->ks, 5);
+ kd4(cx->ks, 6); kd4(cx->ks, 7);
+ kd4(cx->ks, 8); kdl4(cx->ks, 9);
+#endif
+ cx->rn = 10;
+#if defined( AES_ERR_CHK )
+ return aes_good;
+#endif
+}
+
+#endif
+
+#if defined(AES_192) || defined(AES_VAR)
+
+aes_rval aes_decrypt_key192(const unsigned char *key, aes_decrypt_ctx cx[1])
+{ aes_32t ss[7];
+#if defined( d_vars )
+ d_vars;
+#endif
+ cx->ks[0] = ss[0] = word_in(key, 0);
+ cx->ks[1] = ss[1] = word_in(key, 1);
+ cx->ks[2] = ss[2] = word_in(key, 2);
+ cx->ks[3] = ss[3] = word_in(key, 3);
+
+#if DEC_UNROLL == NONE
+ cx->ks[4] = ss[4] = word_in(key, 4);
+ cx->ks[5] = ss[5] = word_in(key, 5);
+ { aes_32t i;
+
+ for(i = 0; i < (13 * N_COLS - 7) / 6; ++i)
+ ke6(cx->ks, i);
+ kel6(cx->ks, 7);
+#if !(DEC_ROUND == NO_TABLES)
+ for(i = N_COLS; i < 12 * N_COLS; ++i)
+ cx->ks[i] = inv_mcol(cx->ks[i]);
+#endif
+ }
+#else
+ cx->ks[4] = ff(ss[4] = word_in(key, 4));
+ cx->ks[5] = ff(ss[5] = word_in(key, 5));
+ kdf6(cx->ks, 0); kd6(cx->ks, 1);
+ kd6(cx->ks, 2); kd6(cx->ks, 3);
+ kd6(cx->ks, 4); kd6(cx->ks, 5);
+ kd6(cx->ks, 6); kdl6(cx->ks, 7);
+#endif
+ cx->rn = 12;
+#if defined( AES_ERR_CHK )
+ return aes_good;
+#endif
+}
+
+#endif
+
+#if defined(AES_256) || defined(AES_VAR)
+
+aes_rval aes_decrypt_key256(const unsigned char *key, aes_decrypt_ctx cx[1])
+{ aes_32t ss[8];
+#if defined( d_vars )
+ d_vars;
+#endif
+ cx->ks[0] = ss[0] = word_in(key, 0);
+ cx->ks[1] = ss[1] = word_in(key, 1);
+ cx->ks[2] = ss[2] = word_in(key, 2);
+ cx->ks[3] = ss[3] = word_in(key, 3);
+
+#if DEC_UNROLL == NONE
+ cx->ks[4] = ss[4] = word_in(key, 4);
+ cx->ks[5] = ss[5] = word_in(key, 5);
+ cx->ks[6] = ss[6] = word_in(key, 6);
+ cx->ks[7] = ss[7] = word_in(key, 7);
+ { aes_32t i;
+
+ for(i = 0; i < (15 * N_COLS - 9) / 8; ++i)
+ ke8(cx->ks, i);
+ kel8(cx->ks, i);
+#if !(DEC_ROUND == NO_TABLES)
+ for(i = N_COLS; i < 14 * N_COLS; ++i)
+ cx->ks[i] = inv_mcol(cx->ks[i]);
+
+#endif
+ }
+#else
+ cx->ks[4] = ff(ss[4] = word_in(key, 4));
+ cx->ks[5] = ff(ss[5] = word_in(key, 5));
+ cx->ks[6] = ff(ss[6] = word_in(key, 6));
+ cx->ks[7] = ff(ss[7] = word_in(key, 7));
+ kdf8(cx->ks, 0); kd8(cx->ks, 1);
+ kd8(cx->ks, 2); kd8(cx->ks, 3);
+ kd8(cx->ks, 4); kd8(cx->ks, 5);
+ kdl8(cx->ks, 6);
+#endif
+ cx->rn = 14;
+#if defined( AES_ERR_CHK )
+ return aes_good;
+#endif
+}
+
+#endif
+
+#if defined(AES_VAR)
+
+aes_rval aes_decrypt_key(const unsigned char *key, int key_len, aes_decrypt_ctx cx[1])
+{
+ switch(key_len)
+ {
+#if defined( AES_ERR_CHK )
+ case 16: case 128: return aes_decrypt_key128(key, cx);
+ case 24: case 192: return aes_decrypt_key192(key, cx);
+ case 32: case 256: return aes_decrypt_key256(key, cx);
+ default: return aes_error;
+#else
+ case 16: case 128: aes_decrypt_key128(key, cx); return;
+ case 24: case 192: aes_decrypt_key192(key, cx); return;
+ case 32: case 256: aes_decrypt_key256(key, cx); return;
+#endif
+ }
+}
+
+#endif
+
+#endif
+
+#if defined(__cplusplus)
+}
+#endif
-/*\r
- ---------------------------------------------------------------------------\r
- Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved.\r
-\r
- LICENSE TERMS\r
-\r
- The free distribution and use of this software in both source and binary\r
- form is allowed (with or without changes) provided that:\r
-\r
- 1. distributions of this source code include the above copyright\r
- notice, this list of conditions and the following disclaimer;\r
-\r
- 2. distributions in binary form include the above copyright\r
- notice, this list of conditions and the following disclaimer\r
- in the documentation and/or other associated materials;\r
-\r
- 3. the copyright holder's name is not used to endorse products\r
- built using this software without specific written permission.\r
-\r
- ALTERNATIVELY, provided that this notice is retained in full, this product\r
- may be distributed under the terms of the GNU General Public License (GPL),\r
- in which case the provisions of the GPL apply INSTEAD OF those given above.\r
-\r
- DISCLAIMER\r
-\r
- This software is provided 'as is' with no explicit or implied warranties\r
- in respect of its properties, including, but not limited to, correctness\r
- and/or fitness for purpose.\r
- ---------------------------------------------------------------------------\r
- Issue 28/01/2004\r
-\r
- My thanks go to Dag Arne Osvik for devising the schemes used here for key\r
- length derivation from the form of the key schedule\r
-\r
- This file contains the compilation options for AES (Rijndael) and code\r
- that is common across encryption, key scheduling and table generation.\r
-\r
- OPERATION\r
-\r
- These source code files implement the AES algorithm Rijndael designed by\r
- Joan Daemen and Vincent Rijmen. This version is designed for the standard\r
- block size of 16 bytes and for key sizes of 128, 192 and 256 bits (16, 24\r
- and 32 bytes).\r
-\r
- This version is designed for flexibility and speed using operations on\r
- 32-bit words rather than operations on bytes. It can be compiled with\r
- either big or little endian internal byte order but is faster when the\r
- native byte order for the processor is used.\r
-\r
- THE CIPHER INTERFACE\r
-\r
- The cipher interface is implemented as an array of bytes in which lower\r
- AES bit sequence indexes map to higher numeric significance within bytes.\r
-\r
- aes_08t (an unsigned 8-bit type)\r
- aes_32t (an unsigned 32-bit type)\r
- struct aes_encrypt_ctx (structure for the cipher encryption context)\r
- struct aes_decrypt_ctx (structure for the cipher decryption context)\r
- aes_rval the function return type\r
-\r
- C subroutine calls:\r
-\r
- aes_rval aes_encrypt_key128(const unsigned char *key, aes_encrypt_ctx cx[1]);\r
- aes_rval aes_encrypt_key192(const unsigned char *key, aes_encrypt_ctx cx[1]);\r
- aes_rval aes_encrypt_key256(const unsigned char *key, aes_encrypt_ctx cx[1]);\r
- aes_rval aes_encrypt(const unsigned char *in, unsigned char *out,\r
- const aes_encrypt_ctx cx[1]);\r
-\r
- aes_rval aes_decrypt_key128(const unsigned char *key, aes_decrypt_ctx cx[1]);\r
- aes_rval aes_decrypt_key192(const unsigned char *key, aes_decrypt_ctx cx[1]);\r
- aes_rval aes_decrypt_key256(const unsigned char *key, aes_decrypt_ctx cx[1]);\r
- aes_rval aes_decrypt(const unsigned char *in, unsigned char *out,\r
- const aes_decrypt_ctx cx[1]);\r
-\r
- IMPORTANT NOTE: If you are using this C interface with dynamic tables make sure that\r
- you call genTabs() before AES is used so that the tables are initialised.\r
-\r
- C++ aes class subroutines:\r
-\r
- Class AESencrypt for encryption\r
-\r
- Construtors:\r
- AESencrypt(void)\r
- AESencrypt(const unsigned char *key) - 128 bit key\r
- Members:\r
- aes_rval key128(const unsigned char *key)\r
- aes_rval key192(const unsigned char *key)\r
- aes_rval key256(const unsigned char *key)\r
- aes_rval encrypt(const unsigned char *in, unsigned char *out) const\r
-\r
- Class AESdecrypt for encryption\r
- Construtors:\r
- AESdecrypt(void)\r
- AESdecrypt(const unsigned char *key) - 128 bit key\r
- Members:\r
- aes_rval key128(const unsigned char *key)\r
- aes_rval key192(const unsigned char *key)\r
- aes_rval key256(const unsigned char *key)\r
- aes_rval decrypt(const unsigned char *in, unsigned char *out) const\r
-\r
- COMPILATION\r
-\r
- The files used to provide AES (Rijndael) are\r
-\r
- a. aes.h for the definitions needed for use in C.\r
- b. aescpp.h for the definitions needed for use in C++.\r
- c. aesopt.h for setting compilation options (also includes common code).\r
- d. aescrypt.c for encryption and decrytpion, or\r
- e. aeskey.c for key scheduling.\r
- f. aestab.c for table loading or generation.\r
- g. aescrypt.asm for encryption and decryption using assembler code.\r
- h. aescrypt.mmx.asm for encryption and decryption using MMX assembler.\r
-\r
- To compile AES (Rijndael) for use in C code use aes.h and set the\r
- defines here for the facilities you need (key lengths, encryption\r
- and/or decryption). Do not define AES_DLL or AES_CPP. Set the options\r
- for optimisations and table sizes here.\r
-\r
- To compile AES (Rijndael) for use in in C++ code use aescpp.h but do\r
- not define AES_DLL\r
-\r
- To compile AES (Rijndael) in C as a Dynamic Link Library DLL) use\r
- aes.h and include the AES_DLL define.\r
-\r
- CONFIGURATION OPTIONS (here and in aes.h)\r
-\r
- a. set AES_DLL in aes.h if AES (Rijndael) is to be compiled as a DLL\r
- b. You may need to set PLATFORM_BYTE_ORDER to define the byte order.\r
- c. If you want the code to run in a specific internal byte order, then\r
- ALGORITHM_BYTE_ORDER must be set accordingly.\r
- d. set other configuration options decribed below.\r
-*/\r
-\r
-#if !defined( _AESOPT_H )\r
-#define _AESOPT_H\r
-\r
-#include "aes.h"\r
-\r
-/* CONFIGURATION - USE OF DEFINES\r
-\r
- Later in this section there are a number of defines that control the\r
- operation of the code. In each section, the purpose of each define is\r
- explained so that the relevant form can be included or excluded by\r
- setting either 1's or 0's respectively on the branches of the related\r
- #if clauses.\r
-\r
- PLATFORM SPECIFIC INCLUDES AND BYTE ORDER IN 32-BIT WORDS\r
-\r
- To obtain the highest speed on processors with 32-bit words, this code\r
- needs to determine the byte order of the target machine. The following\r
- block of code is an attempt to capture the most obvious ways in which\r
- various environemnts define byte order. It may well fail, in which case\r
- the definitions will need to be set by editing at the points marked\r
- **** EDIT HERE IF NECESSARY **** below. My thanks go to Peter Gutmann\r
- for his assistance with this endian detection nightmare.\r
-*/\r
-\r
-#define BRG_LITTLE_ENDIAN 1234 /* byte 0 is least significant (i386) */\r
-#define BRG_BIG_ENDIAN 4321 /* byte 0 is most significant (mc68k) */\r
-\r
-#if defined(__GNUC__) || defined(__GNU_LIBRARY__)\r
-# if defined(__FreeBSD__) || defined(__OpenBSD__)\r
-# include <sys/endian.h>\r
-# elif defined( BSD ) && BSD >= 199103\r
-# include <machine/endian.h>\r
-# elif defined(__APPLE__)\r
-# if defined(__BIG_ENDIAN__) && !defined( BIG_ENDIAN )\r
-# define BIG_ENDIAN\r
-# elif defined(__LITTLE_ENDIAN__) && !defined( LITTLE_ENDIAN )\r
-# define LITTLE_ENDIAN\r
-# endif\r
-# else\r
-# include <endian.h>\r
-# if defined(__BEOS__)\r
-# include <byteswap.h>\r
-# endif\r
-# endif\r
-#endif\r
-\r
-#if !defined(PLATFORM_BYTE_ORDER)\r
-# if defined(LITTLE_ENDIAN) || defined(BIG_ENDIAN)\r
-# if defined(LITTLE_ENDIAN) && !defined(BIG_ENDIAN)\r
-# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN\r
-# elif !defined(LITTLE_ENDIAN) && defined(BIG_ENDIAN)\r
-# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN\r
-# elif defined(BYTE_ORDER) && (BYTE_ORDER == LITTLE_ENDIAN)\r
-# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN\r
-# elif defined(BYTE_ORDER) && (BYTE_ORDER == BIG_ENDIAN)\r
-# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN\r
-# endif\r
-# elif defined(_LITTLE_ENDIAN) || defined(_BIG_ENDIAN)\r
-# if defined(_LITTLE_ENDIAN) && !defined(_BIG_ENDIAN)\r
-# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN\r
-# elif !defined(_LITTLE_ENDIAN) && defined(_BIG_ENDIAN)\r
-# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN\r
-# elif defined(_BYTE_ORDER) && (_BYTE_ORDER == _LITTLE_ENDIAN)\r
-# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN\r
-# elif defined(_BYTE_ORDER) && (_BYTE_ORDER == _BIG_ENDIAN)\r
-# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN\r
-# endif\r
-# elif defined(__LITTLE_ENDIAN__) || defined(__BIG_ENDIAN__)\r
-# if defined(__LITTLE_ENDIAN__) && !defined(__BIG_ENDIAN__)\r
-# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN\r
-# elif !defined(__LITTLE_ENDIAN__) && defined(__BIG_ENDIAN__)\r
-# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN\r
-# elif defined(__BYTE_ORDER__) && (__BYTE_ORDER__ == __LITTLE_ENDIAN__)\r
-# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN\r
-# elif defined(__BYTE_ORDER__) && (__BYTE_ORDER__ == __BIG_ENDIAN__)\r
-# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN\r
-# endif\r
-# endif\r
-#endif\r
-\r
-/* if the platform is still unknown, try to find its byte order */\r
-/* from commonly used machine defines */\r
-\r
-#if !defined(PLATFORM_BYTE_ORDER)\r
-\r
-#if defined( __alpha__ ) || defined( __alpha ) || defined( i386 ) || \\r
- defined( __i386__ ) || defined( _M_I86 ) || defined( _M_IX86 ) || \\r
- defined( __OS2__ ) || defined( sun386 ) || defined( __TURBOC__ ) || \\r
- defined( vax ) || defined( vms ) || defined( VMS ) || \\r
- defined( __VMS )\r
-# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN\r
-\r
-#elif defined( AMIGA ) || defined( applec ) || defined( __AS400__ ) || \\r
- defined( _CRAY ) || defined( __hppa ) || defined( __hp9000 ) || \\r
- defined( ibm370 ) || defined( mc68000 ) || defined( m68k ) || \\r
- defined( __MRC__ ) || defined( __MVS__ ) || defined( __MWERKS__ ) || \\r
- defined( sparc ) || defined( __sparc) || defined( SYMANTEC_C ) || \\r
- defined( __TANDEM ) || defined( THINK_C ) || defined( __VMCMS__ )\r
-# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN\r
-\r
-#elif 0 /* **** EDIT HERE IF NECESSARY **** */\r
-# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN\r
-#elif 0 /* **** EDIT HERE IF NECESSARY **** */\r
-# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN\r
-#else\r
-# error Please edit aesopt.h (line 234 or 236) to set the platform byte order\r
-#endif\r
-\r
-#endif\r
-\r
-/* SOME LOCAL DEFINITIONS */\r
-\r
-#define NO_TABLES 0\r
-#define ONE_TABLE 1\r
-#define FOUR_TABLES 4\r
-#define NONE 0\r
-#define PARTIAL 1\r
-#define FULL 2\r
-\r
-#if defined(bswap32)\r
-#define aes_sw32 bswap32\r
-#elif defined(bswap_32)\r
-#define aes_sw32 bswap_32\r
-#else\r
-#define brot(x,n) (((aes_32t)(x) << n) | ((aes_32t)(x) >> (32 - n)))\r
-#define aes_sw32(x) ((brot((x),8) & 0x00ff00ff) | (brot((x),24) & 0xff00ff00))\r
-#endif\r
-\r
-/* 1. FUNCTIONS REQUIRED\r
-\r
- This implementation provides subroutines for encryption, decryption\r
- and for setting the three key lengths (separately) for encryption\r
- and decryption. When the assembler code is not being used the following\r
- definition blocks allow the selection of the routines that are to be\r
- included in the compilation.\r
-*/\r
-#if defined( AES_ENCRYPT )\r
-#define ENCRYPTION\r
-#define ENCRYPTION_KEY_SCHEDULE\r
-#endif\r
-\r
-#if defined( AES_DECRYPT )\r
-#define DECRYPTION\r
-#define DECRYPTION_KEY_SCHEDULE\r
-#endif\r
-\r
-/* 2. ASSEMBLER SUPPORT\r
-\r
- This define (which can be on the command line) enables the use of the\r
- assembler code routines for encryption and decryption with the C code\r
- only providing key scheduling\r
-*/\r
-#if 0 && !defined(AES_ASM)\r
-#define AES_ASM\r
-#endif\r
-\r
-/* 3. BYTE ORDER WITHIN 32 BIT WORDS\r
-\r
- The fundamental data processing units in Rijndael are 8-bit bytes. The\r
- input, output and key input are all enumerated arrays of bytes in which\r
- bytes are numbered starting at zero and increasing to one less than the\r
- number of bytes in the array in question. This enumeration is only used\r
- for naming bytes and does not imply any adjacency or order relationship\r
- from one byte to another. When these inputs and outputs are considered\r
- as bit sequences, bits 8*n to 8*n+7 of the bit sequence are mapped to\r
- byte[n] with bit 8n+i in the sequence mapped to bit 7-i within the byte.\r
- In this implementation bits are numbered from 0 to 7 starting at the\r
- numerically least significant end of each byte (bit n represents 2^n).\r
-\r
- However, Rijndael can be implemented more efficiently using 32-bit\r
- words by packing bytes into words so that bytes 4*n to 4*n+3 are placed\r
- into word[n]. While in principle these bytes can be assembled into words\r
- in any positions, this implementation only supports the two formats in\r
- which bytes in adjacent positions within words also have adjacent byte\r
- numbers. This order is called big-endian if the lowest numbered bytes\r
- in words have the highest numeric significance and little-endian if the\r
- opposite applies.\r
-\r
- This code can work in either order irrespective of the order used by the\r
- machine on which it runs. Normally the internal byte order will be set\r
- to the order of the processor on which the code is to be run but this\r
- define can be used to reverse this in special situations\r
-\r
- NOTE: Assembler code versions rely on PLATFORM_BYTE_ORDER being set\r
-*/\r
-#if 1 || defined(AES_ASM)\r
-#define ALGORITHM_BYTE_ORDER PLATFORM_BYTE_ORDER\r
-#elif 0\r
-#define ALGORITHM_BYTE_ORDER BRG_LITTLE_ENDIAN\r
-#elif 0\r
-#define ALGORITHM_BYTE_ORDER BRG_BIG_ENDIAN\r
-#else\r
-#error The algorithm byte order is not defined\r
-#endif\r
-\r
-/* 4. FAST INPUT/OUTPUT OPERATIONS.\r
-\r
- On some machines it is possible to improve speed by transferring the\r
- bytes in the input and output arrays to and from the internal 32-bit\r
- variables by addressing these arrays as if they are arrays of 32-bit\r
- words. On some machines this will always be possible but there may\r
- be a large performance penalty if the byte arrays are not aligned on\r
- the normal word boundaries. On other machines this technique will\r
- lead to memory access errors when such 32-bit word accesses are not\r
- properly aligned. The option SAFE_IO avoids such problems but will\r
- often be slower on those machines that support misaligned access\r
- (especially so if care is taken to align the input and output byte\r
- arrays on 32-bit word boundaries). If SAFE_IO is not defined it is\r
- assumed that access to byte arrays as if they are arrays of 32-bit\r
- words will not cause problems when such accesses are misaligned.\r
-*/\r
-#if 0 && !defined(_MSC_VER)\r
-#define SAFE_IO\r
-#endif\r
-\r
-/* 5. LOOP UNROLLING\r
-\r
- The code for encryption and decrytpion cycles through a number of rounds\r
- that can be implemented either in a loop or by expanding the code into a\r
- long sequence of instructions, the latter producing a larger program but\r
- one that will often be much faster. The latter is called loop unrolling.\r
- There are also potential speed advantages in expanding two iterations in\r
- a loop with half the number of iterations, which is called partial loop\r
- unrolling. The following options allow partial or full loop unrolling\r
- to be set independently for encryption and decryption\r
-*/\r
-#if 1\r
-#define ENC_UNROLL FULL\r
-#elif 0\r
-#define ENC_UNROLL PARTIAL\r
-#else\r
-#define ENC_UNROLL NONE\r
-#endif\r
-\r
-#if 1\r
-#define DEC_UNROLL FULL\r
-#elif 0\r
-#define DEC_UNROLL PARTIAL\r
-#else\r
-#define DEC_UNROLL NONE\r
-#endif\r
-\r
-/* 6. FAST FINITE FIELD OPERATIONS\r
-\r
- If this section is included, tables are used to provide faster finite\r
- field arithmetic (this has no effect if FIXED_TABLES is defined).\r
-*/\r
-#if 1\r
-#define FF_TABLES\r
-#endif\r
-\r
-/* 7. INTERNAL STATE VARIABLE FORMAT\r
-\r
- The internal state of Rijndael is stored in a number of local 32-bit\r
- word varaibles which can be defined either as an array or as individual\r
- names variables. Include this section if you want to store these local\r
- varaibles in arrays. Otherwise individual local variables will be used.\r
-*/\r
-#if 0\r
-#define ARRAYS\r
-#endif\r
-\r
-/* In this implementation the columns of the state array are each held in\r
- 32-bit words. The state array can be held in various ways: in an array\r
- of words, in a number of individual word variables or in a number of\r
- processor registers. The following define maps a variable name x and\r
- a column number c to the way the state array variable is to be held.\r
- The first define below maps the state into an array x[c] whereas the\r
- second form maps the state into a number of individual variables x0,\r
- x1, etc. Another form could map individual state colums to machine\r
- register names.\r
-*/\r
-\r
-#if defined(ARRAYS)\r
-#define s(x,c) x[c]\r
-#else\r
-#define s(x,c) x##c\r
-#endif\r
-\r
-/* 8. FIXED OR DYNAMIC TABLES\r
-\r
- When this section is included the tables used by the code are compiled\r
- statically into the binary file. Otherwise the subroutine gen_tabs()\r
- must be called to compute them before the code is first used.\r
-*/\r
-#if 1\r
-#define FIXED_TABLES\r
-#endif\r
-\r
-/* 9. TABLE ALIGNMENT\r
-\r
- On some sytsems speed will be improved by aligning the AES large lookup\r
- tables on particular boundaries. This define should be set to a power of\r
- two giving the desired alignment. It can be left undefined if alignment\r
- is not needed. This option is specific to the Microsft VC++ compiler -\r
- it seems to sometimes cause trouble for the VC++ version 6 compiler.\r
-*/\r
-\r
-#if 0 && defined(_MSC_VER) && (_MSC_VER >= 1300)\r
-#define TABLE_ALIGN 64\r
-#endif\r
-\r
-/* 10. INTERNAL TABLE CONFIGURATION\r
-\r
- This cipher proceeds by repeating in a number of cycles known as 'rounds'\r
- which are implemented by a round function which can optionally be speeded\r
- up using tables. The basic tables are each 256 32-bit words, with either\r
- one or four tables being required for each round function depending on\r
- how much speed is required. The encryption and decryption round functions\r
- are different and the last encryption and decrytpion round functions are\r
- different again making four different round functions in all.\r
-\r
- This means that:\r
- 1. Normal encryption and decryption rounds can each use either 0, 1\r
- or 4 tables and table spaces of 0, 1024 or 4096 bytes each.\r
- 2. The last encryption and decryption rounds can also use either 0, 1\r
- or 4 tables and table spaces of 0, 1024 or 4096 bytes each.\r
-\r
- Include or exclude the appropriate definitions below to set the number\r
- of tables used by this implementation.\r
-*/\r
-\r
-#if 1 /* set tables for the normal encryption round */\r
-#define ENC_ROUND FOUR_TABLES\r
-#elif 0\r
-#define ENC_ROUND ONE_TABLE\r
-#else\r
-#define ENC_ROUND NO_TABLES\r
-#endif\r
-\r
-#if 1 /* set tables for the last encryption round */\r
-#define LAST_ENC_ROUND FOUR_TABLES\r
-#elif 0\r
-#define LAST_ENC_ROUND ONE_TABLE\r
-#else\r
-#define LAST_ENC_ROUND NO_TABLES\r
-#endif\r
-\r
-#if 1 /* set tables for the normal decryption round */\r
-#define DEC_ROUND FOUR_TABLES\r
-#elif 0\r
-#define DEC_ROUND ONE_TABLE\r
-#else\r
-#define DEC_ROUND NO_TABLES\r
-#endif\r
-\r
-#if 1 /* set tables for the last decryption round */\r
-#define LAST_DEC_ROUND FOUR_TABLES\r
-#elif 0\r
-#define LAST_DEC_ROUND ONE_TABLE\r
-#else\r
-#define LAST_DEC_ROUND NO_TABLES\r
-#endif\r
-\r
-/* The decryption key schedule can be speeded up with tables in the same\r
- way that the round functions can. Include or exclude the following\r
- defines to set this requirement.\r
-*/\r
-#if 1\r
-#define KEY_SCHED FOUR_TABLES\r
-#elif 0\r
-#define KEY_SCHED ONE_TABLE\r
-#else\r
-#define KEY_SCHED NO_TABLES\r
-#endif\r
-\r
-/* 11. TABLE POINTER CACHING\r
-\r
- Normally tables are referenced directly, Enable this option if you wish to\r
- cache pointers to the tables in the encrypt/decrypt code. Note that this\r
- only works if you are using FOUR_TABLES for the ROUND you enable this for.\r
-*/\r
-#if 1\r
-#define ENC_ROUND_CACHE_TABLES\r
-#endif\r
-#if 1\r
-#define LAST_ENC_ROUND_CACHE_TABLES\r
-#endif\r
-#if 1\r
-#define DEC_ROUND_CACHE_TABLES\r
-#endif\r
-#if 1\r
-#define LAST_DEC_ROUND_CACHE_TABLES\r
-#endif\r
-\r
-\r
-/* END OF CONFIGURATION OPTIONS */\r
-\r
-#define RC_LENGTH (5 * (AES_BLOCK_SIZE / 4 - 2))\r
-\r
-/* Disable or report errors on some combinations of options */\r
-\r
-#if ENC_ROUND == NO_TABLES && LAST_ENC_ROUND != NO_TABLES\r
-#undef LAST_ENC_ROUND\r
-#define LAST_ENC_ROUND NO_TABLES\r
-#elif ENC_ROUND == ONE_TABLE && LAST_ENC_ROUND == FOUR_TABLES\r
-#undef LAST_ENC_ROUND\r
-#define LAST_ENC_ROUND ONE_TABLE\r
-#endif\r
-\r
-#if ENC_ROUND == NO_TABLES && ENC_UNROLL != NONE\r
-#undef ENC_UNROLL\r
-#define ENC_UNROLL NONE\r
-#endif\r
-\r
-#if DEC_ROUND == NO_TABLES && LAST_DEC_ROUND != NO_TABLES\r
-#undef LAST_DEC_ROUND\r
-#define LAST_DEC_ROUND NO_TABLES\r
-#elif DEC_ROUND == ONE_TABLE && LAST_DEC_ROUND == FOUR_TABLES\r
-#undef LAST_DEC_ROUND\r
-#define LAST_DEC_ROUND ONE_TABLE\r
-#endif\r
-\r
-#if DEC_ROUND == NO_TABLES && DEC_UNROLL != NONE\r
-#undef DEC_UNROLL\r
-#define DEC_UNROLL NONE\r
-#endif\r
-\r
-/* upr(x,n): rotates bytes within words by n positions, moving bytes to\r
- higher index positions with wrap around into low positions\r
- ups(x,n): moves bytes by n positions to higher index positions in\r
- words but without wrap around\r
- bval(x,n): extracts a byte from a word\r
-\r
- NOTE: The definitions given here are intended only for use with\r
- unsigned variables and with shift counts that are compile\r
- time constants\r
-*/\r
-\r
-#if (ALGORITHM_BYTE_ORDER == BRG_LITTLE_ENDIAN)\r
-#define upr(x,n) (((aes_32t)(x) << (8 * (n))) | ((aes_32t)(x) >> (32 - 8 * (n))))\r
-#define ups(x,n) ((aes_32t) (x) << (8 * (n)))\r
-#define bval(x,n) ((aes_08t)((x) >> (8 * (n))))\r
-#define bytes2word(b0, b1, b2, b3) \\r
- (((aes_32t)(b3) << 24) | ((aes_32t)(b2) << 16) | ((aes_32t)(b1) << 8) | (b0))\r
-#endif\r
-\r
-#if (ALGORITHM_BYTE_ORDER == BRG_BIG_ENDIAN)\r
-#define upr(x,n) (((aes_32t)(x) >> (8 * (n))) | ((aes_32t)(x) << (32 - 8 * (n))))\r
-#define ups(x,n) ((aes_32t) (x) >> (8 * (n))))\r
-#define bval(x,n) ((aes_08t)((x) >> (24 - 8 * (n))))\r
-#define bytes2word(b0, b1, b2, b3) \\r
- (((aes_32t)(b0) << 24) | ((aes_32t)(b1) << 16) | ((aes_32t)(b2) << 8) | (b3))\r
-#endif\r
-\r
-#if defined(SAFE_IO)\r
-\r
-#define word_in(x,c) bytes2word(((aes_08t*)(x)+4*c)[0], ((aes_08t*)(x)+4*c)[1], \\r
- ((aes_08t*)(x)+4*c)[2], ((aes_08t*)(x)+4*c)[3])\r
-#define word_out(x,c,v) { ((aes_08t*)(x)+4*c)[0] = bval(v,0); ((aes_08t*)(x)+4*c)[1] = bval(v,1); \\r
- ((aes_08t*)(x)+4*c)[2] = bval(v,2); ((aes_08t*)(x)+4*c)[3] = bval(v,3); }\r
-\r
-#elif (ALGORITHM_BYTE_ORDER == PLATFORM_BYTE_ORDER)\r
-\r
-#define word_in(x,c) (*((aes_32t*)(x)+(c)))\r
-#define word_out(x,c,v) (*((aes_32t*)(x)+(c)) = (v))\r
-\r
-#else\r
-\r
-#define word_in(x,c) aes_sw32(*((aes_32t*)(x)+(c)))\r
-#define word_out(x,c,v) (*((aes_32t*)(x)+(c)) = aes_sw32(v))\r
-\r
-#endif\r
-\r
-/* the finite field modular polynomial and elements */\r
-\r
-#define WPOLY 0x011b\r
-#define BPOLY 0x1b\r
-\r
-/* multiply four bytes in GF(2^8) by 'x' {02} in parallel */\r
-\r
-#define m1 0x80808080\r
-#define m2 0x7f7f7f7f\r
-#define gf_mulx(x) ((((x) & m2) << 1) ^ ((((x) & m1) >> 7) * BPOLY))\r
-\r
-/* The following defines provide alternative definitions of gf_mulx that might\r
- give improved performance if a fast 32-bit multiply is not available. Note\r
- that a temporary variable u needs to be defined where gf_mulx is used.\r
-\r
-#define gf_mulx(x) (u = (x) & m1, u |= (u >> 1), ((x) & m2) << 1) ^ ((u >> 3) | (u >> 6))\r
-#define m4 (0x01010101 * BPOLY)\r
-#define gf_mulx(x) (u = (x) & m1, ((x) & m2) << 1) ^ ((u - (u >> 7)) & m4)\r
-*/\r
-\r
-/* Work out which tables are needed for the different options */\r
-\r
-#if defined( AES_ASM )\r
-#if defined( ENC_ROUND )\r
-#undef ENC_ROUND\r
-#endif\r
-#define ENC_ROUND FOUR_TABLES\r
-#if defined( LAST_ENC_ROUND )\r
-#undef LAST_ENC_ROUND\r
-#endif\r
-#define LAST_ENC_ROUND FOUR_TABLES\r
-#if defined( DEC_ROUND )\r
-#undef DEC_ROUND\r
-#endif\r
-#define DEC_ROUND FOUR_TABLES\r
-#if defined( LAST_DEC_ROUND )\r
-#undef LAST_DEC_ROUND\r
-#endif\r
-#define LAST_DEC_ROUND FOUR_TABLES\r
-#if defined( KEY_SCHED )\r
-#undef KEY_SCHED\r
-#define KEY_SCHED FOUR_TABLES\r
-#endif\r
-#endif\r
-\r
-#if defined(ENCRYPTION) || defined(AES_ASM)\r
-#if ENC_ROUND == ONE_TABLE\r
-#define FT1_SET\r
-#elif ENC_ROUND == FOUR_TABLES\r
-#define FT4_SET\r
-#else\r
-#define SBX_SET\r
-#endif\r
-#if LAST_ENC_ROUND == ONE_TABLE\r
-#define FL1_SET\r
-#elif LAST_ENC_ROUND == FOUR_TABLES\r
-#define FL4_SET\r
-#elif !defined(SBX_SET)\r
-#define SBX_SET\r
-#endif\r
-#endif\r
-\r
-#if defined(DECRYPTION) || defined(AES_ASM)\r
-#if DEC_ROUND == ONE_TABLE\r
-#define IT1_SET\r
-#elif DEC_ROUND == FOUR_TABLES\r
-#define IT4_SET\r
-#else\r
-#define ISB_SET\r
-#endif\r
-#if LAST_DEC_ROUND == ONE_TABLE\r
-#define IL1_SET\r
-#elif LAST_DEC_ROUND == FOUR_TABLES\r
-#define IL4_SET\r
-#elif !defined(ISB_SET)\r
-#define ISB_SET\r
-#endif\r
-#endif\r
-\r
-#if defined(ENCRYPTION_KEY_SCHEDULE) || defined(DECRYPTION_KEY_SCHEDULE)\r
-#if KEY_SCHED == ONE_TABLE\r
-#define LS1_SET\r
-#define IM1_SET\r
-#elif KEY_SCHED == FOUR_TABLES\r
-#define LS4_SET\r
-#define IM4_SET\r
-#elif !defined(SBX_SET)\r
-#define SBX_SET\r
-#endif\r
-#endif\r
-\r
-/* generic definitions of Rijndael macros that use tables */\r
-\r
-#define no_table(x,box,vf,rf,c) bytes2word( \\r
- box[bval(vf(x,0,c),rf(0,c))], \\r
- box[bval(vf(x,1,c),rf(1,c))], \\r
- box[bval(vf(x,2,c),rf(2,c))], \\r
- box[bval(vf(x,3,c),rf(3,c))])\r
-\r
-#define one_table(x,op,tab,vf,rf,c) \\r
- ( tab[bval(vf(x,0,c),rf(0,c))] \\r
- ^ op(tab[bval(vf(x,1,c),rf(1,c))],1) \\r
- ^ op(tab[bval(vf(x,2,c),rf(2,c))],2) \\r
- ^ op(tab[bval(vf(x,3,c),rf(3,c))],3))\r
-\r
-#define four_tables(x,tab,vf,rf,c) \\r
- ( tab[0][bval(vf(x,0,c),rf(0,c))] \\r
- ^ tab[1][bval(vf(x,1,c),rf(1,c))] \\r
- ^ tab[2][bval(vf(x,2,c),rf(2,c))] \\r
- ^ tab[3][bval(vf(x,3,c),rf(3,c))])\r
-\r
-#define four_cached_tables(x,tab,vf,rf,c) \\r
-( tab##0[bval(vf(x,0,c),rf(0,c))] \\r
- ^ tab##1[bval(vf(x,1,c),rf(1,c))] \\r
- ^ tab##2[bval(vf(x,2,c),rf(2,c))] \\r
- ^ tab##3[bval(vf(x,3,c),rf(3,c))])\r
-\r
-#define vf1(x,r,c) (x)\r
-#define rf1(r,c) (r)\r
-#define rf2(r,c) ((8+r-c)&3)\r
-\r
-/* perform forward and inverse column mix operation on four bytes in long word x in */\r
-/* parallel. NOTE: x must be a simple variable, NOT an expression in these macros. */\r
-\r
-#if defined(FM4_SET) /* not currently used */\r
-#define fwd_mcol(x) four_tables(x,t_use(f,m),vf1,rf1,0)\r
-#elif defined(FM1_SET) /* not currently used */\r
-#define fwd_mcol(x) one_table(x,upr,t_use(f,m),vf1,rf1,0)\r
-#else\r
-#define dec_fmvars aes_32t g2\r
-#define fwd_mcol(x) (g2 = gf_mulx(x), g2 ^ upr((x) ^ g2, 3) ^ upr((x), 2) ^ upr((x), 1))\r
-#endif\r
-\r
-#if defined(IM4_SET)\r
-#define inv_mcol(x) four_tables(x,t_use(i,m),vf1,rf1,0)\r
-#elif defined(IM1_SET)\r
-#define inv_mcol(x) one_table(x,upr,t_use(i,m),vf1,rf1,0)\r
-#else\r
-#define dec_imvars aes_32t g2, g4, g9\r
-#define inv_mcol(x) (g2 = gf_mulx(x), g4 = gf_mulx(g2), g9 = (x) ^ gf_mulx(g4), g4 ^= g9, \\r
- (x) ^ g2 ^ g4 ^ upr(g2 ^ g9, 3) ^ upr(g4, 2) ^ upr(g9, 1))\r
-#endif\r
-\r
-#if defined(FL4_SET)\r
-#define ls_box(x,c) four_tables(x,t_use(f,l),vf1,rf2,c)\r
-#elif defined(LS4_SET)\r
-#define ls_box(x,c) four_tables(x,t_use(l,s),vf1,rf2,c)\r
-#elif defined(FL1_SET)\r
-#define ls_box(x,c) one_table(x,upr,t_use(f,l),vf1,rf2,c)\r
-#elif defined(LS1_SET)\r
-#define ls_box(x,c) one_table(x,upr,t_use(l,s),vf1,rf2,c)\r
-#else\r
-#define ls_box(x,c) no_table(x,t_use(s,box),vf1,rf2,c)\r
-#endif\r
-\r
-#endif\r
+/*
+ ---------------------------------------------------------------------------
+ Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved.
+
+ LICENSE TERMS
+
+ The free distribution and use of this software in both source and binary
+ form is allowed (with or without changes) provided that:
+
+ 1. distributions of this source code include the above copyright
+ notice, this list of conditions and the following disclaimer;
+
+ 2. distributions in binary form include the above copyright
+ notice, this list of conditions and the following disclaimer
+ in the documentation and/or other associated materials;
+
+ 3. the copyright holder's name is not used to endorse products
+ built using this software without specific written permission.
+
+ ALTERNATIVELY, provided that this notice is retained in full, this product
+ may be distributed under the terms of the GNU General Public License (GPL),
+ in which case the provisions of the GPL apply INSTEAD OF those given above.
+
+ DISCLAIMER
+
+ This software is provided 'as is' with no explicit or implied warranties
+ in respect of its properties, including, but not limited to, correctness
+ and/or fitness for purpose.
+ ---------------------------------------------------------------------------
+ Issue 28/01/2004
+
+ My thanks go to Dag Arne Osvik for devising the schemes used here for key
+ length derivation from the form of the key schedule
+
+ This file contains the compilation options for AES (Rijndael) and code
+ that is common across encryption, key scheduling and table generation.
+
+ OPERATION
+
+ These source code files implement the AES algorithm Rijndael designed by
+ Joan Daemen and Vincent Rijmen. This version is designed for the standard
+ block size of 16 bytes and for key sizes of 128, 192 and 256 bits (16, 24
+ and 32 bytes).
+
+ This version is designed for flexibility and speed using operations on
+ 32-bit words rather than operations on bytes. It can be compiled with
+ either big or little endian internal byte order but is faster when the
+ native byte order for the processor is used.
+
+ THE CIPHER INTERFACE
+
+ The cipher interface is implemented as an array of bytes in which lower
+ AES bit sequence indexes map to higher numeric significance within bytes.
+
+ aes_08t (an unsigned 8-bit type)
+ aes_32t (an unsigned 32-bit type)
+ struct aes_encrypt_ctx (structure for the cipher encryption context)
+ struct aes_decrypt_ctx (structure for the cipher decryption context)
+ aes_rval the function return type
+
+ C subroutine calls:
+
+ aes_rval aes_encrypt_key128(const unsigned char *key, aes_encrypt_ctx cx[1]);
+ aes_rval aes_encrypt_key192(const unsigned char *key, aes_encrypt_ctx cx[1]);
+ aes_rval aes_encrypt_key256(const unsigned char *key, aes_encrypt_ctx cx[1]);
+ aes_rval aes_encrypt(const unsigned char *in, unsigned char *out,
+ const aes_encrypt_ctx cx[1]);
+
+ aes_rval aes_decrypt_key128(const unsigned char *key, aes_decrypt_ctx cx[1]);
+ aes_rval aes_decrypt_key192(const unsigned char *key, aes_decrypt_ctx cx[1]);
+ aes_rval aes_decrypt_key256(const unsigned char *key, aes_decrypt_ctx cx[1]);
+ aes_rval aes_decrypt(const unsigned char *in, unsigned char *out,
+ const aes_decrypt_ctx cx[1]);
+
+ IMPORTANT NOTE: If you are using this C interface with dynamic tables make sure that
+ you call genTabs() before AES is used so that the tables are initialised.
+
+ C++ aes class subroutines:
+
+ Class AESencrypt for encryption
+
+ Construtors:
+ AESencrypt(void)
+ AESencrypt(const unsigned char *key) - 128 bit key
+ Members:
+ aes_rval key128(const unsigned char *key)
+ aes_rval key192(const unsigned char *key)
+ aes_rval key256(const unsigned char *key)
+ aes_rval encrypt(const unsigned char *in, unsigned char *out) const
+
+ Class AESdecrypt for encryption
+ Construtors:
+ AESdecrypt(void)
+ AESdecrypt(const unsigned char *key) - 128 bit key
+ Members:
+ aes_rval key128(const unsigned char *key)
+ aes_rval key192(const unsigned char *key)
+ aes_rval key256(const unsigned char *key)
+ aes_rval decrypt(const unsigned char *in, unsigned char *out) const
+
+ COMPILATION
+
+ The files used to provide AES (Rijndael) are
+
+ a. aes.h for the definitions needed for use in C.
+ b. aescpp.h for the definitions needed for use in C++.
+ c. aesopt.h for setting compilation options (also includes common code).
+ d. aescrypt.c for encryption and decrytpion, or
+ e. aeskey.c for key scheduling.
+ f. aestab.c for table loading or generation.
+ g. aescrypt.asm for encryption and decryption using assembler code.
+ h. aescrypt.mmx.asm for encryption and decryption using MMX assembler.
+
+ To compile AES (Rijndael) for use in C code use aes.h and set the
+ defines here for the facilities you need (key lengths, encryption
+ and/or decryption). Do not define AES_DLL or AES_CPP. Set the options
+ for optimisations and table sizes here.
+
+ To compile AES (Rijndael) for use in in C++ code use aescpp.h but do
+ not define AES_DLL
+
+ To compile AES (Rijndael) in C as a Dynamic Link Library DLL) use
+ aes.h and include the AES_DLL define.
+
+ CONFIGURATION OPTIONS (here and in aes.h)
+
+ a. set AES_DLL in aes.h if AES (Rijndael) is to be compiled as a DLL
+ b. You may need to set PLATFORM_BYTE_ORDER to define the byte order.
+ c. If you want the code to run in a specific internal byte order, then
+ ALGORITHM_BYTE_ORDER must be set accordingly.
+ d. set other configuration options decribed below.
+*/
+
+#if !defined( _AESOPT_H )
+#define _AESOPT_H
+
+#include "aes.h"
+
+/* CONFIGURATION - USE OF DEFINES
+
+ Later in this section there are a number of defines that control the
+ operation of the code. In each section, the purpose of each define is
+ explained so that the relevant form can be included or excluded by
+ setting either 1's or 0's respectively on the branches of the related
+ #if clauses.
+
+ PLATFORM SPECIFIC INCLUDES AND BYTE ORDER IN 32-BIT WORDS
+
+ To obtain the highest speed on processors with 32-bit words, this code
+ needs to determine the byte order of the target machine. The following
+ block of code is an attempt to capture the most obvious ways in which
+ various environemnts define byte order. It may well fail, in which case
+ the definitions will need to be set by editing at the points marked
+ **** EDIT HERE IF NECESSARY **** below. My thanks go to Peter Gutmann
+ for his assistance with this endian detection nightmare.
+*/
+
+#define BRG_LITTLE_ENDIAN 1234 /* byte 0 is least significant (i386) */
+#define BRG_BIG_ENDIAN 4321 /* byte 0 is most significant (mc68k) */
+
+#if defined(__GNUC__) || defined(__GNU_LIBRARY__)
+# if defined(__FreeBSD__) || defined(__OpenBSD__)
+# include <sys/endian.h>
+# elif defined( BSD ) && BSD >= 199103
+# include <machine/endian.h>
+# elif defined(__APPLE__)
+# if defined(__BIG_ENDIAN__) && !defined( BIG_ENDIAN )
+# define BIG_ENDIAN
+# elif defined(__LITTLE_ENDIAN__) && !defined( LITTLE_ENDIAN )
+# define LITTLE_ENDIAN
+# endif
+# else
+# include <endian.h>
+# if defined(__BEOS__)
+# include <byteswap.h>
+# endif
+# endif
+#endif
+
+#if !defined(PLATFORM_BYTE_ORDER)
+# if defined(LITTLE_ENDIAN) || defined(BIG_ENDIAN)
+# if defined(LITTLE_ENDIAN) && !defined(BIG_ENDIAN)
+# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN
+# elif !defined(LITTLE_ENDIAN) && defined(BIG_ENDIAN)
+# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN
+# elif defined(BYTE_ORDER) && (BYTE_ORDER == LITTLE_ENDIAN)
+# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN
+# elif defined(BYTE_ORDER) && (BYTE_ORDER == BIG_ENDIAN)
+# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN
+# endif
+# elif defined(_LITTLE_ENDIAN) || defined(_BIG_ENDIAN)
+# if defined(_LITTLE_ENDIAN) && !defined(_BIG_ENDIAN)
+# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN
+# elif !defined(_LITTLE_ENDIAN) && defined(_BIG_ENDIAN)
+# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN
+# elif defined(_BYTE_ORDER) && (_BYTE_ORDER == _LITTLE_ENDIAN)
+# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN
+# elif defined(_BYTE_ORDER) && (_BYTE_ORDER == _BIG_ENDIAN)
+# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN
+# endif
+# elif defined(__LITTLE_ENDIAN__) || defined(__BIG_ENDIAN__)
+# if defined(__LITTLE_ENDIAN__) && !defined(__BIG_ENDIAN__)
+# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN
+# elif !defined(__LITTLE_ENDIAN__) && defined(__BIG_ENDIAN__)
+# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN
+# elif defined(__BYTE_ORDER__) && (__BYTE_ORDER__ == __LITTLE_ENDIAN__)
+# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN
+# elif defined(__BYTE_ORDER__) && (__BYTE_ORDER__ == __BIG_ENDIAN__)
+# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN
+# endif
+# endif
+#endif
+
+/* if the platform is still unknown, try to find its byte order */
+/* from commonly used machine defines */
+
+#if !defined(PLATFORM_BYTE_ORDER)
+
+#if defined( __alpha__ ) || defined( __alpha ) || defined( i386 ) || \
+ defined( __i386__ ) || defined( _M_I86 ) || defined( _M_IX86 ) || \
+ defined( __OS2__ ) || defined( sun386 ) || defined( __TURBOC__ ) || \
+ defined( vax ) || defined( vms ) || defined( VMS ) || \
+ defined( __VMS )
+# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN
+
+#elif defined( AMIGA ) || defined( applec ) || defined( __AS400__ ) || \
+ defined( _CRAY ) || defined( __hppa ) || defined( __hp9000 ) || \
+ defined( ibm370 ) || defined( mc68000 ) || defined( m68k ) || \
+ defined( __MRC__ ) || defined( __MVS__ ) || defined( __MWERKS__ ) || \
+ defined( sparc ) || defined( __sparc) || defined( SYMANTEC_C ) || \
+ defined( __TANDEM ) || defined( THINK_C ) || defined( __VMCMS__ )
+# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN
+
+#elif 0 /* **** EDIT HERE IF NECESSARY **** */
+# define PLATFORM_BYTE_ORDER BRG_LITTLE_ENDIAN
+#elif 0 /* **** EDIT HERE IF NECESSARY **** */
+# define PLATFORM_BYTE_ORDER BRG_BIG_ENDIAN
+#else
+# error Please edit aesopt.h (line 234 or 236) to set the platform byte order
+#endif
+
+#endif
+
+/* SOME LOCAL DEFINITIONS */
+
+#define NO_TABLES 0
+#define ONE_TABLE 1
+#define FOUR_TABLES 4
+#define NONE 0
+#define PARTIAL 1
+#define FULL 2
+
+#if defined(bswap32)
+#define aes_sw32 bswap32
+#elif defined(bswap_32)
+#define aes_sw32 bswap_32
+#else
+#define brot(x,n) (((aes_32t)(x) << n) | ((aes_32t)(x) >> (32 - n)))
+#define aes_sw32(x) ((brot((x),8) & 0x00ff00ff) | (brot((x),24) & 0xff00ff00))
+#endif
+
+/* 1. FUNCTIONS REQUIRED
+
+ This implementation provides subroutines for encryption, decryption
+ and for setting the three key lengths (separately) for encryption
+ and decryption. When the assembler code is not being used the following
+ definition blocks allow the selection of the routines that are to be
+ included in the compilation.
+*/
+#if defined( AES_ENCRYPT )
+#define ENCRYPTION
+#define ENCRYPTION_KEY_SCHEDULE
+#endif
+
+#if defined( AES_DECRYPT )
+#define DECRYPTION
+#define DECRYPTION_KEY_SCHEDULE
+#endif
+
+/* 2. ASSEMBLER SUPPORT
+
+ This define (which can be on the command line) enables the use of the
+ assembler code routines for encryption and decryption with the C code
+ only providing key scheduling
+*/
+#if 0 && !defined(AES_ASM)
+#define AES_ASM
+#endif
+
+/* 3. BYTE ORDER WITHIN 32 BIT WORDS
+
+ The fundamental data processing units in Rijndael are 8-bit bytes. The
+ input, output and key input are all enumerated arrays of bytes in which
+ bytes are numbered starting at zero and increasing to one less than the
+ number of bytes in the array in question. This enumeration is only used
+ for naming bytes and does not imply any adjacency or order relationship
+ from one byte to another. When these inputs and outputs are considered
+ as bit sequences, bits 8*n to 8*n+7 of the bit sequence are mapped to
+ byte[n] with bit 8n+i in the sequence mapped to bit 7-i within the byte.
+ In this implementation bits are numbered from 0 to 7 starting at the
+ numerically least significant end of each byte (bit n represents 2^n).
+
+ However, Rijndael can be implemented more efficiently using 32-bit
+ words by packing bytes into words so that bytes 4*n to 4*n+3 are placed
+ into word[n]. While in principle these bytes can be assembled into words
+ in any positions, this implementation only supports the two formats in
+ which bytes in adjacent positions within words also have adjacent byte
+ numbers. This order is called big-endian if the lowest numbered bytes
+ in words have the highest numeric significance and little-endian if the
+ opposite applies.
+
+ This code can work in either order irrespective of the order used by the
+ machine on which it runs. Normally the internal byte order will be set
+ to the order of the processor on which the code is to be run but this
+ define can be used to reverse this in special situations
+
+ NOTE: Assembler code versions rely on PLATFORM_BYTE_ORDER being set
+*/
+#if 1 || defined(AES_ASM)
+#define ALGORITHM_BYTE_ORDER PLATFORM_BYTE_ORDER
+#elif 0
+#define ALGORITHM_BYTE_ORDER BRG_LITTLE_ENDIAN
+#elif 0
+#define ALGORITHM_BYTE_ORDER BRG_BIG_ENDIAN
+#else
+#error The algorithm byte order is not defined
+#endif
+
+/* 4. FAST INPUT/OUTPUT OPERATIONS.
+
+ On some machines it is possible to improve speed by transferring the
+ bytes in the input and output arrays to and from the internal 32-bit
+ variables by addressing these arrays as if they are arrays of 32-bit
+ words. On some machines this will always be possible but there may
+ be a large performance penalty if the byte arrays are not aligned on
+ the normal word boundaries. On other machines this technique will
+ lead to memory access errors when such 32-bit word accesses are not
+ properly aligned. The option SAFE_IO avoids such problems but will
+ often be slower on those machines that support misaligned access
+ (especially so if care is taken to align the input and output byte
+ arrays on 32-bit word boundaries). If SAFE_IO is not defined it is
+ assumed that access to byte arrays as if they are arrays of 32-bit
+ words will not cause problems when such accesses are misaligned.
+*/
+#if 0 && !defined(_MSC_VER)
+#define SAFE_IO
+#endif
+
+/* 5. LOOP UNROLLING
+
+ The code for encryption and decrytpion cycles through a number of rounds
+ that can be implemented either in a loop or by expanding the code into a
+ long sequence of instructions, the latter producing a larger program but
+ one that will often be much faster. The latter is called loop unrolling.
+ There are also potential speed advantages in expanding two iterations in
+ a loop with half the number of iterations, which is called partial loop
+ unrolling. The following options allow partial or full loop unrolling
+ to be set independently for encryption and decryption
+*/
+#if 1
+#define ENC_UNROLL FULL
+#elif 0
+#define ENC_UNROLL PARTIAL
+#else
+#define ENC_UNROLL NONE
+#endif
+
+#if 1
+#define DEC_UNROLL FULL
+#elif 0
+#define DEC_UNROLL PARTIAL
+#else
+#define DEC_UNROLL NONE
+#endif
+
+/* 6. FAST FINITE FIELD OPERATIONS
+
+ If this section is included, tables are used to provide faster finite
+ field arithmetic (this has no effect if FIXED_TABLES is defined).
+*/
+#if 1
+#define FF_TABLES
+#endif
+
+/* 7. INTERNAL STATE VARIABLE FORMAT
+
+ The internal state of Rijndael is stored in a number of local 32-bit
+ word varaibles which can be defined either as an array or as individual
+ names variables. Include this section if you want to store these local
+ varaibles in arrays. Otherwise individual local variables will be used.
+*/
+#if 0
+#define ARRAYS
+#endif
+
+/* In this implementation the columns of the state array are each held in
+ 32-bit words. The state array can be held in various ways: in an array
+ of words, in a number of individual word variables or in a number of
+ processor registers. The following define maps a variable name x and
+ a column number c to the way the state array variable is to be held.
+ The first define below maps the state into an array x[c] whereas the
+ second form maps the state into a number of individual variables x0,
+ x1, etc. Another form could map individual state colums to machine
+ register names.
+*/
+
+#if defined(ARRAYS)
+#define s(x,c) x[c]
+#else
+#define s(x,c) x##c
+#endif
+
+/* 8. FIXED OR DYNAMIC TABLES
+
+ When this section is included the tables used by the code are compiled
+ statically into the binary file. Otherwise the subroutine gen_tabs()
+ must be called to compute them before the code is first used.
+*/
+#if 1
+#define FIXED_TABLES
+#endif
+
+/* 9. TABLE ALIGNMENT
+
+ On some sytsems speed will be improved by aligning the AES large lookup
+ tables on particular boundaries. This define should be set to a power of
+ two giving the desired alignment. It can be left undefined if alignment
+ is not needed. This option is specific to the Microsft VC++ compiler -
+ it seems to sometimes cause trouble for the VC++ version 6 compiler.
+*/
+
+#if 0 && defined(_MSC_VER) && (_MSC_VER >= 1300)
+#define TABLE_ALIGN 64
+#endif
+
+/* 10. INTERNAL TABLE CONFIGURATION
+
+ This cipher proceeds by repeating in a number of cycles known as 'rounds'
+ which are implemented by a round function which can optionally be speeded
+ up using tables. The basic tables are each 256 32-bit words, with either
+ one or four tables being required for each round function depending on
+ how much speed is required. The encryption and decryption round functions
+ are different and the last encryption and decrytpion round functions are
+ different again making four different round functions in all.
+
+ This means that:
+ 1. Normal encryption and decryption rounds can each use either 0, 1
+ or 4 tables and table spaces of 0, 1024 or 4096 bytes each.
+ 2. The last encryption and decryption rounds can also use either 0, 1
+ or 4 tables and table spaces of 0, 1024 or 4096 bytes each.
+
+ Include or exclude the appropriate definitions below to set the number
+ of tables used by this implementation.
+*/
+
+#if 1 /* set tables for the normal encryption round */
+#define ENC_ROUND FOUR_TABLES
+#elif 0
+#define ENC_ROUND ONE_TABLE
+#else
+#define ENC_ROUND NO_TABLES
+#endif
+
+#if 1 /* set tables for the last encryption round */
+#define LAST_ENC_ROUND FOUR_TABLES
+#elif 0
+#define LAST_ENC_ROUND ONE_TABLE
+#else
+#define LAST_ENC_ROUND NO_TABLES
+#endif
+
+#if 1 /* set tables for the normal decryption round */
+#define DEC_ROUND FOUR_TABLES
+#elif 0
+#define DEC_ROUND ONE_TABLE
+#else
+#define DEC_ROUND NO_TABLES
+#endif
+
+#if 1 /* set tables for the last decryption round */
+#define LAST_DEC_ROUND FOUR_TABLES
+#elif 0
+#define LAST_DEC_ROUND ONE_TABLE
+#else
+#define LAST_DEC_ROUND NO_TABLES
+#endif
+
+/* The decryption key schedule can be speeded up with tables in the same
+ way that the round functions can. Include or exclude the following
+ defines to set this requirement.
+*/
+#if 1
+#define KEY_SCHED FOUR_TABLES
+#elif 0
+#define KEY_SCHED ONE_TABLE
+#else
+#define KEY_SCHED NO_TABLES
+#endif
+
+/* 11. TABLE POINTER CACHING
+
+ Normally tables are referenced directly, Enable this option if you wish to
+ cache pointers to the tables in the encrypt/decrypt code. Note that this
+ only works if you are using FOUR_TABLES for the ROUND you enable this for.
+*/
+#if 1
+#define ENC_ROUND_CACHE_TABLES
+#endif
+#if 1
+#define LAST_ENC_ROUND_CACHE_TABLES
+#endif
+#if 1
+#define DEC_ROUND_CACHE_TABLES
+#endif
+#if 1
+#define LAST_DEC_ROUND_CACHE_TABLES
+#endif
+
+
+/* END OF CONFIGURATION OPTIONS */
+
+#define RC_LENGTH (5 * (AES_BLOCK_SIZE / 4 - 2))
+
+/* Disable or report errors on some combinations of options */
+
+#if ENC_ROUND == NO_TABLES && LAST_ENC_ROUND != NO_TABLES
+#undef LAST_ENC_ROUND
+#define LAST_ENC_ROUND NO_TABLES
+#elif ENC_ROUND == ONE_TABLE && LAST_ENC_ROUND == FOUR_TABLES
+#undef LAST_ENC_ROUND
+#define LAST_ENC_ROUND ONE_TABLE
+#endif
+
+#if ENC_ROUND == NO_TABLES && ENC_UNROLL != NONE
+#undef ENC_UNROLL
+#define ENC_UNROLL NONE
+#endif
+
+#if DEC_ROUND == NO_TABLES && LAST_DEC_ROUND != NO_TABLES
+#undef LAST_DEC_ROUND
+#define LAST_DEC_ROUND NO_TABLES
+#elif DEC_ROUND == ONE_TABLE && LAST_DEC_ROUND == FOUR_TABLES
+#undef LAST_DEC_ROUND
+#define LAST_DEC_ROUND ONE_TABLE
+#endif
+
+#if DEC_ROUND == NO_TABLES && DEC_UNROLL != NONE
+#undef DEC_UNROLL
+#define DEC_UNROLL NONE
+#endif
+
+/* upr(x,n): rotates bytes within words by n positions, moving bytes to
+ higher index positions with wrap around into low positions
+ ups(x,n): moves bytes by n positions to higher index positions in
+ words but without wrap around
+ bval(x,n): extracts a byte from a word
+
+ NOTE: The definitions given here are intended only for use with
+ unsigned variables and with shift counts that are compile
+ time constants
+*/
+
+#if (ALGORITHM_BYTE_ORDER == BRG_LITTLE_ENDIAN)
+#define upr(x,n) (((aes_32t)(x) << (8 * (n))) | ((aes_32t)(x) >> (32 - 8 * (n))))
+#define ups(x,n) ((aes_32t) (x) << (8 * (n)))
+#define bval(x,n) ((aes_08t)((x) >> (8 * (n))))
+#define bytes2word(b0, b1, b2, b3) \
+ (((aes_32t)(b3) << 24) | ((aes_32t)(b2) << 16) | ((aes_32t)(b1) << 8) | (b0))
+#endif
+
+#if (ALGORITHM_BYTE_ORDER == BRG_BIG_ENDIAN)
+#define upr(x,n) (((aes_32t)(x) >> (8 * (n))) | ((aes_32t)(x) << (32 - 8 * (n))))
+#define ups(x,n) ((aes_32t) (x) >> (8 * (n))))
+#define bval(x,n) ((aes_08t)((x) >> (24 - 8 * (n))))
+#define bytes2word(b0, b1, b2, b3) \
+ (((aes_32t)(b0) << 24) | ((aes_32t)(b1) << 16) | ((aes_32t)(b2) << 8) | (b3))
+#endif
+
+#if defined(SAFE_IO)
+
+#define word_in(x,c) bytes2word(((aes_08t*)(x)+4*c)[0], ((aes_08t*)(x)+4*c)[1], \
+ ((aes_08t*)(x)+4*c)[2], ((aes_08t*)(x)+4*c)[3])
+#define word_out(x,c,v) { ((aes_08t*)(x)+4*c)[0] = bval(v,0); ((aes_08t*)(x)+4*c)[1] = bval(v,1); \
+ ((aes_08t*)(x)+4*c)[2] = bval(v,2); ((aes_08t*)(x)+4*c)[3] = bval(v,3); }
+
+#elif (ALGORITHM_BYTE_ORDER == PLATFORM_BYTE_ORDER)
+
+#define word_in(x,c) (*((aes_32t*)(x)+(c)))
+#define word_out(x,c,v) (*((aes_32t*)(x)+(c)) = (v))
+
+#else
+
+#define word_in(x,c) aes_sw32(*((aes_32t*)(x)+(c)))
+#define word_out(x,c,v) (*((aes_32t*)(x)+(c)) = aes_sw32(v))
+
+#endif
+
+/* the finite field modular polynomial and elements */
+
+#define WPOLY 0x011b
+#define BPOLY 0x1b
+
+/* multiply four bytes in GF(2^8) by 'x' {02} in parallel */
+
+#define m1 0x80808080
+#define m2 0x7f7f7f7f
+#define gf_mulx(x) ((((x) & m2) << 1) ^ ((((x) & m1) >> 7) * BPOLY))
+
+/* The following defines provide alternative definitions of gf_mulx that might
+ give improved performance if a fast 32-bit multiply is not available. Note
+ that a temporary variable u needs to be defined where gf_mulx is used.
+
+#define gf_mulx(x) (u = (x) & m1, u |= (u >> 1), ((x) & m2) << 1) ^ ((u >> 3) | (u >> 6))
+#define m4 (0x01010101 * BPOLY)
+#define gf_mulx(x) (u = (x) & m1, ((x) & m2) << 1) ^ ((u - (u >> 7)) & m4)
+*/
+
+/* Work out which tables are needed for the different options */
+
+#if defined( AES_ASM )
+#if defined( ENC_ROUND )
+#undef ENC_ROUND
+#endif
+#define ENC_ROUND FOUR_TABLES
+#if defined( LAST_ENC_ROUND )
+#undef LAST_ENC_ROUND
+#endif
+#define LAST_ENC_ROUND FOUR_TABLES
+#if defined( DEC_ROUND )
+#undef DEC_ROUND
+#endif
+#define DEC_ROUND FOUR_TABLES
+#if defined( LAST_DEC_ROUND )
+#undef LAST_DEC_ROUND
+#endif
+#define LAST_DEC_ROUND FOUR_TABLES
+#if defined( KEY_SCHED )
+#undef KEY_SCHED
+#define KEY_SCHED FOUR_TABLES
+#endif
+#endif
+
+#if defined(ENCRYPTION) || defined(AES_ASM)
+#if ENC_ROUND == ONE_TABLE
+#define FT1_SET
+#elif ENC_ROUND == FOUR_TABLES
+#define FT4_SET
+#else
+#define SBX_SET
+#endif
+#if LAST_ENC_ROUND == ONE_TABLE
+#define FL1_SET
+#elif LAST_ENC_ROUND == FOUR_TABLES
+#define FL4_SET
+#elif !defined(SBX_SET)
+#define SBX_SET
+#endif
+#endif
+
+#if defined(DECRYPTION) || defined(AES_ASM)
+#if DEC_ROUND == ONE_TABLE
+#define IT1_SET
+#elif DEC_ROUND == FOUR_TABLES
+#define IT4_SET
+#else
+#define ISB_SET
+#endif
+#if LAST_DEC_ROUND == ONE_TABLE
+#define IL1_SET
+#elif LAST_DEC_ROUND == FOUR_TABLES
+#define IL4_SET
+#elif !defined(ISB_SET)
+#define ISB_SET
+#endif
+#endif
+
+#if defined(ENCRYPTION_KEY_SCHEDULE) || defined(DECRYPTION_KEY_SCHEDULE)
+#if KEY_SCHED == ONE_TABLE
+#define LS1_SET
+#define IM1_SET
+#elif KEY_SCHED == FOUR_TABLES
+#define LS4_SET
+#define IM4_SET
+#elif !defined(SBX_SET)
+#define SBX_SET
+#endif
+#endif
+
+/* generic definitions of Rijndael macros that use tables */
+
+#define no_table(x,box,vf,rf,c) bytes2word( \
+ box[bval(vf(x,0,c),rf(0,c))], \
+ box[bval(vf(x,1,c),rf(1,c))], \
+ box[bval(vf(x,2,c),rf(2,c))], \
+ box[bval(vf(x,3,c),rf(3,c))])
+
+#define one_table(x,op,tab,vf,rf,c) \
+ ( tab[bval(vf(x,0,c),rf(0,c))] \
+ ^ op(tab[bval(vf(x,1,c),rf(1,c))],1) \
+ ^ op(tab[bval(vf(x,2,c),rf(2,c))],2) \
+ ^ op(tab[bval(vf(x,3,c),rf(3,c))],3))
+
+#define four_tables(x,tab,vf,rf,c) \
+ ( tab[0][bval(vf(x,0,c),rf(0,c))] \
+ ^ tab[1][bval(vf(x,1,c),rf(1,c))] \
+ ^ tab[2][bval(vf(x,2,c),rf(2,c))] \
+ ^ tab[3][bval(vf(x,3,c),rf(3,c))])
+
+#define four_cached_tables(x,tab,vf,rf,c) \
+( tab##0[bval(vf(x,0,c),rf(0,c))] \
+ ^ tab##1[bval(vf(x,1,c),rf(1,c))] \
+ ^ tab##2[bval(vf(x,2,c),rf(2,c))] \
+ ^ tab##3[bval(vf(x,3,c),rf(3,c))])
+
+#define vf1(x,r,c) (x)
+#define rf1(r,c) (r)
+#define rf2(r,c) ((8+r-c)&3)
+
+/* perform forward and inverse column mix operation on four bytes in long word x in */
+/* parallel. NOTE: x must be a simple variable, NOT an expression in these macros. */
+
+#if defined(FM4_SET) /* not currently used */
+#define fwd_mcol(x) four_tables(x,t_use(f,m),vf1,rf1,0)
+#elif defined(FM1_SET) /* not currently used */
+#define fwd_mcol(x) one_table(x,upr,t_use(f,m),vf1,rf1,0)
+#else
+#define dec_fmvars aes_32t g2
+#define fwd_mcol(x) (g2 = gf_mulx(x), g2 ^ upr((x) ^ g2, 3) ^ upr((x), 2) ^ upr((x), 1))
+#endif
+
+#if defined(IM4_SET)
+#define inv_mcol(x) four_tables(x,t_use(i,m),vf1,rf1,0)
+#elif defined(IM1_SET)
+#define inv_mcol(x) one_table(x,upr,t_use(i,m),vf1,rf1,0)
+#else
+#define dec_imvars aes_32t g2, g4, g9
+#define inv_mcol(x) (g2 = gf_mulx(x), g4 = gf_mulx(g2), g9 = (x) ^ gf_mulx(g4), g4 ^= g9, \
+ (x) ^ g2 ^ g4 ^ upr(g2 ^ g9, 3) ^ upr(g4, 2) ^ upr(g9, 1))
+#endif
+
+#if defined(FL4_SET)
+#define ls_box(x,c) four_tables(x,t_use(f,l),vf1,rf2,c)
+#elif defined(LS4_SET)
+#define ls_box(x,c) four_tables(x,t_use(l,s),vf1,rf2,c)
+#elif defined(FL1_SET)
+#define ls_box(x,c) one_table(x,upr,t_use(f,l),vf1,rf2,c)
+#elif defined(LS1_SET)
+#define ls_box(x,c) one_table(x,upr,t_use(l,s),vf1,rf2,c)
+#else
+#define ls_box(x,c) no_table(x,t_use(s,box),vf1,rf2,c)
+#endif
+
+#endif
-/*\r
- ---------------------------------------------------------------------------\r
- Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved.\r
-\r
- LICENSE TERMS\r
-\r
- The free distribution and use of this software in both source and binary\r
- form is allowed (with or without changes) provided that:\r
-\r
- 1. distributions of this source code include the above copyright\r
- notice, this list of conditions and the following disclaimer;\r
-\r
- 2. distributions in binary form include the above copyright\r
- notice, this list of conditions and the following disclaimer\r
- in the documentation and/or other associated materials;\r
-\r
- 3. the copyright holder's name is not used to endorse products\r
- built using this software without specific written permission.\r
-\r
- ALTERNATIVELY, provided that this notice is retained in full, this product\r
- may be distributed under the terms of the GNU General Public License (GPL),\r
- in which case the provisions of the GPL apply INSTEAD OF those given above.\r
-\r
- DISCLAIMER\r
-\r
- This software is provided 'as is' with no explicit or implied warranties\r
- in respect of its properties, including, but not limited to, correctness\r
- and/or fitness for purpose.\r
- ---------------------------------------------------------------------------\r
- Issue 28/01/2004\r
-\r
-*/\r
-\r
-#if defined(__cplusplus)\r
-extern "C"\r
-{\r
-#endif\r
-\r
-#define DO_TABLES\r
-\r
-#include "aesopt.h"\r
-\r
-#if defined(FIXED_TABLES)\r
-\r
-#define sb_data(w) {\\r
- w(0x63), w(0x7c), w(0x77), w(0x7b), w(0xf2), w(0x6b), w(0x6f), w(0xc5),\\r
- w(0x30), w(0x01), w(0x67), w(0x2b), w(0xfe), w(0xd7), w(0xab), w(0x76),\\r
- w(0xca), w(0x82), w(0xc9), w(0x7d), w(0xfa), w(0x59), w(0x47), w(0xf0),\\r
- w(0xad), w(0xd4), w(0xa2), w(0xaf), w(0x9c), w(0xa4), w(0x72), w(0xc0),\\r
- w(0xb7), w(0xfd), w(0x93), w(0x26), w(0x36), w(0x3f), w(0xf7), w(0xcc),\\r
- w(0x34), w(0xa5), w(0xe5), w(0xf1), w(0x71), w(0xd8), w(0x31), w(0x15),\\r
- w(0x04), w(0xc7), w(0x23), w(0xc3), w(0x18), w(0x96), w(0x05), w(0x9a),\\r
- w(0x07), w(0x12), w(0x80), w(0xe2), w(0xeb), w(0x27), w(0xb2), w(0x75),\\r
- w(0x09), w(0x83), w(0x2c), w(0x1a), w(0x1b), w(0x6e), w(0x5a), w(0xa0),\\r
- w(0x52), w(0x3b), w(0xd6), w(0xb3), w(0x29), w(0xe3), w(0x2f), w(0x84),\\r
- w(0x53), w(0xd1), w(0x00), w(0xed), w(0x20), w(0xfc), w(0xb1), w(0x5b),\\r
- w(0x6a), w(0xcb), w(0xbe), w(0x39), w(0x4a), w(0x4c), w(0x58), w(0xcf),\\r
- w(0xd0), w(0xef), w(0xaa), w(0xfb), w(0x43), w(0x4d), w(0x33), w(0x85),\\r
- w(0x45), w(0xf9), w(0x02), w(0x7f), w(0x50), w(0x3c), w(0x9f), w(0xa8),\\r
- w(0x51), w(0xa3), w(0x40), w(0x8f), w(0x92), w(0x9d), w(0x38), w(0xf5),\\r
- w(0xbc), w(0xb6), w(0xda), w(0x21), w(0x10), w(0xff), w(0xf3), w(0xd2),\\r
- w(0xcd), w(0x0c), w(0x13), w(0xec), w(0x5f), w(0x97), w(0x44), w(0x17),\\r
- w(0xc4), w(0xa7), w(0x7e), w(0x3d), w(0x64), w(0x5d), w(0x19), w(0x73),\\r
- w(0x60), w(0x81), w(0x4f), w(0xdc), w(0x22), w(0x2a), w(0x90), w(0x88),\\r
- w(0x46), w(0xee), w(0xb8), w(0x14), w(0xde), w(0x5e), w(0x0b), w(0xdb),\\r
- w(0xe0), w(0x32), w(0x3a), w(0x0a), w(0x49), w(0x06), w(0x24), w(0x5c),\\r
- w(0xc2), w(0xd3), w(0xac), w(0x62), w(0x91), w(0x95), w(0xe4), w(0x79),\\r
- w(0xe7), w(0xc8), w(0x37), w(0x6d), w(0x8d), w(0xd5), w(0x4e), w(0xa9),\\r
- w(0x6c), w(0x56), w(0xf4), w(0xea), w(0x65), w(0x7a), w(0xae), w(0x08),\\r
- w(0xba), w(0x78), w(0x25), w(0x2e), w(0x1c), w(0xa6), w(0xb4), w(0xc6),\\r
- w(0xe8), w(0xdd), w(0x74), w(0x1f), w(0x4b), w(0xbd), w(0x8b), w(0x8a),\\r
- w(0x70), w(0x3e), w(0xb5), w(0x66), w(0x48), w(0x03), w(0xf6), w(0x0e),\\r
- w(0x61), w(0x35), w(0x57), w(0xb9), w(0x86), w(0xc1), w(0x1d), w(0x9e),\\r
- w(0xe1), w(0xf8), w(0x98), w(0x11), w(0x69), w(0xd9), w(0x8e), w(0x94),\\r
- w(0x9b), w(0x1e), w(0x87), w(0xe9), w(0xce), w(0x55), w(0x28), w(0xdf),\\r
- w(0x8c), w(0xa1), w(0x89), w(0x0d), w(0xbf), w(0xe6), w(0x42), w(0x68),\\r
- w(0x41), w(0x99), w(0x2d), w(0x0f), w(0xb0), w(0x54), w(0xbb), w(0x16) }\r
-\r
-#define isb_data(w) {\\r
- w(0x52), w(0x09), w(0x6a), w(0xd5), w(0x30), w(0x36), w(0xa5), w(0x38),\\r
- w(0xbf), w(0x40), w(0xa3), w(0x9e), w(0x81), w(0xf3), w(0xd7), w(0xfb),\\r
- w(0x7c), w(0xe3), w(0x39), w(0x82), w(0x9b), w(0x2f), w(0xff), w(0x87),\\r
- w(0x34), w(0x8e), w(0x43), w(0x44), w(0xc4), w(0xde), w(0xe9), w(0xcb),\\r
- w(0x54), w(0x7b), w(0x94), w(0x32), w(0xa6), w(0xc2), w(0x23), w(0x3d),\\r
- w(0xee), w(0x4c), w(0x95), w(0x0b), w(0x42), w(0xfa), w(0xc3), w(0x4e),\\r
- w(0x08), w(0x2e), w(0xa1), w(0x66), w(0x28), w(0xd9), w(0x24), w(0xb2),\\r
- w(0x76), w(0x5b), w(0xa2), w(0x49), w(0x6d), w(0x8b), w(0xd1), w(0x25),\\r
- w(0x72), w(0xf8), w(0xf6), w(0x64), w(0x86), w(0x68), w(0x98), w(0x16),\\r
- w(0xd4), w(0xa4), w(0x5c), w(0xcc), w(0x5d), w(0x65), w(0xb6), w(0x92),\\r
- w(0x6c), w(0x70), w(0x48), w(0x50), w(0xfd), w(0xed), w(0xb9), w(0xda),\\r
- w(0x5e), w(0x15), w(0x46), w(0x57), w(0xa7), w(0x8d), w(0x9d), w(0x84),\\r
- w(0x90), w(0xd8), w(0xab), w(0x00), w(0x8c), w(0xbc), w(0xd3), w(0x0a),\\r
- w(0xf7), w(0xe4), w(0x58), w(0x05), w(0xb8), w(0xb3), w(0x45), w(0x06),\\r
- w(0xd0), w(0x2c), w(0x1e), w(0x8f), w(0xca), w(0x3f), w(0x0f), w(0x02),\\r
- w(0xc1), w(0xaf), w(0xbd), w(0x03), w(0x01), w(0x13), w(0x8a), w(0x6b),\\r
- w(0x3a), w(0x91), w(0x11), w(0x41), w(0x4f), w(0x67), w(0xdc), w(0xea),\\r
- w(0x97), w(0xf2), w(0xcf), w(0xce), w(0xf0), w(0xb4), w(0xe6), w(0x73),\\r
- w(0x96), w(0xac), w(0x74), w(0x22), w(0xe7), w(0xad), w(0x35), w(0x85),\\r
- w(0xe2), w(0xf9), w(0x37), w(0xe8), w(0x1c), w(0x75), w(0xdf), w(0x6e),\\r
- w(0x47), w(0xf1), w(0x1a), w(0x71), w(0x1d), w(0x29), w(0xc5), w(0x89),\\r
- w(0x6f), w(0xb7), w(0x62), w(0x0e), w(0xaa), w(0x18), w(0xbe), w(0x1b),\\r
- w(0xfc), w(0x56), w(0x3e), w(0x4b), w(0xc6), w(0xd2), w(0x79), w(0x20),\\r
- w(0x9a), w(0xdb), w(0xc0), w(0xfe), w(0x78), w(0xcd), w(0x5a), w(0xf4),\\r
- w(0x1f), w(0xdd), w(0xa8), w(0x33), w(0x88), w(0x07), w(0xc7), w(0x31),\\r
- w(0xb1), w(0x12), w(0x10), w(0x59), w(0x27), w(0x80), w(0xec), w(0x5f),\\r
- w(0x60), w(0x51), w(0x7f), w(0xa9), w(0x19), w(0xb5), w(0x4a), w(0x0d),\\r
- w(0x2d), w(0xe5), w(0x7a), w(0x9f), w(0x93), w(0xc9), w(0x9c), w(0xef),\\r
- w(0xa0), w(0xe0), w(0x3b), w(0x4d), w(0xae), w(0x2a), w(0xf5), w(0xb0),\\r
- w(0xc8), w(0xeb), w(0xbb), w(0x3c), w(0x83), w(0x53), w(0x99), w(0x61),\\r
- w(0x17), w(0x2b), w(0x04), w(0x7e), w(0xba), w(0x77), w(0xd6), w(0x26),\\r
- w(0xe1), w(0x69), w(0x14), w(0x63), w(0x55), w(0x21), w(0x0c), w(0x7d) }\r
-\r
-#define mm_data(w) {\\r
- w(0x00), w(0x01), w(0x02), w(0x03), w(0x04), w(0x05), w(0x06), w(0x07),\\r
- w(0x08), w(0x09), w(0x0a), w(0x0b), w(0x0c), w(0x0d), w(0x0e), w(0x0f),\\r
- w(0x10), w(0x11), w(0x12), w(0x13), w(0x14), w(0x15), w(0x16), w(0x17),\\r
- w(0x18), w(0x19), w(0x1a), w(0x1b), w(0x1c), w(0x1d), w(0x1e), w(0x1f),\\r
- w(0x20), w(0x21), w(0x22), w(0x23), w(0x24), w(0x25), w(0x26), w(0x27),\\r
- w(0x28), w(0x29), w(0x2a), w(0x2b), w(0x2c), w(0x2d), w(0x2e), w(0x2f),\\r
- w(0x30), w(0x31), w(0x32), w(0x33), w(0x34), w(0x35), w(0x36), w(0x37),\\r
- w(0x38), w(0x39), w(0x3a), w(0x3b), w(0x3c), w(0x3d), w(0x3e), w(0x3f),\\r
- w(0x40), w(0x41), w(0x42), w(0x43), w(0x44), w(0x45), w(0x46), w(0x47),\\r
- w(0x48), w(0x49), w(0x4a), w(0x4b), w(0x4c), w(0x4d), w(0x4e), w(0x4f),\\r
- w(0x50), w(0x51), w(0x52), w(0x53), w(0x54), w(0x55), w(0x56), w(0x57),\\r
- w(0x58), w(0x59), w(0x5a), w(0x5b), w(0x5c), w(0x5d), w(0x5e), w(0x5f),\\r
- w(0x60), w(0x61), w(0x62), w(0x63), w(0x64), w(0x65), w(0x66), w(0x67),\\r
- w(0x68), w(0x69), w(0x6a), w(0x6b), w(0x6c), w(0x6d), w(0x6e), w(0x6f),\\r
- w(0x70), w(0x71), w(0x72), w(0x73), w(0x74), w(0x75), w(0x76), w(0x77),\\r
- w(0x78), w(0x79), w(0x7a), w(0x7b), w(0x7c), w(0x7d), w(0x7e), w(0x7f),\\r
- w(0x80), w(0x81), w(0x82), w(0x83), w(0x84), w(0x85), w(0x86), w(0x87),\\r
- w(0x88), w(0x89), w(0x8a), w(0x8b), w(0x8c), w(0x8d), w(0x8e), w(0x8f),\\r
- w(0x90), w(0x91), w(0x92), w(0x93), w(0x94), w(0x95), w(0x96), w(0x97),\\r
- w(0x98), w(0x99), w(0x9a), w(0x9b), w(0x9c), w(0x9d), w(0x9e), w(0x9f),\\r
- w(0xa0), w(0xa1), w(0xa2), w(0xa3), w(0xa4), w(0xa5), w(0xa6), w(0xa7),\\r
- w(0xa8), w(0xa9), w(0xaa), w(0xab), w(0xac), w(0xad), w(0xae), w(0xaf),\\r
- w(0xb0), w(0xb1), w(0xb2), w(0xb3), w(0xb4), w(0xb5), w(0xb6), w(0xb7),\\r
- w(0xb8), w(0xb9), w(0xba), w(0xbb), w(0xbc), w(0xbd), w(0xbe), w(0xbf),\\r
- w(0xc0), w(0xc1), w(0xc2), w(0xc3), w(0xc4), w(0xc5), w(0xc6), w(0xc7),\\r
- w(0xc8), w(0xc9), w(0xca), w(0xcb), w(0xcc), w(0xcd), w(0xce), w(0xcf),\\r
- w(0xd0), w(0xd1), w(0xd2), w(0xd3), w(0xd4), w(0xd5), w(0xd6), w(0xd7),\\r
- w(0xd8), w(0xd9), w(0xda), w(0xdb), w(0xdc), w(0xdd), w(0xde), w(0xdf),\\r
- w(0xe0), w(0xe1), w(0xe2), w(0xe3), w(0xe4), w(0xe5), w(0xe6), w(0xe7),\\r
- w(0xe8), w(0xe9), w(0xea), w(0xeb), w(0xec), w(0xed), w(0xee), w(0xef),\\r
- w(0xf0), w(0xf1), w(0xf2), w(0xf3), w(0xf4), w(0xf5), w(0xf6), w(0xf7),\\r
- w(0xf8), w(0xf9), w(0xfa), w(0xfb), w(0xfc), w(0xfd), w(0xfe), w(0xff) }\r
-\r
-#define rc_data(w) {\\r
- w(0x01), w(0x02), w(0x04), w(0x08), w(0x10),w(0x20), w(0x40), w(0x80),\\r
- w(0x1b), w(0x36) }\r
-\r
-#define h0(x) (x)\r
-\r
-#define w0(p) bytes2word(p, 0, 0, 0)\r
-#define w1(p) bytes2word(0, p, 0, 0)\r
-#define w2(p) bytes2word(0, 0, p, 0)\r
-#define w3(p) bytes2word(0, 0, 0, p)\r
-\r
-#define u0(p) bytes2word(f2(p), p, p, f3(p))\r
-#define u1(p) bytes2word(f3(p), f2(p), p, p)\r
-#define u2(p) bytes2word(p, f3(p), f2(p), p)\r
-#define u3(p) bytes2word(p, p, f3(p), f2(p))\r
-\r
-#define v0(p) bytes2word(fe(p), f9(p), fd(p), fb(p))\r
-#define v1(p) bytes2word(fb(p), fe(p), f9(p), fd(p))\r
-#define v2(p) bytes2word(fd(p), fb(p), fe(p), f9(p))\r
-#define v3(p) bytes2word(f9(p), fd(p), fb(p), fe(p))\r
-\r
-#endif\r
-\r
-#if defined(FIXED_TABLES) || !defined(FF_TABLES)\r
-\r
-#define f2(x) ((x<<1) ^ (((x>>7) & 1) * WPOLY))\r
-#define f4(x) ((x<<2) ^ (((x>>6) & 1) * WPOLY) ^ (((x>>6) & 2) * WPOLY))\r
-#define f8(x) ((x<<3) ^ (((x>>5) & 1) * WPOLY) ^ (((x>>5) & 2) * WPOLY) \\r
- ^ (((x>>5) & 4) * WPOLY))\r
-#define f3(x) (f2(x) ^ x)\r
-#define f9(x) (f8(x) ^ x)\r
-#define fb(x) (f8(x) ^ f2(x) ^ x)\r
-#define fd(x) (f8(x) ^ f4(x) ^ x)\r
-#define fe(x) (f8(x) ^ f4(x) ^ f2(x))\r
-\r
-#else\r
-\r
-#define f2(x) ((x) ? pow[log[x] + 0x19] : 0)\r
-#define f3(x) ((x) ? pow[log[x] + 0x01] : 0)\r
-#define f9(x) ((x) ? pow[log[x] + 0xc7] : 0)\r
-#define fb(x) ((x) ? pow[log[x] + 0x68] : 0)\r
-#define fd(x) ((x) ? pow[log[x] + 0xee] : 0)\r
-#define fe(x) ((x) ? pow[log[x] + 0xdf] : 0)\r
-#define fi(x) ((x) ? pow[ 255 - log[x]] : 0)\r
-\r
-#endif\r
-\r
-#include "aestab.h"\r
-\r
-#if defined(FIXED_TABLES)\r
-\r
-/* implemented in case of wrong call for fixed tables */\r
-\r
-void gen_tabs(void)\r
-{\r
-}\r
-\r
-#else /* dynamic table generation */\r
-\r
-#if !defined(FF_TABLES)\r
-\r
-/* Generate the tables for the dynamic table option\r
-\r
- It will generally be sensible to use tables to compute finite\r
- field multiplies and inverses but where memory is scarse this\r
- code might sometimes be better. But it only has effect during\r
- initialisation so its pretty unimportant in overall terms.\r
-*/\r
-\r
-/* return 2 ^ (n - 1) where n is the bit number of the highest bit\r
- set in x with x in the range 1 < x < 0x00000200. This form is\r
- used so that locals within fi can be bytes rather than words\r
-*/\r
-\r
-static aes_08t hibit(const aes_32t x)\r
-{ aes_08t r = (aes_08t)((x >> 1) | (x >> 2));\r
-\r
- r |= (r >> 2);\r
- r |= (r >> 4);\r
- return (r + 1) >> 1;\r
-}\r
-\r
-/* return the inverse of the finite field element x */\r
-\r
-static aes_08t fi(const aes_08t x)\r
-{ aes_08t p1 = x, p2 = BPOLY, n1 = hibit(x), n2 = 0x80, v1 = 1, v2 = 0;\r
-\r
- if(x < 2) return x;\r
-\r
- for(;;)\r
- {\r
- if(!n1) return v1;\r
-\r
- while(n2 >= n1)\r
- {\r
- n2 /= n1; p2 ^= p1 * n2; v2 ^= v1 * n2; n2 = hibit(p2);\r
- }\r
-\r
- if(!n2) return v2;\r
-\r
- while(n1 >= n2)\r
- {\r
- n1 /= n2; p1 ^= p2 * n1; v1 ^= v2 * n1; n1 = hibit(p1);\r
- }\r
- }\r
-}\r
-\r
-#endif\r
-\r
-/* The forward and inverse affine transformations used in the S-box */\r
-\r
-#define fwd_affine(x) \\r
- (w = (aes_32t)x, w ^= (w<<1)^(w<<2)^(w<<3)^(w<<4), 0x63^(aes_08t)(w^(w>>8)))\r
-\r
-#define inv_affine(x) \\r
- (w = (aes_32t)x, w = (w<<1)^(w<<3)^(w<<6), 0x05^(aes_08t)(w^(w>>8)))\r
-\r
-static int init = 0;\r
-\r
-void gen_tabs(void)\r
-{ aes_32t i, w;\r
-\r
-#if defined(FF_TABLES)\r
-\r
- aes_08t pow[512], log[256];\r
-\r
- if(init) return;\r
- /* log and power tables for GF(2^8) finite field with\r
- WPOLY as modular polynomial - the simplest primitive\r
- root is 0x03, used here to generate the tables\r
- */\r
-\r
- i = 0; w = 1;\r
- do\r
- {\r
- pow[i] = (aes_08t)w;\r
- pow[i + 255] = (aes_08t)w;\r
- log[w] = (aes_08t)i++;\r
- w ^= (w << 1) ^ (w & 0x80 ? WPOLY : 0);\r
- }\r
- while (w != 1);\r
-\r
-#else\r
- if(init) return;\r
-#endif\r
-\r
- for(i = 0, w = 1; i < RC_LENGTH; ++i)\r
- {\r
- t_set(r,c)[i] = bytes2word(w, 0, 0, 0);\r
- w = f2(w);\r
- }\r
-\r
- for(i = 0; i < 256; ++i)\r
- { aes_08t b;\r
-\r
- b = fwd_affine(fi((aes_08t)i));\r
- w = bytes2word(f2(b), b, b, f3(b));\r
-\r
-#if defined( SBX_SET )\r
- t_set(s,box)[i] = b;\r
-#endif\r
-\r
-#if defined( FT1_SET ) /* tables for a normal encryption round */\r
- t_set(f,n)[i] = w;\r
-#endif\r
-#if defined( FT4_SET )\r
- t_set(f,n)[0][i] = w;\r
- t_set(f,n)[1][i] = upr(w,1);\r
- t_set(f,n)[2][i] = upr(w,2);\r
- t_set(f,n)[3][i] = upr(w,3);\r
-#endif\r
- w = bytes2word(b, 0, 0, 0);\r
-\r
-#if defined( FL1_SET ) /* tables for last encryption round (may also */\r
- t_set(f,l)[i] = w; /* be used in the key schedule) */\r
-#endif\r
-#if defined( FL4_SET )\r
- t_set(f,l)[0][i] = w;\r
- t_set(f,l)[1][i] = upr(w,1);\r
- t_set(f,l)[2][i] = upr(w,2);\r
- t_set(f,l)[3][i] = upr(w,3);\r
-#endif\r
-\r
-#if defined( LS1_SET ) /* table for key schedule if t_set(f,l) above is */\r
- t_set(l,s)[i] = w; /* not of the required form */\r
-#endif\r
-#if defined( LS4_SET )\r
- t_set(l,s)[0][i] = w;\r
- t_set(l,s)[1][i] = upr(w,1);\r
- t_set(l,s)[2][i] = upr(w,2);\r
- t_set(l,s)[3][i] = upr(w,3);\r
-#endif\r
-\r
- b = fi(inv_affine((aes_08t)i));\r
- w = bytes2word(fe(b), f9(b), fd(b), fb(b));\r
-\r
-#if defined( IM1_SET ) /* tables for the inverse mix column operation */\r
- t_set(i,m)[b] = w;\r
-#endif\r
-#if defined( IM4_SET )\r
- t_set(i,m)[0][b] = w;\r
- t_set(i,m)[1][b] = upr(w,1);\r
- t_set(i,m)[2][b] = upr(w,2);\r
- t_set(i,m)[3][b] = upr(w,3);\r
-#endif\r
-\r
-#if defined( ISB_SET )\r
- t_set(i,box)[i] = b;\r
-#endif\r
-#if defined( IT1_SET ) /* tables for a normal decryption round */\r
- t_set(i,n)[i] = w;\r
-#endif\r
-#if defined( IT4_SET )\r
- t_set(i,n)[0][i] = w;\r
- t_set(i,n)[1][i] = upr(w,1);\r
- t_set(i,n)[2][i] = upr(w,2);\r
- t_set(i,n)[3][i] = upr(w,3);\r
-#endif\r
- w = bytes2word(b, 0, 0, 0);\r
-#if defined( IL1_SET ) /* tables for last decryption round */\r
- t_set(i,l)[i] = w;\r
-#endif\r
-#if defined( IL4_SET )\r
- t_set(i,l)[0][i] = w;\r
- t_set(i,l)[1][i] = upr(w,1);\r
- t_set(i,l)[2][i] = upr(w,2);\r
- t_set(i,l)[3][i] = upr(w,3);\r
-#endif\r
- }\r
- init = 1;\r
-}\r
-\r
-#endif\r
-\r
-#if defined(__cplusplus)\r
-}\r
-#endif\r
-\r
+/*
+ ---------------------------------------------------------------------------
+ Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved.
+
+ LICENSE TERMS
+
+ The free distribution and use of this software in both source and binary
+ form is allowed (with or without changes) provided that:
+
+ 1. distributions of this source code include the above copyright
+ notice, this list of conditions and the following disclaimer;
+
+ 2. distributions in binary form include the above copyright
+ notice, this list of conditions and the following disclaimer
+ in the documentation and/or other associated materials;
+
+ 3. the copyright holder's name is not used to endorse products
+ built using this software without specific written permission.
+
+ ALTERNATIVELY, provided that this notice is retained in full, this product
+ may be distributed under the terms of the GNU General Public License (GPL),
+ in which case the provisions of the GPL apply INSTEAD OF those given above.
+
+ DISCLAIMER
+
+ This software is provided 'as is' with no explicit or implied warranties
+ in respect of its properties, including, but not limited to, correctness
+ and/or fitness for purpose.
+ ---------------------------------------------------------------------------
+ Issue 28/01/2004
+
+*/
+
+#if defined(__cplusplus)
+extern "C"
+{
+#endif
+
+#define DO_TABLES
+
+#include "aesopt.h"
+
+#if defined(FIXED_TABLES)
+
+#define sb_data(w) {\
+ w(0x63), w(0x7c), w(0x77), w(0x7b), w(0xf2), w(0x6b), w(0x6f), w(0xc5),\
+ w(0x30), w(0x01), w(0x67), w(0x2b), w(0xfe), w(0xd7), w(0xab), w(0x76),\
+ w(0xca), w(0x82), w(0xc9), w(0x7d), w(0xfa), w(0x59), w(0x47), w(0xf0),\
+ w(0xad), w(0xd4), w(0xa2), w(0xaf), w(0x9c), w(0xa4), w(0x72), w(0xc0),\
+ w(0xb7), w(0xfd), w(0x93), w(0x26), w(0x36), w(0x3f), w(0xf7), w(0xcc),\
+ w(0x34), w(0xa5), w(0xe5), w(0xf1), w(0x71), w(0xd8), w(0x31), w(0x15),\
+ w(0x04), w(0xc7), w(0x23), w(0xc3), w(0x18), w(0x96), w(0x05), w(0x9a),\
+ w(0x07), w(0x12), w(0x80), w(0xe2), w(0xeb), w(0x27), w(0xb2), w(0x75),\
+ w(0x09), w(0x83), w(0x2c), w(0x1a), w(0x1b), w(0x6e), w(0x5a), w(0xa0),\
+ w(0x52), w(0x3b), w(0xd6), w(0xb3), w(0x29), w(0xe3), w(0x2f), w(0x84),\
+ w(0x53), w(0xd1), w(0x00), w(0xed), w(0x20), w(0xfc), w(0xb1), w(0x5b),\
+ w(0x6a), w(0xcb), w(0xbe), w(0x39), w(0x4a), w(0x4c), w(0x58), w(0xcf),\
+ w(0xd0), w(0xef), w(0xaa), w(0xfb), w(0x43), w(0x4d), w(0x33), w(0x85),\
+ w(0x45), w(0xf9), w(0x02), w(0x7f), w(0x50), w(0x3c), w(0x9f), w(0xa8),\
+ w(0x51), w(0xa3), w(0x40), w(0x8f), w(0x92), w(0x9d), w(0x38), w(0xf5),\
+ w(0xbc), w(0xb6), w(0xda), w(0x21), w(0x10), w(0xff), w(0xf3), w(0xd2),\
+ w(0xcd), w(0x0c), w(0x13), w(0xec), w(0x5f), w(0x97), w(0x44), w(0x17),\
+ w(0xc4), w(0xa7), w(0x7e), w(0x3d), w(0x64), w(0x5d), w(0x19), w(0x73),\
+ w(0x60), w(0x81), w(0x4f), w(0xdc), w(0x22), w(0x2a), w(0x90), w(0x88),\
+ w(0x46), w(0xee), w(0xb8), w(0x14), w(0xde), w(0x5e), w(0x0b), w(0xdb),\
+ w(0xe0), w(0x32), w(0x3a), w(0x0a), w(0x49), w(0x06), w(0x24), w(0x5c),\
+ w(0xc2), w(0xd3), w(0xac), w(0x62), w(0x91), w(0x95), w(0xe4), w(0x79),\
+ w(0xe7), w(0xc8), w(0x37), w(0x6d), w(0x8d), w(0xd5), w(0x4e), w(0xa9),\
+ w(0x6c), w(0x56), w(0xf4), w(0xea), w(0x65), w(0x7a), w(0xae), w(0x08),\
+ w(0xba), w(0x78), w(0x25), w(0x2e), w(0x1c), w(0xa6), w(0xb4), w(0xc6),\
+ w(0xe8), w(0xdd), w(0x74), w(0x1f), w(0x4b), w(0xbd), w(0x8b), w(0x8a),\
+ w(0x70), w(0x3e), w(0xb5), w(0x66), w(0x48), w(0x03), w(0xf6), w(0x0e),\
+ w(0x61), w(0x35), w(0x57), w(0xb9), w(0x86), w(0xc1), w(0x1d), w(0x9e),\
+ w(0xe1), w(0xf8), w(0x98), w(0x11), w(0x69), w(0xd9), w(0x8e), w(0x94),\
+ w(0x9b), w(0x1e), w(0x87), w(0xe9), w(0xce), w(0x55), w(0x28), w(0xdf),\
+ w(0x8c), w(0xa1), w(0x89), w(0x0d), w(0xbf), w(0xe6), w(0x42), w(0x68),\
+ w(0x41), w(0x99), w(0x2d), w(0x0f), w(0xb0), w(0x54), w(0xbb), w(0x16) }
+
+#define isb_data(w) {\
+ w(0x52), w(0x09), w(0x6a), w(0xd5), w(0x30), w(0x36), w(0xa5), w(0x38),\
+ w(0xbf), w(0x40), w(0xa3), w(0x9e), w(0x81), w(0xf3), w(0xd7), w(0xfb),\
+ w(0x7c), w(0xe3), w(0x39), w(0x82), w(0x9b), w(0x2f), w(0xff), w(0x87),\
+ w(0x34), w(0x8e), w(0x43), w(0x44), w(0xc4), w(0xde), w(0xe9), w(0xcb),\
+ w(0x54), w(0x7b), w(0x94), w(0x32), w(0xa6), w(0xc2), w(0x23), w(0x3d),\
+ w(0xee), w(0x4c), w(0x95), w(0x0b), w(0x42), w(0xfa), w(0xc3), w(0x4e),\
+ w(0x08), w(0x2e), w(0xa1), w(0x66), w(0x28), w(0xd9), w(0x24), w(0xb2),\
+ w(0x76), w(0x5b), w(0xa2), w(0x49), w(0x6d), w(0x8b), w(0xd1), w(0x25),\
+ w(0x72), w(0xf8), w(0xf6), w(0x64), w(0x86), w(0x68), w(0x98), w(0x16),\
+ w(0xd4), w(0xa4), w(0x5c), w(0xcc), w(0x5d), w(0x65), w(0xb6), w(0x92),\
+ w(0x6c), w(0x70), w(0x48), w(0x50), w(0xfd), w(0xed), w(0xb9), w(0xda),\
+ w(0x5e), w(0x15), w(0x46), w(0x57), w(0xa7), w(0x8d), w(0x9d), w(0x84),\
+ w(0x90), w(0xd8), w(0xab), w(0x00), w(0x8c), w(0xbc), w(0xd3), w(0x0a),\
+ w(0xf7), w(0xe4), w(0x58), w(0x05), w(0xb8), w(0xb3), w(0x45), w(0x06),\
+ w(0xd0), w(0x2c), w(0x1e), w(0x8f), w(0xca), w(0x3f), w(0x0f), w(0x02),\
+ w(0xc1), w(0xaf), w(0xbd), w(0x03), w(0x01), w(0x13), w(0x8a), w(0x6b),\
+ w(0x3a), w(0x91), w(0x11), w(0x41), w(0x4f), w(0x67), w(0xdc), w(0xea),\
+ w(0x97), w(0xf2), w(0xcf), w(0xce), w(0xf0), w(0xb4), w(0xe6), w(0x73),\
+ w(0x96), w(0xac), w(0x74), w(0x22), w(0xe7), w(0xad), w(0x35), w(0x85),\
+ w(0xe2), w(0xf9), w(0x37), w(0xe8), w(0x1c), w(0x75), w(0xdf), w(0x6e),\
+ w(0x47), w(0xf1), w(0x1a), w(0x71), w(0x1d), w(0x29), w(0xc5), w(0x89),\
+ w(0x6f), w(0xb7), w(0x62), w(0x0e), w(0xaa), w(0x18), w(0xbe), w(0x1b),\
+ w(0xfc), w(0x56), w(0x3e), w(0x4b), w(0xc6), w(0xd2), w(0x79), w(0x20),\
+ w(0x9a), w(0xdb), w(0xc0), w(0xfe), w(0x78), w(0xcd), w(0x5a), w(0xf4),\
+ w(0x1f), w(0xdd), w(0xa8), w(0x33), w(0x88), w(0x07), w(0xc7), w(0x31),\
+ w(0xb1), w(0x12), w(0x10), w(0x59), w(0x27), w(0x80), w(0xec), w(0x5f),\
+ w(0x60), w(0x51), w(0x7f), w(0xa9), w(0x19), w(0xb5), w(0x4a), w(0x0d),\
+ w(0x2d), w(0xe5), w(0x7a), w(0x9f), w(0x93), w(0xc9), w(0x9c), w(0xef),\
+ w(0xa0), w(0xe0), w(0x3b), w(0x4d), w(0xae), w(0x2a), w(0xf5), w(0xb0),\
+ w(0xc8), w(0xeb), w(0xbb), w(0x3c), w(0x83), w(0x53), w(0x99), w(0x61),\
+ w(0x17), w(0x2b), w(0x04), w(0x7e), w(0xba), w(0x77), w(0xd6), w(0x26),\
+ w(0xe1), w(0x69), w(0x14), w(0x63), w(0x55), w(0x21), w(0x0c), w(0x7d) }
+
+#define mm_data(w) {\
+ w(0x00), w(0x01), w(0x02), w(0x03), w(0x04), w(0x05), w(0x06), w(0x07),\
+ w(0x08), w(0x09), w(0x0a), w(0x0b), w(0x0c), w(0x0d), w(0x0e), w(0x0f),\
+ w(0x10), w(0x11), w(0x12), w(0x13), w(0x14), w(0x15), w(0x16), w(0x17),\
+ w(0x18), w(0x19), w(0x1a), w(0x1b), w(0x1c), w(0x1d), w(0x1e), w(0x1f),\
+ w(0x20), w(0x21), w(0x22), w(0x23), w(0x24), w(0x25), w(0x26), w(0x27),\
+ w(0x28), w(0x29), w(0x2a), w(0x2b), w(0x2c), w(0x2d), w(0x2e), w(0x2f),\
+ w(0x30), w(0x31), w(0x32), w(0x33), w(0x34), w(0x35), w(0x36), w(0x37),\
+ w(0x38), w(0x39), w(0x3a), w(0x3b), w(0x3c), w(0x3d), w(0x3e), w(0x3f),\
+ w(0x40), w(0x41), w(0x42), w(0x43), w(0x44), w(0x45), w(0x46), w(0x47),\
+ w(0x48), w(0x49), w(0x4a), w(0x4b), w(0x4c), w(0x4d), w(0x4e), w(0x4f),\
+ w(0x50), w(0x51), w(0x52), w(0x53), w(0x54), w(0x55), w(0x56), w(0x57),\
+ w(0x58), w(0x59), w(0x5a), w(0x5b), w(0x5c), w(0x5d), w(0x5e), w(0x5f),\
+ w(0x60), w(0x61), w(0x62), w(0x63), w(0x64), w(0x65), w(0x66), w(0x67),\
+ w(0x68), w(0x69), w(0x6a), w(0x6b), w(0x6c), w(0x6d), w(0x6e), w(0x6f),\
+ w(0x70), w(0x71), w(0x72), w(0x73), w(0x74), w(0x75), w(0x76), w(0x77),\
+ w(0x78), w(0x79), w(0x7a), w(0x7b), w(0x7c), w(0x7d), w(0x7e), w(0x7f),\
+ w(0x80), w(0x81), w(0x82), w(0x83), w(0x84), w(0x85), w(0x86), w(0x87),\
+ w(0x88), w(0x89), w(0x8a), w(0x8b), w(0x8c), w(0x8d), w(0x8e), w(0x8f),\
+ w(0x90), w(0x91), w(0x92), w(0x93), w(0x94), w(0x95), w(0x96), w(0x97),\
+ w(0x98), w(0x99), w(0x9a), w(0x9b), w(0x9c), w(0x9d), w(0x9e), w(0x9f),\
+ w(0xa0), w(0xa1), w(0xa2), w(0xa3), w(0xa4), w(0xa5), w(0xa6), w(0xa7),\
+ w(0xa8), w(0xa9), w(0xaa), w(0xab), w(0xac), w(0xad), w(0xae), w(0xaf),\
+ w(0xb0), w(0xb1), w(0xb2), w(0xb3), w(0xb4), w(0xb5), w(0xb6), w(0xb7),\
+ w(0xb8), w(0xb9), w(0xba), w(0xbb), w(0xbc), w(0xbd), w(0xbe), w(0xbf),\
+ w(0xc0), w(0xc1), w(0xc2), w(0xc3), w(0xc4), w(0xc5), w(0xc6), w(0xc7),\
+ w(0xc8), w(0xc9), w(0xca), w(0xcb), w(0xcc), w(0xcd), w(0xce), w(0xcf),\
+ w(0xd0), w(0xd1), w(0xd2), w(0xd3), w(0xd4), w(0xd5), w(0xd6), w(0xd7),\
+ w(0xd8), w(0xd9), w(0xda), w(0xdb), w(0xdc), w(0xdd), w(0xde), w(0xdf),\
+ w(0xe0), w(0xe1), w(0xe2), w(0xe3), w(0xe4), w(0xe5), w(0xe6), w(0xe7),\
+ w(0xe8), w(0xe9), w(0xea), w(0xeb), w(0xec), w(0xed), w(0xee), w(0xef),\
+ w(0xf0), w(0xf1), w(0xf2), w(0xf3), w(0xf4), w(0xf5), w(0xf6), w(0xf7),\
+ w(0xf8), w(0xf9), w(0xfa), w(0xfb), w(0xfc), w(0xfd), w(0xfe), w(0xff) }
+
+#define rc_data(w) {\
+ w(0x01), w(0x02), w(0x04), w(0x08), w(0x10),w(0x20), w(0x40), w(0x80),\
+ w(0x1b), w(0x36) }
+
+#define h0(x) (x)
+
+#define w0(p) bytes2word(p, 0, 0, 0)
+#define w1(p) bytes2word(0, p, 0, 0)
+#define w2(p) bytes2word(0, 0, p, 0)
+#define w3(p) bytes2word(0, 0, 0, p)
+
+#define u0(p) bytes2word(f2(p), p, p, f3(p))
+#define u1(p) bytes2word(f3(p), f2(p), p, p)
+#define u2(p) bytes2word(p, f3(p), f2(p), p)
+#define u3(p) bytes2word(p, p, f3(p), f2(p))
+
+#define v0(p) bytes2word(fe(p), f9(p), fd(p), fb(p))
+#define v1(p) bytes2word(fb(p), fe(p), f9(p), fd(p))
+#define v2(p) bytes2word(fd(p), fb(p), fe(p), f9(p))
+#define v3(p) bytes2word(f9(p), fd(p), fb(p), fe(p))
+
+#endif
+
+#if defined(FIXED_TABLES) || !defined(FF_TABLES)
+
+#define f2(x) ((x<<1) ^ (((x>>7) & 1) * WPOLY))
+#define f4(x) ((x<<2) ^ (((x>>6) & 1) * WPOLY) ^ (((x>>6) & 2) * WPOLY))
+#define f8(x) ((x<<3) ^ (((x>>5) & 1) * WPOLY) ^ (((x>>5) & 2) * WPOLY) \
+ ^ (((x>>5) & 4) * WPOLY))
+#define f3(x) (f2(x) ^ x)
+#define f9(x) (f8(x) ^ x)
+#define fb(x) (f8(x) ^ f2(x) ^ x)
+#define fd(x) (f8(x) ^ f4(x) ^ x)
+#define fe(x) (f8(x) ^ f4(x) ^ f2(x))
+
+#else
+
+#define f2(x) ((x) ? pow[log[x] + 0x19] : 0)
+#define f3(x) ((x) ? pow[log[x] + 0x01] : 0)
+#define f9(x) ((x) ? pow[log[x] + 0xc7] : 0)
+#define fb(x) ((x) ? pow[log[x] + 0x68] : 0)
+#define fd(x) ((x) ? pow[log[x] + 0xee] : 0)
+#define fe(x) ((x) ? pow[log[x] + 0xdf] : 0)
+#define fi(x) ((x) ? pow[ 255 - log[x]] : 0)
+
+#endif
+
+#include "aestab.h"
+
+#if defined(FIXED_TABLES)
+
+/* implemented in case of wrong call for fixed tables */
+
+void gen_tabs(void)
+{
+}
+
+#else /* dynamic table generation */
+
+#if !defined(FF_TABLES)
+
+/* Generate the tables for the dynamic table option
+
+ It will generally be sensible to use tables to compute finite
+ field multiplies and inverses but where memory is scarse this
+ code might sometimes be better. But it only has effect during
+ initialisation so its pretty unimportant in overall terms.
+*/
+
+/* return 2 ^ (n - 1) where n is the bit number of the highest bit
+ set in x with x in the range 1 < x < 0x00000200. This form is
+ used so that locals within fi can be bytes rather than words
+*/
+
+static aes_08t hibit(const aes_32t x)
+{ aes_08t r = (aes_08t)((x >> 1) | (x >> 2));
+
+ r |= (r >> 2);
+ r |= (r >> 4);
+ return (r + 1) >> 1;
+}
+
+/* return the inverse of the finite field element x */
+
+static aes_08t fi(const aes_08t x)
+{ aes_08t p1 = x, p2 = BPOLY, n1 = hibit(x), n2 = 0x80, v1 = 1, v2 = 0;
+
+ if(x < 2) return x;
+
+ for(;;)
+ {
+ if(!n1) return v1;
+
+ while(n2 >= n1)
+ {
+ n2 /= n1; p2 ^= p1 * n2; v2 ^= v1 * n2; n2 = hibit(p2);
+ }
+
+ if(!n2) return v2;
+
+ while(n1 >= n2)
+ {
+ n1 /= n2; p1 ^= p2 * n1; v1 ^= v2 * n1; n1 = hibit(p1);
+ }
+ }
+}
+
+#endif
+
+/* The forward and inverse affine transformations used in the S-box */
+
+#define fwd_affine(x) \
+ (w = (aes_32t)x, w ^= (w<<1)^(w<<2)^(w<<3)^(w<<4), 0x63^(aes_08t)(w^(w>>8)))
+
+#define inv_affine(x) \
+ (w = (aes_32t)x, w = (w<<1)^(w<<3)^(w<<6), 0x05^(aes_08t)(w^(w>>8)))
+
+static int init = 0;
+
+void gen_tabs(void)
+{ aes_32t i, w;
+
+#if defined(FF_TABLES)
+
+ aes_08t pow[512], log[256];
+
+ if(init) return;
+ /* log and power tables for GF(2^8) finite field with
+ WPOLY as modular polynomial - the simplest primitive
+ root is 0x03, used here to generate the tables
+ */
+
+ i = 0; w = 1;
+ do
+ {
+ pow[i] = (aes_08t)w;
+ pow[i + 255] = (aes_08t)w;
+ log[w] = (aes_08t)i++;
+ w ^= (w << 1) ^ (w & 0x80 ? WPOLY : 0);
+ }
+ while (w != 1);
+
+#else
+ if(init) return;
+#endif
+
+ for(i = 0, w = 1; i < RC_LENGTH; ++i)
+ {
+ t_set(r,c)[i] = bytes2word(w, 0, 0, 0);
+ w = f2(w);
+ }
+
+ for(i = 0; i < 256; ++i)
+ { aes_08t b;
+
+ b = fwd_affine(fi((aes_08t)i));
+ w = bytes2word(f2(b), b, b, f3(b));
+
+#if defined( SBX_SET )
+ t_set(s,box)[i] = b;
+#endif
+
+#if defined( FT1_SET ) /* tables for a normal encryption round */
+ t_set(f,n)[i] = w;
+#endif
+#if defined( FT4_SET )
+ t_set(f,n)[0][i] = w;
+ t_set(f,n)[1][i] = upr(w,1);
+ t_set(f,n)[2][i] = upr(w,2);
+ t_set(f,n)[3][i] = upr(w,3);
+#endif
+ w = bytes2word(b, 0, 0, 0);
+
+#if defined( FL1_SET ) /* tables for last encryption round (may also */
+ t_set(f,l)[i] = w; /* be used in the key schedule) */
+#endif
+#if defined( FL4_SET )
+ t_set(f,l)[0][i] = w;
+ t_set(f,l)[1][i] = upr(w,1);
+ t_set(f,l)[2][i] = upr(w,2);
+ t_set(f,l)[3][i] = upr(w,3);
+#endif
+
+#if defined( LS1_SET ) /* table for key schedule if t_set(f,l) above is */
+ t_set(l,s)[i] = w; /* not of the required form */
+#endif
+#if defined( LS4_SET )
+ t_set(l,s)[0][i] = w;
+ t_set(l,s)[1][i] = upr(w,1);
+ t_set(l,s)[2][i] = upr(w,2);
+ t_set(l,s)[3][i] = upr(w,3);
+#endif
+
+ b = fi(inv_affine((aes_08t)i));
+ w = bytes2word(fe(b), f9(b), fd(b), fb(b));
+
+#if defined( IM1_SET ) /* tables for the inverse mix column operation */
+ t_set(i,m)[b] = w;
+#endif
+#if defined( IM4_SET )
+ t_set(i,m)[0][b] = w;
+ t_set(i,m)[1][b] = upr(w,1);
+ t_set(i,m)[2][b] = upr(w,2);
+ t_set(i,m)[3][b] = upr(w,3);
+#endif
+
+#if defined( ISB_SET )
+ t_set(i,box)[i] = b;
+#endif
+#if defined( IT1_SET ) /* tables for a normal decryption round */
+ t_set(i,n)[i] = w;
+#endif
+#if defined( IT4_SET )
+ t_set(i,n)[0][i] = w;
+ t_set(i,n)[1][i] = upr(w,1);
+ t_set(i,n)[2][i] = upr(w,2);
+ t_set(i,n)[3][i] = upr(w,3);
+#endif
+ w = bytes2word(b, 0, 0, 0);
+#if defined( IL1_SET ) /* tables for last decryption round */
+ t_set(i,l)[i] = w;
+#endif
+#if defined( IL4_SET )
+ t_set(i,l)[0][i] = w;
+ t_set(i,l)[1][i] = upr(w,1);
+ t_set(i,l)[2][i] = upr(w,2);
+ t_set(i,l)[3][i] = upr(w,3);
+#endif
+ }
+ init = 1;
+}
+
+#endif
+
+#if defined(__cplusplus)
+}
+#endif
+
-/*\r
- ---------------------------------------------------------------------------\r
- Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved.\r
-\r
- LICENSE TERMS\r
-\r
- The free distribution and use of this software in both source and binary\r
- form is allowed (with or without changes) provided that:\r
-\r
- 1. distributions of this source code include the above copyright\r
- notice, this list of conditions and the following disclaimer;\r
-\r
- 2. distributions in binary form include the above copyright\r
- notice, this list of conditions and the following disclaimer\r
- in the documentation and/or other associated materials;\r
-\r
- 3. the copyright holder's name is not used to endorse products\r
- built using this software without specific written permission.\r
-\r
- ALTERNATIVELY, provided that this notice is retained in full, this product\r
- may be distributed under the terms of the GNU General Public License (GPL),\r
- in which case the provisions of the GPL apply INSTEAD OF those given above.\r
-\r
- DISCLAIMER\r
-\r
- This software is provided 'as is' with no explicit or implied warranties\r
- in respect of its properties, including, but not limited to, correctness\r
- and/or fitness for purpose.\r
- ---------------------------------------------------------------------------\r
- Issue 28/01/2004\r
-\r
- This file contains the code for declaring the tables needed to implement\r
- AES. The file aesopt.h is assumed to be included before this header file.\r
- If there are no global variables, the definitions here can be used to put\r
- the AES tables in a structure so that a pointer can then be added to the\r
- AES context to pass them to the AES routines that need them. If this\r
- facility is used, the calling program has to ensure that this pointer is\r
- managed appropriately. In particular, the value of the t_dec(in,it) item\r
- in the table structure must be set to zero in order to ensure that the\r
- tables are initialised. In practice the three code sequences in aeskey.c\r
- that control the calls to gen_tabs() and the gen_tabs() routine itself will\r
- have to be changed for a specific implementation. If global variables are\r
- available it will generally be preferable to use them with the precomputed\r
- FIXED_TABLES option that uses static global tables.\r
-\r
- The following defines can be used to control the way the tables\r
- are defined, initialised and used in embedded environments that\r
- require special features for these purposes\r
-\r
- the 't_dec' construction is used to declare fixed table arrays\r
- the 't_set' construction is used to set fixed table values\r
- the 't_use' construction is used to access fixed table values\r
-\r
- 256 byte tables:\r
-\r
- t_xxx(s,box) => forward S box\r
- t_xxx(i,box) => inverse S box\r
-\r
- 256 32-bit word OR 4 x 256 32-bit word tables:\r
-\r
- t_xxx(f,n) => forward normal round\r
- t_xxx(f,l) => forward last round\r
- t_xxx(i,n) => inverse normal round\r
- t_xxx(i,l) => inverse last round\r
- t_xxx(l,s) => key schedule table\r
- t_xxx(i,m) => key schedule table\r
-\r
- Other variables and tables:\r
-\r
- t_xxx(r,c) => the rcon table\r
-*/\r
-\r
-#if !defined( _AESTAB_H )\r
-#define _AESTAB_H\r
-\r
-#define t_dec(m,n) t_##m##n\r
-#define t_set(m,n) t_##m##n\r
-#define t_use(m,n) t_##m##n\r
-\r
-#if defined(FIXED_TABLES)\r
-#define Const const\r
-#else\r
-#define Const\r
-#endif\r
-\r
-#if defined(DO_TABLES)\r
-#define Extern\r
-#else\r
-#define Extern extern\r
-#endif\r
-\r
-#if defined(_MSC_VER) && defined(TABLE_ALIGN)\r
-#define Align __declspec(align(TABLE_ALIGN))\r
-#else\r
-#define Align\r
-#endif\r
-\r
-#if defined(__cplusplus)\r
-extern "C"\r
-{\r
-#endif\r
-\r
-#if defined(DO_TABLES) && defined(FIXED_TABLES)\r
-#define d_1(t,n,b,e) Align Const t n[256] = b(e)\r
-#define d_4(t,n,b,e,f,g,h) Align Const t n[4][256] = { b(e), b(f), b(g), b(h) }\r
-Extern Align Const aes_32t t_dec(r,c)[RC_LENGTH] = rc_data(w0);\r
-#else\r
-#define d_1(t,n,b,e) Extern Align Const t n[256]\r
-#define d_4(t,n,b,e,f,g,h) Extern Align Const t n[4][256]\r
-Extern Align Const aes_32t t_dec(r,c)[RC_LENGTH];\r
-#endif\r
-\r
-#if defined( SBX_SET )\r
- d_1(aes_08t, t_dec(s,box), sb_data, h0);\r
-#endif\r
-#if defined( ISB_SET )\r
- d_1(aes_08t, t_dec(i,box), isb_data, h0);\r
-#endif\r
-\r
-#if defined( FT1_SET )\r
- d_1(aes_32t, t_dec(f,n), sb_data, u0);\r
-#endif\r
-#if defined( FT4_SET )\r
- d_4(aes_32t, t_dec(f,n), sb_data, u0, u1, u2, u3);\r
-#endif\r
-\r
-#if defined( FL1_SET )\r
- d_1(aes_32t, t_dec(f,l), sb_data, w0);\r
-#endif\r
-#if defined( FL4_SET )\r
- d_4(aes_32t, t_dec(f,l), sb_data, w0, w1, w2, w3);\r
-#endif\r
-\r
-#if defined( IT1_SET )\r
- d_1(aes_32t, t_dec(i,n), isb_data, v0);\r
-#endif\r
-#if defined( IT4_SET )\r
- d_4(aes_32t, t_dec(i,n), isb_data, v0, v1, v2, v3);\r
-#endif\r
-\r
-#if defined( IL1_SET )\r
- d_1(aes_32t, t_dec(i,l), isb_data, w0);\r
-#endif\r
-#if defined( IL4_SET )\r
- d_4(aes_32t, t_dec(i,l), isb_data, w0, w1, w2, w3);\r
-#endif\r
-\r
-#if defined( LS1_SET )\r
-#if defined( FL1_SET )\r
-#undef LS1_SET\r
-#else\r
- d_1(aes_32t, t_dec(l,s), sb_data, w0);\r
-#endif\r
-#endif\r
-\r
-#if defined( LS4_SET )\r
-#if defined( FL4_SET )\r
-#undef LS4_SET\r
-#else\r
- d_4(aes_32t, t_dec(l,s), sb_data, w0, w1, w2, w3);\r
-#endif\r
-#endif\r
-\r
-#if defined( IM1_SET )\r
- d_1(aes_32t, t_dec(i,m), mm_data, v0);\r
-#endif\r
-#if defined( IM4_SET )\r
- d_4(aes_32t, t_dec(i,m), mm_data, v0, v1, v2, v3);\r
-#endif\r
-\r
-#if defined(__cplusplus)\r
-}\r
-#endif\r
-\r
-#endif\r
+/*
+ ---------------------------------------------------------------------------
+ Copyright (c) 2003, Dr Brian Gladman, Worcester, UK. All rights reserved.
+
+ LICENSE TERMS
+
+ The free distribution and use of this software in both source and binary
+ form is allowed (with or without changes) provided that:
+
+ 1. distributions of this source code include the above copyright
+ notice, this list of conditions and the following disclaimer;
+
+ 2. distributions in binary form include the above copyright
+ notice, this list of conditions and the following disclaimer
+ in the documentation and/or other associated materials;
+
+ 3. the copyright holder's name is not used to endorse products
+ built using this software without specific written permission.
+
+ ALTERNATIVELY, provided that this notice is retained in full, this product
+ may be distributed under the terms of the GNU General Public License (GPL),
+ in which case the provisions of the GPL apply INSTEAD OF those given above.
+
+ DISCLAIMER
+
+ This software is provided 'as is' with no explicit or implied warranties
+ in respect of its properties, including, but not limited to, correctness
+ and/or fitness for purpose.
+ ---------------------------------------------------------------------------
+ Issue 28/01/2004
+
+ This file contains the code for declaring the tables needed to implement
+ AES. The file aesopt.h is assumed to be included before this header file.
+ If there are no global variables, the definitions here can be used to put
+ the AES tables in a structure so that a pointer can then be added to the
+ AES context to pass them to the AES routines that need them. If this
+ facility is used, the calling program has to ensure that this pointer is
+ managed appropriately. In particular, the value of the t_dec(in,it) item
+ in the table structure must be set to zero in order to ensure that the
+ tables are initialised. In practice the three code sequences in aeskey.c
+ that control the calls to gen_tabs() and the gen_tabs() routine itself will
+ have to be changed for a specific implementation. If global variables are
+ available it will generally be preferable to use them with the precomputed
+ FIXED_TABLES option that uses static global tables.
+
+ The following defines can be used to control the way the tables
+ are defined, initialised and used in embedded environments that
+ require special features for these purposes
+
+ the 't_dec' construction is used to declare fixed table arrays
+ the 't_set' construction is used to set fixed table values
+ the 't_use' construction is used to access fixed table values
+
+ 256 byte tables:
+
+ t_xxx(s,box) => forward S box
+ t_xxx(i,box) => inverse S box
+
+ 256 32-bit word OR 4 x 256 32-bit word tables:
+
+ t_xxx(f,n) => forward normal round
+ t_xxx(f,l) => forward last round
+ t_xxx(i,n) => inverse normal round
+ t_xxx(i,l) => inverse last round
+ t_xxx(l,s) => key schedule table
+ t_xxx(i,m) => key schedule table
+
+ Other variables and tables:
+
+ t_xxx(r,c) => the rcon table
+*/
+
+#if !defined( _AESTAB_H )
+#define _AESTAB_H
+
+#define t_dec(m,n) t_##m##n
+#define t_set(m,n) t_##m##n
+#define t_use(m,n) t_##m##n
+
+#if defined(FIXED_TABLES)
+#define Const const
+#else
+#define Const
+#endif
+
+#if defined(DO_TABLES)
+#define Extern
+#else
+#define Extern extern
+#endif
+
+#if defined(_MSC_VER) && defined(TABLE_ALIGN)
+#define Align __declspec(align(TABLE_ALIGN))
+#else
+#define Align
+#endif
+
+#if defined(__cplusplus)
+extern "C"
+{
+#endif
+
+#if defined(DO_TABLES) && defined(FIXED_TABLES)
+#define d_1(t,n,b,e) Align Const t n[256] = b(e)
+#define d_4(t,n,b,e,f,g,h) Align Const t n[4][256] = { b(e), b(f), b(g), b(h) }
+Extern Align Const aes_32t t_dec(r,c)[RC_LENGTH] = rc_data(w0);
+#else
+#define d_1(t,n,b,e) Extern Align Const t n[256]
+#define d_4(t,n,b,e,f,g,h) Extern Align Const t n[4][256]
+Extern Align Const aes_32t t_dec(r,c)[RC_LENGTH];
+#endif
+
+#if defined( SBX_SET )
+ d_1(aes_08t, t_dec(s,box), sb_data, h0);
+#endif
+#if defined( ISB_SET )
+ d_1(aes_08t, t_dec(i,box), isb_data, h0);
+#endif
+
+#if defined( FT1_SET )
+ d_1(aes_32t, t_dec(f,n), sb_data, u0);
+#endif
+#if defined( FT4_SET )
+ d_4(aes_32t, t_dec(f,n), sb_data, u0, u1, u2, u3);
+#endif
+
+#if defined( FL1_SET )
+ d_1(aes_32t, t_dec(f,l), sb_data, w0);
+#endif
+#if defined( FL4_SET )
+ d_4(aes_32t, t_dec(f,l), sb_data, w0, w1, w2, w3);
+#endif
+
+#if defined( IT1_SET )
+ d_1(aes_32t, t_dec(i,n), isb_data, v0);
+#endif
+#if defined( IT4_SET )
+ d_4(aes_32t, t_dec(i,n), isb_data, v0, v1, v2, v3);
+#endif
+
+#if defined( IL1_SET )
+ d_1(aes_32t, t_dec(i,l), isb_data, w0);
+#endif
+#if defined( IL4_SET )
+ d_4(aes_32t, t_dec(i,l), isb_data, w0, w1, w2, w3);
+#endif
+
+#if defined( LS1_SET )
+#if defined( FL1_SET )
+#undef LS1_SET
+#else
+ d_1(aes_32t, t_dec(l,s), sb_data, w0);
+#endif
+#endif
+
+#if defined( LS4_SET )
+#if defined( FL4_SET )
+#undef LS4_SET
+#else
+ d_4(aes_32t, t_dec(l,s), sb_data, w0, w1, w2, w3);
+#endif
+#endif
+
+#if defined( IM1_SET )
+ d_1(aes_32t, t_dec(i,m), mm_data, v0);
+#endif
+#if defined( IM4_SET )
+ d_4(aes_32t, t_dec(i,m), mm_data, v0, v1, v2, v3);
+#endif
+
+#if defined(__cplusplus)
+}
+#endif
+
+#endif
/* NOTREACHED */
}
+extern vm_map_offset_t kvtophys64(vm_map_offset_t);
+
boolean_t
kernacc(
off_t start,
end = start + len;
while (base < end) {
- if(kvtophys((vm_offset_t)base) == NULL)
+ if(kvtophys64((vm_map_offset_t)base) == (vm_map_offset_t)0)
return(FALSE);
base += page_size;
}
searchinfospec_t *searchInfo2,
Boolean lookForDup );
-static int CheckAccess(ExtendedVCB *vcb, u_long searchBits, CatalogKey *key, struct proc *p);
+static int CheckAccess(ExtendedVCB *vcb, u_long searchBits, CatalogKey *key, struct vfs_context *ctx);
static int InsertMatch(struct hfsmount *hfsmp, uio_t a_uio, CatalogRecord *rec,
CatalogKey *key, struct attrlist *returnAttrList,
attrs = ap->a_searchattrs->commonattr | ap->a_returnattrs->commonattr;
if (attrs & (ATTR_CMN_NAME | ATTR_CMN_PAROBJID))
return (EINVAL);
- if ((err = suser(kauth_cred_get(), 0)))
+ if ((err = vfs_context_suser(ap->a_context)))
return (err);
}
hfs_systemfile_unlock(hfsmp, lockflags);
if (CheckCriteria(vcb, ap->a_options, ap->a_searchattrs, &rec,
keyp, &searchInfo1, &searchInfo2, false) &&
- CheckAccess(vcb, ap->a_options, keyp, p)) {
+ CheckAccess(vcb, ap->a_options, keyp, ap->a_context)) {
result = InsertMatch(hfsmp, ap->a_uio, &rec,
keyp, ap->a_returnattrs,
}
if (CheckCriteria( vcb, ap->a_options, ap->a_searchattrs, myCurrentDataPtr,
myCurrentKeyPtr, &searchInfo1, &searchInfo2, true )
- && CheckAccess(vcb, ap->a_options, myCurrentKeyPtr, p)) {
+ && CheckAccess(vcb, ap->a_options, myCurrentKeyPtr, ap->a_context)) {
err = InsertMatch(hfsmp, ap->a_uio, myCurrentDataPtr,
myCurrentKeyPtr, ap->a_returnattrs,
attributesBuffer, variableBuffer, ap->a_nummatches);
*/
static int
-CheckAccess(ExtendedVCB *theVCBPtr, u_long searchBits, CatalogKey *theKeyPtr, struct proc *theProcPtr)
+CheckAccess(ExtendedVCB *theVCBPtr, u_long searchBits, CatalogKey *theKeyPtr, struct vfs_context *ctx)
{
Boolean isHFSPlus;
int myErr;
hfsmount_t * hfsmp;
struct FndrDirInfo *finfop;
struct vnode * vp = NULL;
- struct vfs_context my_context;
myResult = 0; /* default to "no access" */
- my_context.vc_proc = theProcPtr;
- my_context.vc_ucred = kauth_cred_get();
- if (!proc_suser(theProcPtr)) {
+ if (!vfs_context_suser(ctx)) {
myResult = 1; /* allow access */
goto ExitThisRoutine; /* root always has access */
}
myNodeID = cp->c_parentcnid; /* move up the hierarchy */
hfs_unlock(VTOC(vp));
if (vp->v_type == VDIR) {
- myErr = vnode_authorize(vp, NULL, (KAUTH_VNODE_SEARCH | KAUTH_VNODE_LIST_DIRECTORY), &my_context);
+ myErr = vnode_authorize(vp, NULL, (KAUTH_VNODE_SEARCH | KAUTH_VNODE_LIST_DIRECTORY), ctx);
} else {
- myErr = vnode_authorize(vp, NULL, (KAUTH_VNODE_SEARCH), &my_context);
+ myErr = vnode_authorize(vp, NULL, (KAUTH_VNODE_SEARCH), ctx);
}
vnode_put(vp);
vp = NULL;
/* Pick up volume name and create date */
retval = cat_idlookup(hfsmp, kHFSRootFolderID, &cndesc, &cnattr, NULL);
if (retval) {
+ if (hfsmp->hfs_attribute_vp)
+ hfs_unlock(VTOC(hfsmp->hfs_attribute_vp));
hfs_unlock(VTOC(hfsmp->hfs_allocation_vp));
hfs_unlock(VTOC(hfsmp->hfs_catalog_vp));
hfs_unlock(VTOC(hfsmp->hfs_extents_vp));
return(EBADF);
}
if ( fp != NULL ) {
- error = dofilewrite( entryp->procp, fp, entryp->aiocb.aio_fildes,
- entryp->aiocb.aio_buf,
- entryp->aiocb.aio_nbytes,
- entryp->aiocb.aio_offset, FOF_OFFSET,
- &entryp->returnval );
+ /* NB: tell dofilewrite the offset, and to use the proc cred */
+ error = dofilewrite( entryp->procp,
+ fp,
+ entryp->aiocb.aio_fildes,
+ entryp->aiocb.aio_buf,
+ entryp->aiocb.aio_nbytes,
+ entryp->aiocb.aio_offset,
+ FOF_OFFSET | FOF_PCRED,
+ &entryp->returnval);
fp_drop(entryp->procp, entryp->aiocb.aio_fildes, fp, 0);
}
* with ones that only work for read.
*/
- ubc_setcred(vp, p);
+ ubc_setthreadcred(vp, p, current_thread());
docow = FALSE;
if ((flags & (MAP_ANON|MAP_SHARED)) == 0) {
docow = TRUE;
}
}
- ubc_setcred(vp, current_proc());
+ ubc_setthreadcred(vp, current_proc(), current_thread());
(void)ubc_map(vp, (PROT_READ | PROT_WRITE | PROT_EXEC));
(void)vnode_put(vp);
err = 0;
gid_t newgroups[NGROUPS] = { 0 };
int error;
kauth_cred_t my_cred, my_new_cred;
+ struct uthread *uthread = get_bsdthread_info(current_thread());
if ((error = suser(p->p_ucred, &p->p_acflag)))
return (error);
}
}
- /* get current credential and take a reference while we muck with it */
- for (;;) {
- my_cred = kauth_cred_proc_ref(p);
+ if ((uthread->uu_flag & UT_SETUID) != 0) {
+ /*
+ * If this thread is under an assumed identity, set the
+ * supplementary grouplist on the thread credential instead
+ * of the process one. If we were the only reference holder,
+ * the credential is updated in place, otherwise, our reference
+ * is dropped and we get back a different cred with a reference
+ * already held on it. Because this is per-thread, we don't
+ * need the referencing/locking/retry required for per-process.
+ *
+ * Hack: this opts into memberd to avoid needing to use a per
+ * thread credential initgroups() instead of setgroups() in
+ * AFP server to address <rdar://4561060>
+ */
+ my_cred = uthread->uu_ucred;
+ uthread->uu_ucred = kauth_cred_setgroups(my_cred, &newgroups[0], ngrp, my_cred->cr_gmuid);
+ } else {
- /*
- * set the credential with new info. If there is no change we get back
- * the same credential we passed in.
+ /*
+ * get current credential and take a reference while we muck
+ * with it
*/
- my_new_cred = kauth_cred_setgroups(p->p_ucred, &newgroups[0], ngrp, gmuid);
- if (my_cred != my_new_cred) {
- proc_lock(p);
- /* need to protect for a race where another thread also changed
- * the credential after we took our reference. If p_ucred has
- * changed then we should restart this again with the new cred.
+ for (;;) {
+ my_cred = kauth_cred_proc_ref(p);
+
+ /*
+ * set the credential with new info. If there is no
+ * change we get back the same credential we passed in.
*/
- if (p->p_ucred != my_cred) {
+ my_new_cred = kauth_cred_setgroups(my_cred, &newgroups[0], ngrp, gmuid);
+ if (my_cred != my_new_cred) {
+ proc_lock(p);
+ /*
+ * need to protect for a race where another
+ * thread also changed the credential after we
+ * took our reference. If p_ucred has
+ * changed then we should restart this again
+ * with the new cred.
+ */
+ if (p->p_ucred != my_cred) {
+ proc_unlock(p);
+ kauth_cred_rele(my_cred);
+ kauth_cred_rele(my_new_cred);
+ /* try again */
+ continue;
+ }
+ p->p_ucred = my_new_cred;
+ p->p_flag |= P_SUGID;
proc_unlock(p);
- kauth_cred_rele(my_cred);
- kauth_cred_rele(my_new_cred);
- /* try again */
- continue;
}
- p->p_ucred = my_new_cred;
- p->p_flag |= P_SUGID;
- proc_unlock(p);
+ /* drop our extra reference */
+ kauth_cred_rele(my_cred);
+ break;
}
- /* drop our extra reference */
- kauth_cred_rele(my_cred);
- break;
- }
- AUDIT_ARG(groupset, p->p_ucred->cr_groups, ngrp);
- set_security_token(p);
+ AUDIT_ARG(groupset, p->p_ucred->cr_groups, ngrp);
+ set_security_token(p);
+ }
return (0);
}
#include <sys/proc_internal.h>
#include <sys/kauth.h>
#include <sys/buf.h>
+#include <sys/user.h>
#include <mach/mach_types.h>
#include <mach/memory_object_types.h>
#include <kern/kern_types.h>
#include <kern/zalloc.h>
+#include <kern/thread.h>
#include <vm/vm_kern.h>
#include <vm/vm_protos.h> /* last */
return (NOCRED);
}
+int
+ubc_setthreadcred(struct vnode *vp, struct proc *p, thread_t thread)
+{
+ struct ubc_info *uip;
+ kauth_cred_t credp;
+ struct uthread *uthread = get_bsdthread_info(thread);
+
+ if (!UBCINFOEXISTS(vp))
+ return (1);
+
+ vnode_lock(vp);
+
+ uip = vp->v_ubcinfo;
+ credp = uip->ui_ucred;
+
+ if (credp == NOCRED) {
+ /* use per-thread cred, if assumed identity, else proc cred */
+ if (uthread == NULL || (uthread->uu_flag & UT_SETUID) == 0) {
+ uip->ui_ucred = kauth_cred_proc_ref(p);
+ } else {
+ uip->ui_ucred = uthread->uu_ucred;
+ kauth_cred_ref(uip->ui_ucred);
+ }
+ }
+ vnode_unlock(vp);
+
+ return (0);
+}
+
/*
* Set the credentials
* existing credentials are not changed
so->so_uid = head->so_uid;
so->so_usecount = 1;
+#ifdef __APPLE__
+ so->so_rcv.sb_flags |= SB_RECV; /* XXX */
+ so->so_rcv.sb_so = so->so_snd.sb_so = so;
+ TAILQ_INIT(&so->so_evlist);
+#endif
+
if (soreserve(so, head->so_snd.sb_hiwat, head->so_rcv.sb_hiwat)) {
sflt_termsock(so);
sodealloc(so);
head->so_incqlen++;
}
head->so_qlen++;
-#ifdef __APPLE__
- so->so_rcv.sb_flags |= SB_RECV; /* XXX */
- so->so_rcv.sb_so = so->so_snd.sb_so = so;
- TAILQ_INIT(&so->so_evlist);
+#ifdef __APPLE__
/* Attach socket filters for this protocol */
sflt_initsock(so);
#endif
goto release;
}
- if (control && (error = unp_internalize(control, p)))
- goto release;
+ if (control) {
+ socket_unlock(so, 0); /* release global lock to avoid deadlock (4436174) */
+ error = unp_internalize(control, p);
+ socket_lock(so, 0);
+ if (error)
+ goto release;
+ }
switch (so->so_type) {
case SOCK_DGRAM:
-<HEAD>\r
-<title>FTP Menu at ftp2.FreeBSD.ORG</title>\r
-</HEAD>\r
-<h1>FTP Menu</h1>\r
-<HR>\r
-<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/README">\r
-<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> README <br>\r
-<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfs_proto.h">\r
-<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfs_proto.h <br>\r
-<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfs_tree.c">\r
-<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfs_tree.c <br>\r
-<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfs_vfsops.c">\r
-<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfs_vfsops.c <br>\r
-<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfs_vnops.c">\r
-<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfs_vnops.c <br>\r
-<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfsdefs.h">\r
-<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfsdefs.h <br>\r
-<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/reproto.sh">\r
-<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> reproto.sh <br>\r
-<br><hr>\r
-<A HREF="http://-internal-/-http-gw-internal-/version.html">http-gw version 3.2 / 0</A>\r
- (17.254.0.77)\r
+<HEAD>
+<title>FTP Menu at ftp2.FreeBSD.ORG</title>
+</HEAD>
+<h1>FTP Menu</h1>
+<HR>
+<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/README">
+<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> README <br>
+<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfs_proto.h">
+<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfs_proto.h <br>
+<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfs_tree.c">
+<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfs_tree.c <br>
+<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfs_vfsops.c">
+<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfs_vfsops.c <br>
+<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfs_vnops.c">
+<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfs_vnops.c <br>
+<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/devfsdefs.h">
+<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> devfsdefs.h <br>
+<A HREF="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/sys/miscfs/devfs/reproto.sh">
+<IMG ALT="[TXT]" SRC="http://17.254.0.77:80/-http-gw-internal-/text.gif"></A> reproto.sh <br>
+<br><hr>
+<A HREF="http://-internal-/-http-gw-internal-/version.html">http-gw version 3.2 / 0</A>
+ (17.254.0.77)
return;
}
- /* Verify the sender is not broadcast or multicast */
- if ((ea->arp_sha[0] & 0x01) != 0) {
+ /* Verify the sender is not broadcast */
+ if (bcmp(ea->arp_sha, etherbroadcastaddr, ETHER_ADDR_LEN) == 0) {
mbuf_free(m);
return;
}
ifnet_head_lock_shared();
TAILQ_FOREACH(ifp, &ifnet, if_link)
{
- struct sockaddr_dl *ll_addr =
- (struct sockaddr_dl *)ifnet_addrs[ifp->if_index - 1]->ifa_addr;
+ struct ifaddr *ifa = ifnet_addrs[ifp->if_index - 1];
+ struct sockaddr_dl *ll_addr;
+
+ if (!ifa || !ifa->ifa_addr)
+ continue;
+
+ ll_addr = (struct sockaddr_dl *)ifa->ifa_addr;
+
if ((ifp->if_eflags & IFEF_DETACHING) == 0 &&
namelen == ll_addr->sdl_nlen &&
(strncmp(ll_addr->sdl_data, ifname, ll_addr->sdl_nlen) == 0))
if (cur_np == NULL) {
dlil_detach_protocol(np->nd_if, PF_NDRV);
}
+ } else {
+ /* Remove from the linked list of control blocks */
+ TAILQ_REMOVE(&ndrvl, np, nd_next);
}
FREE((caddr_t)np, M_PCB);
atalk_notify(gref, ESHUTDOWN);
}
}
- if (count_only || active_skts) {
+ if (count_only) {
splx(s);
return(active_skts);
/* XXX expensive to zero, see if we can remove it*/
mtag = m_tag_alloc(KERNEL_MODULE_TAG_ID, KERNEL_TAG_TYPE_DUMMYNET,
- sizeof(struct dn_pkt_tag), M_NOWAIT|M_ZERO);
+ sizeof(struct dn_pkt_tag), M_NOWAIT);
if ( mtag == NULL )
goto dropit ; /* cannot allocate packet header */
m_tag_prepend(m, mtag); /* attach to mbuf chain */
pkt = (struct dn_pkt_tag *)(mtag+1);
+ bzero(pkt, sizeof(struct dn_pkt_tag));
/* ok, i can handle the pkt now... */
/* build and enqueue packet + parameters */
pkt->rule = fwa->rule ;
ip->ip_len = ntohs(ip->ip_len);
ip->ip_off = ntohs(ip->ip_off);
}
+ args->m->m_flags |= M_SKIP_FIREWALL;
icmp_error(args->m, ICMP_UNREACH, code, 0L, 0);
} else if (offset == 0 && args->f_id.proto == IPPROTO_TCP) {
struct tcphdr *const tcp =
#if defined(NFAITH) && NFAITH > 0
#include "faith.h"
#include <net/if_types.h>
+#endif
+
+ /* XXX This one should go in sys/mbuf.h. It is used to avoid that
+ * a firewall-generated packet loops forever through the firewall.
+ */
+#ifndef M_SKIP_FIREWALL
+#define M_SKIP_FIREWALL 0x4000
#endif
/*
m = m_gethdr(M_DONTWAIT, MT_HEADER);
if (m == NULL)
goto freeit;
+
+ if (n->m_flags & M_SKIP_FIREWALL) {
+ /* set M_SKIP_FIREWALL to skip firewall check, since we're called from firewall */
+ m->m_flags |= M_SKIP_FIREWALL;
+ }
+
icmplen = min(oiplen + 8, oip->ip_len);
if (icmplen < sizeof(struct ip)) {
printf("icmp_error: bad length\n");
ifnet_head_lock_shared();
if (((ifp = m->m_pkthdr.rcvif))
&& ( ifp->if_index && (ifp->if_index <= if_index))) {
- sdp = (struct sockaddr_dl *)(ifnet_addrs
- [ifp->if_index - 1]->ifa_addr);
+ struct ifaddr *ifa = ifnet_addrs[ifp->if_index - 1];
+
+ if (!ifa || !ifa->ifa_addr)
+ goto makedummy;
+
+ sdp = (struct sockaddr_dl *)ifa->ifa_addr;
/*
* Change our mind and don't try copy.
*/
state.ro = NULL; /* update at ipsec6_output_tunnel() */
state.dst = NULL; /* update at ipsec6_output_tunnel() */
+ if (locked)
+ lck_mtx_unlock(ip6_mutex);
error = ipsec6_output_tunnel(&state, sp, 0);
+ if (locked) {
+ lck_mtx_unlock(sadb_mutex);
+ lck_mtx_lock(ip6_mutex);
+ lck_mtx_lock(sadb_mutex);
+ }
m = state.m;
key_freesp(sp);
bzero(&state, sizeof(state));
state.m = m;
+ lck_mtx_unlock(ip6_mutex);
+ lck_mtx_lock(sadb_mutex);
error = ipsec6_output_trans(&state, nexthdrp, mprev, sp, flags,
&needipsectun);
+ lck_mtx_unlock(sadb_mutex);
+ lck_mtx_lock(ip6_mutex);
m = state.m;
if (error) {
/* mbuf is already reclaimed in ipsec6_output_trans. */
state.m = m;
state.ro = (struct route *)ro;
state.dst = (struct sockaddr *)dst;
-
+ lck_mtx_unlock(ip6_mutex);
lck_mtx_lock(sadb_mutex);
error = ipsec6_output_tunnel(&state, sp, flags);
lck_mtx_unlock(sadb_mutex);
+ lck_mtx_lock(ip6_mutex);
m = state.m;
ro = (struct route_in6 *)state.ro;
dst = (struct sockaddr_in6 *)state.dst;
printf("ipsec6_output_trans: applyed SP\n");
kdebug_secpolicy(sp));
- lck_mtx_lock(sadb_mutex);
+ lck_mtx_assert(sadb_mutex, LCK_MTX_ASSERT_OWNED);
*tun = 0;
for (isr = sp->req; isr; isr = isr->next) {
if (isr->saidx.mode == IPSEC_MODE_TUNNEL) {
* XXX: should we directly notify sockets via
* pfctlinputs?
*/
- lck_mtx_unlock(ip6_mutex);
+ lck_mtx_unlock(sadb_mutex);
icmp6_error(state->m, ICMP6_DST_UNREACH,
ICMP6_DST_UNREACH_ADMIN, 0);
- lck_mtx_lock(ip6_mutex);
+ lck_mtx_lock(sadb_mutex);
state->m = NULL; /* icmp6_error freed the mbuf */
goto bad;
}
if (isr != NULL)
*tun = 1;
- lck_mtx_unlock(sadb_mutex);
return 0;
bad:
- lck_mtx_unlock(sadb_mutex);
m_freem(state->m);
state->m = NULL;
return error;
goto again;
}
- if ((waitfor == MNT_WAIT) && !LIST_EMPTY(&np->n_dirtyblkhd)) {
- goto again;
- }
- /* if we have no dirty blocks, we can clear the modified flag */
- if (LIST_EMPTY(&np->n_dirtyblkhd))
+ if (waitfor == MNT_WAIT) {
+ if (!LIST_EMPTY(&np->n_dirtyblkhd))
+ goto again;
+ /* if we have no dirty blocks, we can clear the modified flag */
np->n_flag &= ~NMODIFIED;
+ }
FSDBG(526, np->n_flag, np->n_error, 0, 0);
if (!ignore_writeerr && (np->n_flag & NWRITEERR)) {
int (*fo_write) __P((struct fileproc *fp, struct uio *uio,
struct ucred *cred, int flags,
struct proc *p));
-#define FOF_OFFSET 1
+#define FOF_OFFSET 0x00000001 /* offset supplied to vn_write */
+#define FOF_PCRED 0x00000002 /* cred from proc, not current thread */
int (*fo_ioctl) __P((struct fileproc *fp, u_long com,
caddr_t data, struct proc *p));
int (*fo_select) __P((struct fileproc *fp, int which,
struct ucred *ubc_getcred(struct vnode *);
int ubc_setcred(struct vnode *, struct proc *);
+struct thread;
+int ubc_setthreadcred(struct vnode *, struct proc *, struct thread *);
int ubc_sync_range(vnode_t, off_t, off_t, int);
errno_t ubc_msync(vnode_t, off_t, off_t, off_t *, int);
#if (BYTE_ORDER == LITTLE_ENDIAN)
u_char tmp;
- tmp = dp->d_namlen;
- dp->d_namlen = dp->d_type;
- dp->d_type = tmp;
+ /*
+ * We only need to swap the d_namlen and
+ * d_type fields for older versions of UFS,
+ * which we check by looking at the mnt_maxsymlinklen
+ * field.
+ */
+ if (vp->v_mount->mnt_maxsymlinklen <= 0) {
+ tmp = dp->d_namlen;
+ dp->d_namlen = dp->d_type;
+ dp->d_type = tmp;
+ }
#endif
+
xdp->d_reclen = EXT_DIRENT_LEN(dp->d_namlen);
if (xdp->d_reclen > uio_resid(uio)) {
break; /* user buffer is full */
xdp->d_ino = dp->d_ino;
xdp->d_namlen = dp->d_namlen;
xdp->d_type = dp->d_type;
+
bcopy(dp->d_name, xdp->d_name, dp->d_namlen + 1);
off += dp->d_reclen;
xdp->d_seekoff = off;
return (0);
}
+
+/*
+ * Get the combing class.
+ *
+ * Similar to CFUniCharGetCombiningPropertyForCharacter.
+ */
+static inline u_int8_t
+get_combining_class(u_int16_t character) {
+ const u_int8_t *bitmap = __CFUniCharCombiningPropertyBitmap;
+
+ u_int8_t value = bitmap[(character >> 8)];
+
+ if (value) {
+ bitmap = bitmap + (value * 256);
+ return bitmap[character % 256];
+ }
+ return (0);
+}
+
+
static int unicode_decompose(u_int16_t character, u_int16_t *convertedChars);
static u_int16_t unicode_combine(u_int16_t base, u_int16_t combining);
+static void priortysort(u_int16_t* characters, int count);
char utf_extrabytes[32] = {
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
u_int16_t* bufend;
unsigned int ucs_ch;
unsigned int byte;
+ int combcharcnt = 0;
int result = 0;
int decompose, precompose, swapbytes;
if (ucsp >= bufend)
goto toolong;
}
+ combcharcnt += count - 1;
continue;
}
} else if (precompose && (ucsp != bufstart)) {
if (ucs_ch == altslash)
ucs_ch = '/';
+ /*
+ * Make multiple combining character sequences canonical
+ */
+ if (unicode_combinable(ucs_ch)) {
+ ++combcharcnt; /* start tracking a run */
+ } else if (combcharcnt) {
+ if (combcharcnt > 1) {
+ priortysort(ucsp - combcharcnt, combcharcnt);
+ }
+ combcharcnt = 0; /* start over */
+ }
*ucsp++ = swapbytes ? NXSwapShort(ucs_ch) : ucs_ch;
}
+ /*
+ * Make a previous combining sequence canonical
+ */
+ if (combcharcnt > 1) {
+ priortysort(ucsp - combcharcnt, combcharcnt);
+ }
exit:
*ucslen = (u_int8_t*)ucsp - (u_int8_t*)bufstart;
return (value);
}
+
+/*
+ * priortysort - order combining chars into canonical order
+ *
+ * Similar to CFUniCharPrioritySort
+ */
+static void
+priortysort(u_int16_t* characters, int count)
+{
+ u_int32_t p1, p2;
+ u_int16_t *ch1, *ch2;
+ u_int16_t *end;
+ int changes = 1;
+
+ end = characters + count;
+ do {
+ changes = 0;
+ ch1 = characters;
+ ch2 = characters + 1;
+ p2 = get_combining_class(*ch1);
+ while (ch2 < end) {
+ p1 = p2;
+ p2 = get_combining_class(*ch2);
+ if (p1 > p2) {
+ u_int32_t tmp;
+
+ tmp = *ch1;
+ *ch1 = *ch2;
+ *ch2 = tmp;
+ changes = 1;
+ }
+ ++ch1;
+ ++ch2;
+ }
+ } while (changes);
+}
0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xFF, 0xFF,
0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
};
+
+static const u_int8_t
+__CFUniCharCombiningPropertyBitmap[] = {
+ 0x00, 0x00, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05,
+ 0x00, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C,
+ 0x0D, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x0E,
+ 0x0F, 0x10, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x11, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x12, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x13, 0x00, 0x00, 0x14, 0x00,
+ 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6,
+ 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6,
+ 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE8, 0xDC, 0xDC,
+ 0xDC, 0xDC, 0xE8, 0xD8, 0xDC, 0xDC, 0xDC, 0xDC,
+ 0xDC, 0xCA, 0xCA, 0xDC, 0xDC, 0xDC, 0xDC, 0xCA,
+ 0xCA, 0xDC, 0xDC, 0xDC, 0xDC, 0xDC, 0xDC, 0xDC,
+ 0xDC, 0xDC, 0xDC, 0xDC, 0x01, 0x01, 0x01, 0x01,
+ 0x01, 0xDC, 0xDC, 0xDC, 0xDC, 0xE6, 0xE6, 0xE6,
+ 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xF0, 0xE6, 0xDC,
+ 0xDC, 0xDC, 0xE6, 0xE6, 0xE6, 0xDC, 0xDC, 0x00,
+ 0xE6, 0xE6, 0xE6, 0xDC, 0xDC, 0xDC, 0xDC, 0xE6,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0xEA, 0xEA, 0xE9,
+ 0xEA, 0xEA, 0xE9, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6,
+ 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0xE6, 0xE6, 0xE6, 0xE6, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0xDC, 0xE6, 0xE6, 0xE6, 0xE6, 0xDC, 0xE6,
+ 0xE6, 0xE6, 0xDE, 0xDC, 0xE6, 0xE6, 0xE6, 0xE6,
+ 0xE6, 0xE6, 0x00, 0xDC, 0xDC, 0xDC, 0xDC, 0xDC,
+ 0xE6, 0xE6, 0xDC, 0xE6, 0xE6, 0xDE, 0xE4, 0xE6,
+ 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, 0x10, 0x11,
+ 0x12, 0x13, 0x00, 0x14, 0x15, 0x16, 0x00, 0x17,
+ 0x00, 0x18, 0x19, 0x00, 0xE6, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x1B, 0x1C, 0x1D, 0x1E, 0x1F,
+ 0x20, 0x21, 0x22, 0xE6, 0xE6, 0xDC, 0xDC, 0xE6,
+ 0xE6, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x23, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xE6, 0xE6,
+ 0xE6, 0xE6, 0xE6, 0xE6, 0xE6, 0x00, 0x00, 0xE6,
+ 0xE6, 0xE6, 0xE6, 0xDC, 0xE6, 0x00, 0x00, 0xE6,
+ 0xE6, 0x00, 0xDC, 0xE6, 0xE6, 0xDC, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x24, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0xE6, 0xDC, 0xE6, 0xE6, 0xDC, 0xE6, 0xE6, 0xDC,
+ 0xDC, 0xDC, 0xE6, 0xDC, 0xDC, 0xE6, 0xDC, 0xE6,
+ 0xE6, 0xE6, 0xDC, 0xE6, 0xDC, 0xE6, 0xDC, 0xE6,
+ 0xDC, 0xE6, 0xE6, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00,
+ 0x00, 0xE6, 0xDC, 0xE6, 0xE6, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x54, 0x5B, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x09, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x67, 0x67, 0x09, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x6B, 0x6B, 0x6B, 0x6B, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x76, 0x76, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x7A, 0x7A, 0x7A, 0x7A, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0xDC, 0xDC, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0xDC, 0x00, 0xDC,
+ 0x00, 0xD8, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x81, 0x82, 0x00, 0x84, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x82, 0x82, 0x82, 0x82, 0x00, 0x00,
+ 0x82, 0x00, 0xE6, 0xE6, 0x09, 0x00, 0xE6, 0xE6,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xDC, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x07,
+ 0x00, 0x09, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x09, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x09, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0xE6, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0xE4, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0xDE, 0xE6, 0xDC, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0xE6, 0xE6, 0x01, 0x01, 0xE6, 0xE6, 0xE6, 0xE6,
+ 0x01, 0x01, 0x01, 0xE6, 0xE6, 0x00, 0x00, 0x00,
+ 0x00, 0xE6, 0x00, 0x00, 0x00, 0x01, 0x01, 0xE6,
+ 0xDC, 0xE6, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0xDA, 0xE4, 0xE8, 0xDE, 0xE0, 0xE0,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x08, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x1A, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0xE6, 0xE6, 0xE6, 0xE6, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
+};
+
+
* Set the credentials on successful writes
*/
if ((error == 0) && (vp->v_tag == VT_NFS) && (UBCINFOEXISTS(vp))) {
- ubc_setcred(vp, p);
+ /*
+ * When called from aio subsystem, we only have the proc from
+ * which to get the credential, at this point, so use that
+ * instead. This means aio functions are incompatible with
+ * per-thread credentials (aio operations are proxied). We
+ * can't easily correct the aio vs. settid race in this case
+ * anyway, so we disallow it.
+ */
+ if ((flags & FOF_PCRED) == 0) {
+ ubc_setthreadcred(vp, p, current_thread());
+ } else {
+ ubc_setcred(vp, p);
+ }
}
(void)vnode_put(vp);
return (error);
/* Mark this vnode as being used for swapfile */
SET(vp->v_flag, VSWAP);
- ubc_setcred(vp, p);
+ ubc_setthreadcred(vp, p, current_thread());
/*
* take a long term reference on the vnode to keep
if (
(p != (struct proc *) 0)
&& (p1 != (struct proc *) 0)
- && (((kauth_cred_getuid(p->p_ucred) == kauth_cred_getuid(kauth_cred_get())) &&
- ((p->p_ucred->cr_ruid == kauth_cred_get()->cr_ruid)))
- || !(suser(kauth_cred_get(), 0)))
+ && (
+ (p1 == p)
+ || !(suser(kauth_cred_get(), 0))
+ || ((kauth_cred_getuid(p->p_ucred) == kauth_cred_getuid(kauth_cred_get()))
+ && (p->p_ucred->cr_ruid == kauth_cred_get()->cr_ruid)
+ && ((p->p_flag & P_SUGID) == 0))
+ )
&& (p->p_stat != SZOMB)
) {
if (p->task != TASK_NULL) {
_ubc_range_op
_ubc_setcred
_ubc_setsize
+_ubc_setthreadcred
_ubc_sync_range
_ubc_upl_abort
_ubc_upl_abort_range
-8.6.0
+8.7.0
# The first line of this file contains the master version number for the kernel.
# All other instances of the kernel version in xnu are derived from this file.
* Revision 1.3 2002/06/16 20:36:02 lindak
* Merged PR-2957314 into Jaguar (siegmund: netboot kernel code needs to set
* com.apple.AppleDiskImageController.load to boolean Yes)
- *
+ *
* Revision 1.2.40.2 2002/06/15 03:50:38 dieter
* - corrected com.apple.AppleDiskImageController.load string
*
* Changes from Josh(networking), Rick(IOKit), Jim & David(osfmk), Umesh, Dan & Ramesh(BSD)
* Submitted by: Ramesh
* Reviewed by: Vincent
- *
+ *
* Revision 1.2.12.1 2002/05/21 23:08:14 aramesh
* Kernel API Cleanup
* Bug #: 2853781
static __inline__ int _OSRosettaCheck(void)
{
- int isCrossEndian = 0;
+ int isCrossEndian;
+ __asm__ ( "b 0f\n"
+ " .long 0x14400004\n"
+ " li %0,1\n"
+ "0:"
+ : "=r" (isCrossEndian) : "0" (0)
+ );
return isCrossEndian;
}
-<h2>do_mach_notify_port_deleted</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Handle the current instance of a port-deleted notification.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t do_mach_notify_port_deleted</strong>
\r <strong>(notify_port_t</strong> <var>notify</var>,
\r <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong>
\r\r\r<strong>kern_return_t do_seqnos_mach_notify_port_deleted</strong>
\r <strong>(notify_port_t</strong> <var>notify</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>notify</var>
\r<dd>
\r[in notify (receive) right]
\rThe port to which the notification was sent.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the
\rnotification port.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\rThe invalid name.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>do_mach_notify_port_deleted</strong> function is called by
\r<strong>notify_server</strong> as the
\rresult of a kernel message indicating that a port name is no
\rlonger usable (that is,
\rit no longer names a valid right), typically as a result of the right so named
\rbeing consumed or moved. In contrast, a dead-name notification
\rindicates that the
\rport name is now dead as the result of the associated receive
\rright having died.
\r<var>notify</var> is the port named via <strong>mach_port_request_notification</strong>
\ror <strong>mach_msg</strong>.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="notify_server.html"><strong>notify_server</strong></a>,
\r<a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>,
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>,
\r<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>,
\r<a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name</strong></a>,
\r<a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders</strong></a>,
\r<a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once</strong></a>.
\r\ No newline at end of file
+<h2>do_mach_notify_port_deleted</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Handle the current instance of a port-deleted notification.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t do_mach_notify_port_deleted</strong>
+ <strong>(notify_port_t</strong> <var>notify</var>,
+ <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong>
+
+
+<strong>kern_return_t do_seqnos_mach_notify_port_deleted</strong>
+ <strong>(notify_port_t</strong> <var>notify</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>notify</var>
+<dd>
+[in notify (receive) right]
+The port to which the notification was sent.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the
+notification port.
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+The invalid name.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>do_mach_notify_port_deleted</strong> function is called by
+<strong>notify_server</strong> as the
+result of a kernel message indicating that a port name is no
+longer usable (that is,
+it no longer names a valid right), typically as a result of the right so named
+being consumed or moved. In contrast, a dead-name notification
+indicates that the
+port name is now dead as the result of the associated receive
+right having died.
+<var>notify</var> is the port named via <strong>mach_port_request_notification</strong>
+or <strong>mach_msg</strong>.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="notify_server.html"><strong>notify_server</strong></a>,
+<a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>,
+<a href="mach_msg.html"><strong>mach_msg</strong></a>,
+<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>,
+<a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name</strong></a>,
+<a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders</strong></a>,
+<a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once</strong></a>.
-<h2>do_mach_notify_port_destroyed</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Handle the current instance of a port-destroyed notification.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t do_mach_notify_port_destroyed</strong>
\r <strong>(notify_port_t</strong> <var>notify</var>,
\r <strong>mach_port_receive_t</strong> <var>name</var><strong>);</strong>
\r\r\r<strong>kern_return_t do_seqnos_mach_notify_port_destroyed</strong>
\r <strong>(mach_port_t</strong> <var>notify</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>mach_port_receive_t</strong> <var>name</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>notify</var>
\r<dd>
\r[in notify (receive) right]
\rThe port to which the notification was sent.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the
\rnotification port.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\rThe invalid name.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>do_mach_notify_port_destroyed</strong> function is called by
\r<strong>notify_server</strong> as the
\rresult of a kernel message indicating that a receive right would have
\rbeen destroyed. <var>notify</var> is the port named via
\r<strong>mach_port_request_notification</strong> or <strong>mach_msg</strong>.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="notify_server.html"><strong>notify_server</strong></a>,
\r<a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>,
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>,
\r<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>,
\r<a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name</strong></a>,
\r<a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders</strong></a>,
\r<a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once</strong></a>.
\r\ No newline at end of file
+<h2>do_mach_notify_port_destroyed</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Handle the current instance of a port-destroyed notification.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t do_mach_notify_port_destroyed</strong>
+ <strong>(notify_port_t</strong> <var>notify</var>,
+ <strong>mach_port_receive_t</strong> <var>name</var><strong>);</strong>
+
+
+<strong>kern_return_t do_seqnos_mach_notify_port_destroyed</strong>
+ <strong>(mach_port_t</strong> <var>notify</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>mach_port_receive_t</strong> <var>name</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>notify</var>
+<dd>
+[in notify (receive) right]
+The port to which the notification was sent.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the
+notification port.
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+The invalid name.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>do_mach_notify_port_destroyed</strong> function is called by
+<strong>notify_server</strong> as the
+result of a kernel message indicating that a receive right would have
+been destroyed. <var>notify</var> is the port named via
+<strong>mach_port_request_notification</strong> or <strong>mach_msg</strong>.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="notify_server.html"><strong>notify_server</strong></a>,
+<a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>,
+<a href="mach_msg.html"><strong>mach_msg</strong></a>,
+<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>,
+<a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name</strong></a>,
+<a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders</strong></a>,
+<a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once</strong></a>.
-<h2>default_pager_backing_store_create</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Create a backing storage object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include< mach/default_pager_object.h></strong>
\r\r<strong>kern_return_t default_pager_backing_store_create</strong>
\r <strong>(mach_port_t</strong> <var>pager</var>,
\r <strong>int</strong> <var>priority</var>,
\r <strong>int</strong> <var>clsize</var>,
\r <strong>mach_port_t</strong> <var>backing_store</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>pager</var>
\r<dd>
\r[in default pager (receive) right] The default pager service port.
\r<p>
\r<dt> <var>priority</var>
\r<dd>
\r[in scalar] The scheduling priority for the backing store service
\rthread(s).
\r<p>
\r<dt> <var>clsize</var>
\r<dd>
\r[in scalar] The preferred cluster size (in bytes) for the backing
\rstore object.
\r<p>
\r<dt> <var>backing_store</var>
\r<dd>
\r[out backing store (receive) right] The port used to manipulate the
\rcreated backing store.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>default_pager_backing_store_create</strong> function is called to create a
\rnew backing storage object. The kernel does not make this call itself
\r(which is why it can be a synchronous call); this request is only
\rissued by tasks (privileged) holding the default pager service port.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_FAILURE</strong>
\r<dd>
\rThe default pager does not support this operation.
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe pager port does not represent a valid default pager.
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe operation was successful.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="DP_backing_store_delete.html"><strong>default_pager_backing_store_delete</strong></a>,
\r<a href="DP_backing_store_info.html"><strong>default_pager_backing_store_info</strong></a>.
\r\ No newline at end of file
+<h2>default_pager_backing_store_create</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Create a backing storage object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include< mach/default_pager_object.h></strong>
+
+<strong>kern_return_t default_pager_backing_store_create</strong>
+ <strong>(mach_port_t</strong> <var>pager</var>,
+ <strong>int</strong> <var>priority</var>,
+ <strong>int</strong> <var>clsize</var>,
+ <strong>mach_port_t</strong> <var>backing_store</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>pager</var>
+<dd>
+[in default pager (receive) right] The default pager service port.
+<p>
+<dt> <var>priority</var>
+<dd>
+[in scalar] The scheduling priority for the backing store service
+thread(s).
+<p>
+<dt> <var>clsize</var>
+<dd>
+[in scalar] The preferred cluster size (in bytes) for the backing
+store object.
+<p>
+<dt> <var>backing_store</var>
+<dd>
+[out backing store (receive) right] The port used to manipulate the
+created backing store.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>default_pager_backing_store_create</strong> function is called to create a
+new backing storage object. The kernel does not make this call itself
+(which is why it can be a synchronous call); this request is only
+issued by tasks (privileged) holding the default pager service port.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_FAILURE</strong>
+<dd>
+The default pager does not support this operation.
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The pager port does not represent a valid default pager.
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The operation was successful.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="DP_backing_store_delete.html"><strong>default_pager_backing_store_delete</strong></a>,
+<a href="DP_backing_store_info.html"><strong>default_pager_backing_store_info</strong></a>.
-<h2>default_pager_backing_store_delete</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Delete a backing storage object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include< mach/default_pager_object.h></strong>
\r\r<strong>kern_return_t default_pager_backing_store_delete</strong>
\r <strong>(mach_port_t</strong> <var>backing_store</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>backing_store</var>
\r<dd>
\r[in backing store (receive) right] The backing store port created by
\rdefault_pager_backing_store_create.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>default_pager_backing_store_delete</strong> function is called to destroy a
\rbacking storage object created by
\r<strong>default_pager_backing_store_create</strong>. The kernel does not make this call
\ritself (which is why it can be a synchronous call); this request is
\ronly issued by tasks holding the backing store port, created with
\r<strong>default_pager_backing_store_create</strong>, for a default memory manager.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_FAILURE</strong>
\r<dd>
\rThe default pager does not support this operation.
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe backing_store port does not represent a valid backing store or the
\rspecified segment overlaps an existing partition.
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe operation was successful.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="DP_backing_store_create.html"><strong>default_pager_backing_store_create</strong></a>,
\r<a href="DP_backing_store_info.html"><strong>default_pager_backing_store_info</strong></a>.
\r\ No newline at end of file
+<h2>default_pager_backing_store_delete</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Delete a backing storage object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include< mach/default_pager_object.h></strong>
+
+<strong>kern_return_t default_pager_backing_store_delete</strong>
+ <strong>(mach_port_t</strong> <var>backing_store</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>backing_store</var>
+<dd>
+[in backing store (receive) right] The backing store port created by
+default_pager_backing_store_create.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>default_pager_backing_store_delete</strong> function is called to destroy a
+backing storage object created by
+<strong>default_pager_backing_store_create</strong>. The kernel does not make this call
+itself (which is why it can be a synchronous call); this request is
+only issued by tasks holding the backing store port, created with
+<strong>default_pager_backing_store_create</strong>, for a default memory manager.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_FAILURE</strong>
+<dd>
+The default pager does not support this operation.
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The backing_store port does not represent a valid backing store or the
+specified segment overlaps an existing partition.
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The operation was successful.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="DP_backing_store_create.html"><strong>default_pager_backing_store_create</strong></a>,
+<a href="DP_backing_store_info.html"><strong>default_pager_backing_store_info</strong></a>.
-<h2>default_pager_backing_store_info</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Return information about a backing storage object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include< default_pager/mach/default_pager_types.h></strong>
\r\r<strong>kern_return_t default_pager_backing_store_info</strong>
\r <strong>(mach_port_t</strong> <var>backing_store</var>,
\r <strong>backing_store_flavor_t</strong> <var>flavor</var>,
\r <strong>backing_store_info_t</strong> <var>info</var>,
\r <strong>mach_msg_type_number_t</strong> <var>size</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>backing_store</var>
\r<dd>
\r[in backing store (receive) right] The backing store port for which
\rinformation is desired.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar] The type of information to be returned. Valid values are:
\r<p>
\r<dt> <var>BACKING_STORE_BASIC_INFO</var>
\r<dd>
\rStatistical and space used/available information. It includes
\rthe priority and cluster size that was provided in the
\rdefault_pager_backing_store_create call.
\r<p>
\r<dt> <var>info</var>
\r<dd>
\r[pointer to in structure] The data structure that will be filled in with the
\rinformation provided for the requested flavor.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[pointer to in/out scalar] On input, the maximum size of the info data
\rstructure; on output, the actual size of the returned data.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>default_pager_backing_store_info</strong> function is called to obtain
\rinformation about a backing storage object created by
\r<strong>default_pager_backing_store_create</strong>. The kernel does not make this call
\ritself (which is why it can be a synchronous call); this request is
\ronly issued by tasks holding the backing store port, created with
\r<strong>default_pager_backing_store_create</strong>, for a default memory manager.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_FAILURE</strong>
\r<dd>
\rThe default pager does not support this operation.
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe backing_store port does not represent a valid backing store, flavor
\ris not valid, or size is not the size for the requested flavor.
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe operation was successful.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="DP_backing_store_create.html"><strong>default_pager_backing_store_create</strong></a>,
\r<a href="DP_backing_store_delete.html"><strong>default_pager_backing_store_delete</strong></a>.
\r<p>
\rData Structures:
\rbacking_store_basic_info.
\r\ No newline at end of file
+<h2>default_pager_backing_store_info</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Return information about a backing storage object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include< default_pager/mach/default_pager_types.h></strong>
+
+<strong>kern_return_t default_pager_backing_store_info</strong>
+ <strong>(mach_port_t</strong> <var>backing_store</var>,
+ <strong>backing_store_flavor_t</strong> <var>flavor</var>,
+ <strong>backing_store_info_t</strong> <var>info</var>,
+ <strong>mach_msg_type_number_t</strong> <var>size</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>backing_store</var>
+<dd>
+[in backing store (receive) right] The backing store port for which
+information is desired.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar] The type of information to be returned. Valid values are:
+<p>
+<dt> <var>BACKING_STORE_BASIC_INFO</var>
+<dd>
+Statistical and space used/available information. It includes
+the priority and cluster size that was provided in the
+default_pager_backing_store_create call.
+<p>
+<dt> <var>info</var>
+<dd>
+[pointer to in structure] The data structure that will be filled in with the
+information provided for the requested flavor.
+<p>
+<dt> <var>size</var>
+<dd>
+[pointer to in/out scalar] On input, the maximum size of the info data
+structure; on output, the actual size of the returned data.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>default_pager_backing_store_info</strong> function is called to obtain
+information about a backing storage object created by
+<strong>default_pager_backing_store_create</strong>. The kernel does not make this call
+itself (which is why it can be a synchronous call); this request is
+only issued by tasks holding the backing store port, created with
+<strong>default_pager_backing_store_create</strong>, for a default memory manager.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_FAILURE</strong>
+<dd>
+The default pager does not support this operation.
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The backing_store port does not represent a valid backing store, flavor
+is not valid, or size is not the size for the requested flavor.
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The operation was successful.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="DP_backing_store_create.html"><strong>default_pager_backing_store_create</strong></a>,
+<a href="DP_backing_store_delete.html"><strong>default_pager_backing_store_delete</strong></a>.
+<p>
+Data Structures:
+backing_store_basic_info.
-<h2>default_pager_object_create</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Initialize a non-persistent memory object suitable for sharing between tasks.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t default_pager_object_create</strong>
\r <strong>(mach_port_t</strong> <var>pager</var>,
\r <strong>memory_object_t</strong> <var>*memory_object</var>,
\r <strong>vm_size_t</strong> <var>object_size</var><strong>);</strong>
\r\r\r<strong>kern_return_t seqnos_default_pager_object_create</strong>
\r <strong>(mach_port_t</strong> <var>pager</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>memory_object_t</strong> <var>*memory_object</var>,
\r <strong>vm_size_t</strong> <var>object_size</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>pager</var>
\r<dd>
\r[in default-pager (receive) right]
\rThe default memory manager service
\rport.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the <var>pager</var>
\rport.
\r<p>
\r<dt> <var>memory_object</var>
\r<dd>
\r[out memory-object send right]
\rA memory object port (with full access) for the memory object.
\r<p>
\r<dt> <var>object_size</var>
\r<dd>
\r[in scalar]
\rThe maximum size for the memory object.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>default_pager_object_create</strong> function is called as
\rthe result of a message
\rrequesting that the default memory manager create and return a (shared) memory
\robject which is suitable for use with <strong>vm_map</strong>. This memory object has
\rthe same properties as does a memory object provided by
\r<strong>vm_allocate</strong>: its initial
\rcontents are zero and the backing contents are temporary in that they do not
\rpersist after the memory object is destroyed. The memory object
\ris suitable for use
\ras non-permanent shared memory. The kernel does not make this call itself
\r(which is why it can be a synchronous call); this request is only issued by
\r(privileged) tasks holding the default memory manager port.
\rThis call should be
\rcontrasted with the kernel's <strong>memory_object_create</strong> message, in which
\rthe memory cache object is already created and the identity of the abstract
\rmemory object is made known to the default manager.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_map.html"><strong>vm_map</strong></a>,
\r<a href="HD_memory_manager.html"><strong>host_default_memory_manager</strong></a>,
\r<a href="memory_object_create.html"><strong>memory_object_create</strong></a>,
\r<a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>,
\r<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>.
\r\ No newline at end of file
+<h2>default_pager_object_create</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Initialize a non-persistent memory object suitable for sharing between tasks.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t default_pager_object_create</strong>
+ <strong>(mach_port_t</strong> <var>pager</var>,
+ <strong>memory_object_t</strong> <var>*memory_object</var>,
+ <strong>vm_size_t</strong> <var>object_size</var><strong>);</strong>
+
+
+<strong>kern_return_t seqnos_default_pager_object_create</strong>
+ <strong>(mach_port_t</strong> <var>pager</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>memory_object_t</strong> <var>*memory_object</var>,
+ <strong>vm_size_t</strong> <var>object_size</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>pager</var>
+<dd>
+[in default-pager (receive) right]
+The default memory manager service
+port.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the <var>pager</var>
+port.
+<p>
+<dt> <var>memory_object</var>
+<dd>
+[out memory-object send right]
+A memory object port (with full access) for the memory object.
+<p>
+<dt> <var>object_size</var>
+<dd>
+[in scalar]
+The maximum size for the memory object.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>default_pager_object_create</strong> function is called as
+the result of a message
+requesting that the default memory manager create and return a (shared) memory
+object which is suitable for use with <strong>vm_map</strong>. This memory object has
+the same properties as does a memory object provided by
+<strong>vm_allocate</strong>: its initial
+contents are zero and the backing contents are temporary in that they do not
+persist after the memory object is destroyed. The memory object
+is suitable for use
+as non-permanent shared memory. The kernel does not make this call itself
+(which is why it can be a synchronous call); this request is only issued by
+(privileged) tasks holding the default memory manager port.
+This call should be
+contrasted with the kernel's <strong>memory_object_create</strong> message, in which
+the memory cache object is already created and the identity of the abstract
+memory object is made known to the default manager.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="vm_map.html"><strong>vm_map</strong></a>,
+<a href="HD_memory_manager.html"><strong>host_default_memory_manager</strong></a>,
+<a href="memory_object_create.html"><strong>memory_object_create</strong></a>,
+<a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>,
+<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>.
-<h2>device_read_overwrite_async</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> - Read a sequence of bytes from a device object into the caller's
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t device_read_overwrite_async</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>mach_port_t</strong> <var>queue</var>,
\r <strong>mach_port_t</strong> <var>request_id</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>recnum_t</strong> <var>recnum</var>,
\r <strong>io_buf_len_t</strong> <var>bytes_wanted</var>,
\r <strong>io_buf_ptr_t</strong> <var>buffer</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right] A device port to the device to be read.
\r<p>
\r<dt> <var>queue</var>
\r<dd>
\r[in io_done queue send right] The port returned from the
\rio_done_queue_create call.
\r<p>
\r<dt> <var>request_id</var>
\r<dd>
\r[in send right] An unique request identifier that will be passed back as
\rpart of the io_done_result structure.
\r<p>
\r<dt> <var>mode</var>
\r<dd>
\r[in scalar] I/O mode value. Meaningful options are:
\r<p>
\r <dl>
\r<dt> <strong>D_NOWAIT</strong>
\r<dd>
\rDo not wait if data is unavailable.
\r<p>
\r </dl>
\r<dt> <var>recnum</var>
\r<dd>
\r[in scalar] Record number to be read.
\r<p>
\r<dt> <var>bytes_wanted</var>
\r<dd>
\r[in scalar] Size of data transfer.
\r<p>
\r<dt> <var>buffer</var>
\r<dd>
\r[pointer to in array of bytes] Data buffer to be overwritten.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_read_overwrite</strong> system trap enqueues a read operation for a
\rsequence of bytes from a device object to be placed directly into
\rthe caller's address space. The meaning of recnum as well as the
\rspecific operation performed is device dependent.
\r<h3>RETURN VALUES</h3>
\r<p>
\r<strong>device_read_overwrite_async</strong> returns only invalid parameter errors.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_read_async.html"><strong>device_read_async</strong></a>,
\r<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>,
\r<a href="device_write_async.html"><strong>device_write_async</strong></a>,
\r<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>,
\r<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>.
\r\ No newline at end of file
+<h2>device_read_overwrite_async</h2>
+<hr>
+<p>
+<strong>System Trap</strong> - Read a sequence of bytes from a device object into the caller's
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t device_read_overwrite_async</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>mach_port_t</strong> <var>queue</var>,
+ <strong>mach_port_t</strong> <var>request_id</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>recnum_t</strong> <var>recnum</var>,
+ <strong>io_buf_len_t</strong> <var>bytes_wanted</var>,
+ <strong>io_buf_ptr_t</strong> <var>buffer</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right] A device port to the device to be read.
+<p>
+<dt> <var>queue</var>
+<dd>
+[in io_done queue send right] The port returned from the
+io_done_queue_create call.
+<p>
+<dt> <var>request_id</var>
+<dd>
+[in send right] An unique request identifier that will be passed back as
+part of the io_done_result structure.
+<p>
+<dt> <var>mode</var>
+<dd>
+[in scalar] I/O mode value. Meaningful options are:
+<p>
+ <dl>
+<dt> <strong>D_NOWAIT</strong>
+<dd>
+Do not wait if data is unavailable.
+<p>
+ </dl>
+<dt> <var>recnum</var>
+<dd>
+[in scalar] Record number to be read.
+<p>
+<dt> <var>bytes_wanted</var>
+<dd>
+[in scalar] Size of data transfer.
+<p>
+<dt> <var>buffer</var>
+<dd>
+[pointer to in array of bytes] Data buffer to be overwritten.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_read_overwrite</strong> system trap enqueues a read operation for a
+sequence of bytes from a device object to be placed directly into
+the caller's address space. The meaning of recnum as well as the
+specific operation performed is device dependent.
+<h3>RETURN VALUES</h3>
+<p>
+<strong>device_read_overwrite_async</strong> returns only invalid parameter errors.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_read_async.html"><strong>device_read_async</strong></a>,
+<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>,
+<a href="device_write_async.html"><strong>device_write_async</strong></a>,
+<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>,
+<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>.
-<h2>host_default_memory_manager</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Establish the official connection between the kernel and its default pager task.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t host_default_memory_manager</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>mach_port_make_send_t</strong> <var>default_manager</var>,
\r <strong>vm_size_t</strong> <var>cluster_size</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host_priv</var>
\r<dd>
\r[in host-control send right]
\rThe control port naming the host for which
\rthe default memory manager is to be set.
\r<p>
\r<dt> <var>default_manager</var>
\r<dd>
\r[pointer to in/out default-pager send right]
\rA memory manager port to
\rthe new default memory manager. If this value is <strong>MACH_PORT_NULL</strong>,
\rthe old memory manager is not changed. The old memory
\rmanager port is returned in this variable.
\r<p>
\r<dt> <var>cluster_size</var>
\r<dd>
\r[in scalar]
\rThe preferred cluster size (in bytes) for temporary memory
\robjects.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_default_memory_manager</strong> function establishes the default
\rmemory manager for a host. The named manager will be the target for future
\r<strong>memory_object_create</strong> calls.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_create.html"><strong>memory_object_create</strong></a>,
\r<a href="vm_allocate.html"><strong>vm_allocate</strong></a>.
\r\ No newline at end of file
+<h2>host_default_memory_manager</h2>
+<hr>
+<p>
+<strong>Function</strong> - Establish the official connection between the kernel and its default pager task.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t host_default_memory_manager</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>mach_port_make_send_t</strong> <var>default_manager</var>,
+ <strong>vm_size_t</strong> <var>cluster_size</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host_priv</var>
+<dd>
+[in host-control send right]
+The control port naming the host for which
+the default memory manager is to be set.
+<p>
+<dt> <var>default_manager</var>
+<dd>
+[pointer to in/out default-pager send right]
+A memory manager port to
+the new default memory manager. If this value is <strong>MACH_PORT_NULL</strong>,
+the old memory manager is not changed. The old memory
+manager port is returned in this variable.
+<p>
+<dt> <var>cluster_size</var>
+<dd>
+[in scalar]
+The preferred cluster size (in bytes) for temporary memory
+objects.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_default_memory_manager</strong> function establishes the default
+memory manager for a host. The named manager will be the target for future
+<strong>memory_object_create</strong> calls.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_create.html"><strong>memory_object_create</strong></a>,
+<a href="vm_allocate.html"><strong>vm_allocate</strong></a>.
-<h2>memory_object_synchronize_completed</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Inform the kernel that synchronized data has been processed.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_synchronize_completed </strong>
\r <strong>(memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>vm_offset_t</strong> <var>length</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used by the memory manager for cache management requests.
\rThis port is provided by the kernel in a <strong>memory_object_init</strong> call.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar]
\rThe offset within the memory object, in bytes.
\r<p>
\r<dt> <var>length</var>
\r<dd>
\r[in scalar]
\rThe amount of data processed. The number must be an
\rintegral number of memory object pages.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>memory_object_synchronize_completed</strong> function informs the kernel
\rthat previously synchronized data (<strong>memory_object_synchronize</strong>)
\rhas been queued or placed on backing storage. This reply causes the issuing
\rclient to return from its <strong>vm_msync</strong> call. The offset and length
\rmust match that of the corresponding <strong>memory_object_synchronize</strong>
\rcall. There may be multiple synchronize requests
\rfor a given memory object outstanding but they will not overlap.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_data_return.html"><strong>memory_object_data_return</strong></a>,
\r<a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>,
\r<a href="vm_msync.html"><strong>vm_msync</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_synchronize_completed</h2>
+<hr>
+<p>
+<strong>Function</strong> - Inform the kernel that synchronized data has been processed.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_synchronize_completed </strong>
+ <strong>(memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>vm_offset_t</strong> <var>length</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used by the memory manager for cache management requests.
+This port is provided by the kernel in a <strong>memory_object_init</strong> call.
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar]
+The offset within the memory object, in bytes.
+<p>
+<dt> <var>length</var>
+<dd>
+[in scalar]
+The amount of data processed. The number must be an
+integral number of memory object pages.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>memory_object_synchronize_completed</strong> function informs the kernel
+that previously synchronized data (<strong>memory_object_synchronize</strong>)
+has been queued or placed on backing storage. This reply causes the issuing
+client to return from its <strong>vm_msync</strong> call. The offset and length
+must match that of the corresponding <strong>memory_object_synchronize</strong>
+call. There may be multiple synchronize requests
+for a given memory object outstanding but they will not overlap.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_data_return.html"><strong>memory_object_data_return</strong></a>,
+<a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>,
+<a href="vm_msync.html"><strong>vm_msync</strong></a>.
-<h2>memory_object_change_attributes</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Modify caller-specified subset of attributes representing target memory object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_change_attributes</strong>
\r <strong>(memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>memory_object_flavor_t</strong> <var>flavor</var>,
\r <strong>memory_object_info_t</strong> <var>attributes</var>,
\r <strong>attributes</strong> <var>attributes_count</var>,
\r <strong>mach_port_t</strong> <var>reply_to</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used by the memory manager for cache management requests.
\rThis port is provided by the kernel in a <strong>memory_object_init</strong>
\r or <strong>memory_object_create</strong> call.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of information to be changed. Valid values are:
\r<dl>
\r<p>
\r<dt> <strong>MEMORY_OBJECT_PERFORMANCE_INFO</strong>
\r<dd>
\rPerformance related attributes such as the cache indicator and
\rthe cluster size. <var>attributes</var> should specify a structure of type
\r<strong>memory_object_perf_info</strong>.
\r<p>
\r<dt> <strong>MEMORY_OBJECT_BEHAVIOR_INFO</strong>
\r<dd>
\rBehavior related attributes such as the copy strategy and sync
\rinvalidate flag. <var>attributes</var> should specify a structure of type
\r<strong>memory_object_behavior_info</strong>.
\r<p>
\r<dt> <strong>MEMORY_OBJECT_ATTRIBUTES_INFO</strong>
\r<dd>
\rBehavior and performance related attributes such as the copy strategy,
\rcache indicator, and cluster size. <var>attributes</var> should specify a structure of type
\r<strong>memory_object_attr_info</strong>.
\r</dl>
\r<p>
\r<dt> <var>attributes</var>
\r<dd>
\r[pointer to in structure]
\rNew attributes.
\r<p>
\r<dt> <var>attributes_count</var>
\r<dd>
\r[in scalar]
\rThe size of the buffer (in natural-sized units).
\r<p>
\r<dt> <var>reply_port</var>
\r<dd>
\r[in reply receive (to be converted to send) right]
\rA port to which a
\rreply (<strong>memory_object_change_completed</strong>) is to be sent indicating the
\rcompletion of the attribute change. Such a reply would be useful if the
\rcache attribute is turned off, since such a change, if the memory object
\ris no longer mapped, may result in the object being terminated.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>memory_object_change_attributes</strong> function sets various
\rattributes of the
\rspecified memory object.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="MO_change_completed.html"><strong>memory_object_change_completed</strong></a>,
\r<a href="MO_get_attributes.html"><strong>memory_object_get_attributes</strong></a>,
\r<a href="memory_object_create.html"><strong>memory_object_create</strong></a>.
\r<p>
\rData Structures:
\r<a href="memory_object_perf_info.html"><strong>memory_object_perf_info</strong></a>,
\r<a href="memory_object_attr_info.html"><strong>memory_object_attr_info</strong></a>.
\r\r\r\ No newline at end of file
+<h2>memory_object_change_attributes</h2>
+<hr>
+<p>
+<strong>Function</strong> - Modify caller-specified subset of attributes representing target memory object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_change_attributes</strong>
+ <strong>(memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>memory_object_flavor_t</strong> <var>flavor</var>,
+ <strong>memory_object_info_t</strong> <var>attributes</var>,
+ <strong>attributes</strong> <var>attributes_count</var>,
+ <strong>mach_port_t</strong> <var>reply_to</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used by the memory manager for cache management requests.
+This port is provided by the kernel in a <strong>memory_object_init</strong>
+ or <strong>memory_object_create</strong> call.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of information to be changed. Valid values are:
+<dl>
+<p>
+<dt> <strong>MEMORY_OBJECT_PERFORMANCE_INFO</strong>
+<dd>
+Performance related attributes such as the cache indicator and
+the cluster size. <var>attributes</var> should specify a structure of type
+<strong>memory_object_perf_info</strong>.
+<p>
+<dt> <strong>MEMORY_OBJECT_BEHAVIOR_INFO</strong>
+<dd>
+Behavior related attributes such as the copy strategy and sync
+invalidate flag. <var>attributes</var> should specify a structure of type
+<strong>memory_object_behavior_info</strong>.
+<p>
+<dt> <strong>MEMORY_OBJECT_ATTRIBUTES_INFO</strong>
+<dd>
+Behavior and performance related attributes such as the copy strategy,
+cache indicator, and cluster size. <var>attributes</var> should specify a structure of type
+<strong>memory_object_attr_info</strong>.
+</dl>
+<p>
+<dt> <var>attributes</var>
+<dd>
+[pointer to in structure]
+New attributes.
+<p>
+<dt> <var>attributes_count</var>
+<dd>
+[in scalar]
+The size of the buffer (in natural-sized units).
+<p>
+<dt> <var>reply_port</var>
+<dd>
+[in reply receive (to be converted to send) right]
+A port to which a
+reply (<strong>memory_object_change_completed</strong>) is to be sent indicating the
+completion of the attribute change. Such a reply would be useful if the
+cache attribute is turned off, since such a change, if the memory object
+is no longer mapped, may result in the object being terminated.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>memory_object_change_attributes</strong> function sets various
+attributes of the
+specified memory object.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="MO_change_completed.html"><strong>memory_object_change_completed</strong></a>,
+<a href="MO_get_attributes.html"><strong>memory_object_get_attributes</strong></a>,
+<a href="memory_object_create.html"><strong>memory_object_create</strong></a>.
+<p>
+Data Structures:
+<a href="memory_object_perf_info.html"><strong>memory_object_perf_info</strong></a>,
+<a href="memory_object_attr_info.html"><strong>memory_object_attr_info</strong></a>.
+
+
-<h2>memory_object_change_completed</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Notify memory manager that kernel has updated memory object attributes as requested.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_change_completed</strong>
\r <strong>(memory_object_t</strong> <var>reply_port</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>memory_object_flavor_t</strong> <var>flavor</var><strong>);</strong>
\r\r\r<strong>kern_return_t seqnos_memory_object_change_completed</strong>
\r <strong>(memory_object_t</strong> <var>reply_port</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>memory_object_flavor_t</strong> <var>flavor</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>reply_port</var>
\r<dd>
\r[in reply (receive) right]
\rThe port supplied in the corresponding
\r<strong>memory_object_change_attributes</strong> call.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the port
\rnamed in the <strong>memory_object_change_attributes</strong> call.
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used for a response by the memory manager. If the memory
\robject has been supplied to more than one kernel, this parameter
\ridentifies the kernel that is making the call.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe flavor of attributes changed by the corresponding
\r<strong>memory_object_change_attributes</strong> call.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>memory_object_change_completed</strong> function is called
\ras the result of a
\rkernel message confirming the kernel's action in response to a
\r<strong>memory_object_change_attributes</strong> call from the memory manager.
\r<p>
\rWhen the kernel completes the requested changes, it calls
\r<strong>memory_object_change_completed</strong> (asynchronously) using
\rthe port explicitly provided in
\rthe <strong>memory_object_change_attributes</strong> call.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="MO_change_attributes.html"><strong>memory_object_change_attributes</strong></a>,
\r<a href="memory_object_server.html"><strong>memory_object_server</strong></a>,
\r<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_change_completed</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Notify memory manager that kernel has updated memory object attributes as requested.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_change_completed</strong>
+ <strong>(memory_object_t</strong> <var>reply_port</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>memory_object_flavor_t</strong> <var>flavor</var><strong>);</strong>
+
+
+<strong>kern_return_t seqnos_memory_object_change_completed</strong>
+ <strong>(memory_object_t</strong> <var>reply_port</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>memory_object_flavor_t</strong> <var>flavor</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>reply_port</var>
+<dd>
+[in reply (receive) right]
+The port supplied in the corresponding
+<strong>memory_object_change_attributes</strong> call.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the port
+named in the <strong>memory_object_change_attributes</strong> call.
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used for a response by the memory manager. If the memory
+object has been supplied to more than one kernel, this parameter
+identifies the kernel that is making the call.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The flavor of attributes changed by the corresponding
+<strong>memory_object_change_attributes</strong> call.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>memory_object_change_completed</strong> function is called
+as the result of a
+kernel message confirming the kernel's action in response to a
+<strong>memory_object_change_attributes</strong> call from the memory manager.
+<p>
+When the kernel completes the requested changes, it calls
+<strong>memory_object_change_completed</strong> (asynchronously) using
+the port explicitly provided in
+the <strong>memory_object_change_attributes</strong> call.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="MO_change_attributes.html"><strong>memory_object_change_attributes</strong></a>,
+<a href="memory_object_server.html"><strong>memory_object_server</strong></a>,
+<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>.
-<h2>memory_object_data_initialize</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Request that the default pager record initialization information for specified memory object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_data_initialize</strong>
\r <strong>(memory_object_t</strong> <var>memory_object</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>pointer_t</strong> <var>data</var><strong>);</strong>
\r\r\r<strong>kern_return_t seqnos_memory_object_data_initialize</strong>
\r <strong>(memory_object_t</strong> <var>memory_object</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>pointer_t</strong> <var>data</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>memory_object</var>
\r<dd>
\r[in abstract-memory-object (receive) right]
\rThe abstract memory
\robject port that represents the memory object data, as supplied by the
\rkernel in a <strong>memory_object_create</strong> call.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the abstract
\rmemory object port.
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used for a response by the memory manager. If the memory
\robject has been supplied to more than one kernel, this parameter
\ridentifies the kernel that is making the call.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar]
\rThe offset within the memory object.
\r<p>
\r<dt> <var>data</var>
\r<dd>
\r[in pointer to dynamic array of bytes]
\rThe data that has been modified
\rwhile cached in physical memory.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>memory_object_data_initialize</strong> function is called
\ras the result of a kernel
\rmessage providing the default memory manager with initial data for a
\rkernel-created memory object. If the memory manager already
\rhas supplied data (by a previous <strong>memory_object_data_initialize</strong> or
\r<strong>memory_object_data_return</strong>), it
\rshould ignore this call. Otherwise, the call behaves the same as the
\r<strong>memory_object_data_return</strong> call.
\r<p>
\rThe kernel makes this call only to the default memory manager and only on
\rtemporary memory objects that it has created with
\r<strong>memory_object_create</strong>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_create.html"><strong>memory_object_create</strong></a>,
\r<a href="memory_object_data_return.html"><strong>memory_object_data_return</strong></a>,
\r<a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>,
\r<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_data_initialize</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Request that the default pager record initialization information for specified memory object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_data_initialize</strong>
+ <strong>(memory_object_t</strong> <var>memory_object</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>pointer_t</strong> <var>data</var><strong>);</strong>
+
+
+<strong>kern_return_t seqnos_memory_object_data_initialize</strong>
+ <strong>(memory_object_t</strong> <var>memory_object</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>pointer_t</strong> <var>data</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>memory_object</var>
+<dd>
+[in abstract-memory-object (receive) right]
+The abstract memory
+object port that represents the memory object data, as supplied by the
+kernel in a <strong>memory_object_create</strong> call.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the abstract
+memory object port.
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used for a response by the memory manager. If the memory
+object has been supplied to more than one kernel, this parameter
+identifies the kernel that is making the call.
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar]
+The offset within the memory object.
+<p>
+<dt> <var>data</var>
+<dd>
+[in pointer to dynamic array of bytes]
+The data that has been modified
+while cached in physical memory.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>memory_object_data_initialize</strong> function is called
+as the result of a kernel
+message providing the default memory manager with initial data for a
+kernel-created memory object. If the memory manager already
+has supplied data (by a previous <strong>memory_object_data_initialize</strong> or
+<strong>memory_object_data_return</strong>), it
+should ignore this call. Otherwise, the call behaves the same as the
+<strong>memory_object_data_return</strong> call.
+<p>
+The kernel makes this call only to the default memory manager and only on
+temporary memory objects that it has created with
+<strong>memory_object_create</strong>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_create.html"><strong>memory_object_create</strong></a>,
+<a href="memory_object_data_return.html"><strong>memory_object_data_return</strong></a>,
+<a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>,
+<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>.
-<h2>memory_object_data_unavailable</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Instruct kernel to zero-fill pages as requested data does not exist.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_data_unavailable</strong>
\r <strong>(memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>vm_size_t</strong> <var>size</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used by the memory manager for cache management requests.
\rThis port is provided by the kernel in a <strong>memory_object_init</strong> or a
\r<strong>memory_object_create</strong> call.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar]
\rThe offset within the memory object, in bytes.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes of data (starting at <var>offset</var>). The number
\rmust convert to an integral number of memory object pages.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>memory_object_data_unavailable</strong> function indicates
\rthat the memory
\rmanager cannot provide the kernel with the data requested for
\rthe given region.
\rInstead, the kernel should provide the data for this region.
\r<p>
\rA memory manager can use this call in any of the following situations:
\r<ul>
\r<li>
\rWhen the object was created by the kernel
\r(via <strong>memory_object_create</strong>) and
\rthe kernel has not yet provided data for the region (via either
\r<strong>memory_object_data_initialize</strong> or <strong>memory_object_data_return</strong>).
\rIn this case, the
\robject is a temporary memory object; the memory manager is the default
\rmemory manager; and the kernel should provide zero-filled pages for the
\robject.
\r <p>
\r<li>
\rWhen the object is a normal user-created memory object. In this case, the
\rkernel should provide zero-filled pages for the region.
\r</ul>
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_create.html"><strong>memory_object_create</strong></a>,
\r<a href="memory_object_data_error.html"><strong>memory_object_data_error</strong></a>,
\r<a href="memory_object_data_request.html"><strong>memory_object_data_request</strong></a>,
\r<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_data_unavailable</h2>
+<hr>
+<p>
+<strong>Function</strong> - Instruct kernel to zero-fill pages as requested data does not exist.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_data_unavailable</strong>
+ <strong>(memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>vm_size_t</strong> <var>size</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used by the memory manager for cache management requests.
+This port is provided by the kernel in a <strong>memory_object_init</strong> or a
+<strong>memory_object_create</strong> call.
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar]
+The offset within the memory object, in bytes.
+<p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The number of bytes of data (starting at <var>offset</var>). The number
+must convert to an integral number of memory object pages.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>memory_object_data_unavailable</strong> function indicates
+that the memory
+manager cannot provide the kernel with the data requested for
+the given region.
+Instead, the kernel should provide the data for this region.
+<p>
+A memory manager can use this call in any of the following situations:
+<ul>
+<li>
+When the object was created by the kernel
+(via <strong>memory_object_create</strong>) and
+the kernel has not yet provided data for the region (via either
+<strong>memory_object_data_initialize</strong> or <strong>memory_object_data_return</strong>).
+In this case, the
+object is a temporary memory object; the memory manager is the default
+memory manager; and the kernel should provide zero-filled pages for the
+object.
+ <p>
+<li>
+When the object is a normal user-created memory object. In this case, the
+kernel should provide zero-filled pages for the region.
+</ul>
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_create.html"><strong>memory_object_create</strong></a>,
+<a href="memory_object_data_error.html"><strong>memory_object_data_error</strong></a>,
+<a href="memory_object_data_request.html"><strong>memory_object_data_request</strong></a>,
+<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>.
-<h2>memory_object_default_server</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Handle kernel operation request targeted for the default pager.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>boolean_t memory_object_default_server</strong>
\r <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
\r <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>in_msg</var>
\r<dd>
\r[pointer to in structure]
\rThe memory manager message received from
\rthe kernel.
\r<p>
\r<dt> <var>out_msg</var>
\r<dd>
\r[out structure]
\rA reply message. Note that no kernel messages to a
\rmemory manager expect a direct reply.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>memory_object_default_server</strong> function is the MIG generated server
\rhandling function to handle messages from the kernel targeted to the default
\rmemory manager. This server function only handles messages unique
\rto the default
\rmemory manager. Messages that are common to all memory managers are
\rhandled by <strong>memory_object_server</strong>.
\r<p>
\rA \*Vmemory manager\*O
\ris a server task that responds to specific messages from the
\rkernel in order to handle memory management functions for the kernel. The
\r<strong>memory_object_default_server</strong> function performs all necessary argument
\rhandling for a kernel message and calls one of the default memory manager
\rfunctions.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>TRUE</strong>
\r<dd>
\rThe message was handled and the appropriate function was called.
\r<p>
\r<dt> <strong>FALSE</strong>
\r<dd>
\rThe message did not apply to this memory management interface and
\rno other action was taken.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server<strong></a>,
\r<a href="memory_object_server.html"><strong>memory_object_server<strong></a>,
\r<a href="memory_object_create.html"><strong>memory_object_create<strong></a>,
\r<a href="MO_data_initialize.html"><strong>memory_object_data_initialize<strong></a>,
\r<a href="DP_object_create.html"><strong>default_pager_object_create<strong></a>,
\r<a href="default_pager_info.html"><strong>default_pager_info<strong></a>.
\r\r\ No newline at end of file
+<h2>memory_object_default_server</h2>
+<hr>
+<p>
+<strong>Function</strong> - Handle kernel operation request targeted for the default pager.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>boolean_t memory_object_default_server</strong>
+ <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
+ <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>in_msg</var>
+<dd>
+[pointer to in structure]
+The memory manager message received from
+the kernel.
+<p>
+<dt> <var>out_msg</var>
+<dd>
+[out structure]
+A reply message. Note that no kernel messages to a
+memory manager expect a direct reply.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>memory_object_default_server</strong> function is the MIG generated server
+handling function to handle messages from the kernel targeted to the default
+memory manager. This server function only handles messages unique
+to the default
+memory manager. Messages that are common to all memory managers are
+handled by <strong>memory_object_server</strong>.
+<p>
+A \*Vmemory manager\*O
+is a server task that responds to specific messages from the
+kernel in order to handle memory management functions for the kernel. The
+<strong>memory_object_default_server</strong> function performs all necessary argument
+handling for a kernel message and calls one of the default memory manager
+functions.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>TRUE</strong>
+<dd>
+The message was handled and the appropriate function was called.
+<p>
+<dt> <strong>FALSE</strong>
+<dd>
+The message did not apply to this memory management interface and
+no other action was taken.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server<strong></a>,
+<a href="memory_object_server.html"><strong>memory_object_server<strong></a>,
+<a href="memory_object_create.html"><strong>memory_object_create<strong></a>,
+<a href="MO_data_initialize.html"><strong>memory_object_data_initialize<strong></a>,
+<a href="DP_object_create.html"><strong>default_pager_object_create<strong></a>,
+<a href="default_pager_info.html"><strong>default_pager_info<strong></a>.
+
-<h2>memory_object_get_attributes</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return current attributes for a memory object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_get_attributes</strong>
\r <strong>(memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>memory_object_flavor_t</strong> <var>flavor</var>,
\r <strong>memory_object_info_t</strong> <var>attributes</var>,
\r <strong>mach_msg_type_number_t</strong> <var>attributes_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used by the memory manager for cache management requests.
\rThis port is provided by the kernel in a <strong>memory_object_notify</strong> call.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of information to be returned. Valid values are:
\r<dl>
\r<p>
\r<dt> <strong>MEMORY_OBJECT_PERFORMANCE_INFO</strong>
\r<dd>
\rPerformance related attributes such as the cache indicator and
\rthe cluster size. <var>attributes</var> should specify a structure of type
\r<strong>memory_object_perf_info</strong>.
\r<p>
\r<dt> <strong>MEMORY_OBJECT_BEHAVIOR_INFO</strong>
\r<dd>
\rBehavior related attributes such as the copy strategy and sync
\rinvalidate flag. <var>attributes</var> should specify a structure of type
\r<strong>memory_object_behavior_info</strong>.
\r <dt> <strong>MEMORY_OBJECT_ATTRIBUTES_INFO</strong>
\r<dd>
\rBehavior and performance related attributes such as the copy strategy,
\rcache indicator, and cluster size. <var>attributes</var> should specify a structure of type
\r<strong>memory_object_attr_info</strong>.
\r</dl>
\r<p>
\r<dt> <var>attributes</var>
\r<dd>
\r[out structure]
\rCurrent attributes.
\r<p>
\r<dt> <var>attributes_count</var>
\r<dd>
\r[in/out scalar]
\rOn input, the maximum size of the buffer; on output, the
\rsize returned (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>memory_object_get_attributes</strong> function retrieves
\rthe current attributes for
\rthe specified memory object.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="MO_change_attributes.html"><strong>memory_object_change_attributes</strong></a>.
\r<p>
\rData Structures:
\r<a href="memory_object_perf_info.html"><strong>memory_object_perf_info</strong></a>,
\r<a href="memory_object_attr_info.html"><strong>memory_object_attr_info</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_get_attributes</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return current attributes for a memory object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_get_attributes</strong>
+ <strong>(memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>memory_object_flavor_t</strong> <var>flavor</var>,
+ <strong>memory_object_info_t</strong> <var>attributes</var>,
+ <strong>mach_msg_type_number_t</strong> <var>attributes_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used by the memory manager for cache management requests.
+This port is provided by the kernel in a <strong>memory_object_notify</strong> call.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of information to be returned. Valid values are:
+<dl>
+<p>
+<dt> <strong>MEMORY_OBJECT_PERFORMANCE_INFO</strong>
+<dd>
+Performance related attributes such as the cache indicator and
+the cluster size. <var>attributes</var> should specify a structure of type
+<strong>memory_object_perf_info</strong>.
+<p>
+<dt> <strong>MEMORY_OBJECT_BEHAVIOR_INFO</strong>
+<dd>
+Behavior related attributes such as the copy strategy and sync
+invalidate flag. <var>attributes</var> should specify a structure of type
+<strong>memory_object_behavior_info</strong>.
+ <dt> <strong>MEMORY_OBJECT_ATTRIBUTES_INFO</strong>
+<dd>
+Behavior and performance related attributes such as the copy strategy,
+cache indicator, and cluster size. <var>attributes</var> should specify a structure of type
+<strong>memory_object_attr_info</strong>.
+</dl>
+<p>
+<dt> <var>attributes</var>
+<dd>
+[out structure]
+Current attributes.
+<p>
+<dt> <var>attributes_count</var>
+<dd>
+[in/out scalar]
+On input, the maximum size of the buffer; on output, the
+size returned (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>memory_object_get_attributes</strong> function retrieves
+the current attributes for
+the specified memory object.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="MO_change_attributes.html"><strong>memory_object_change_attributes</strong></a>.
+<p>
+Data Structures:
+<a href="memory_object_perf_info.html"><strong>memory_object_perf_info</strong></a>,
+<a href="memory_object_attr_info.html"><strong>memory_object_attr_info</strong></a>.
-<h2>memory_object_lock_completed</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Report to memory manager that a previous consistency control request has been handled.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_lock_completed</strong>
\r <strong>(memory_object_t</strong> <var>reply_port</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>vm_size_t</strong> <var>length</var><strong>);</strong>
\r\r\r<strong>kern_return_t seqnos_memory_object_lock_completed</strong>
\r <strong>(memory_object_t</strong> <var>reply_port</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>vm_size_t</strong> <var>length</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>reply_port</var>
\r<dd>
\r[in reply (receive) right]
\rThe port supplied in the corresponding
\r<strong>memory_object_lock_request</strong> call.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the port
\rnamed in the <strong>memory_object_lock_completed</strong> message.
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used for a response by the memory manager. If the memory
\robject has been supplied to more than one kernel, this parameter
\ridentifies the kernel that is making the call.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar]
\rThe offset within the memory object.
\r<p>
\r<dt> <var>length</var>
\r<dd>
\r[in scalar]
\rThe number of bytes to which the call refers, starting at
\r<var>offset</var>. The number converts to an integral number of memory object
\rpages.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>memory_object_lock_completed</strong> function is called as
\rthe result of a kernel
\rmessage confirming the kernel's action in response to a
\r<strong>memory_object_lock_request</strong> call from the memory manager.
\rThe memory manager can use the <strong>memory_object_lock_request</strong> call to:
\r<ul>
\r<li>
\rAlter access restrictions specified in the <strong>memory_object_data_supply</strong>
\rcall or a previous <strong>memory_object_lock_request</strong> call.
\r<p>
\r<li>
\rWrite back modifications made in memory.
\r<p>
\r<li>
\rInvalidate its cached data.
\r</ul>
\r<p>
\rWhen the kernel completes the requested actions, it calls
\r<strong>memory_object_lock_completed</strong> (asynchronously) using
\rthe port explicitly provided in the
\r<strong>memory_object_lock_request</strong> call. Because the memory manager cannot
\rknow which pages have been modified, or even which pages remain in the
\rcache, it cannot know how many pages will be written back in response to a
\r<strong>memory_object_lock_request</strong> call. Receiving the
\r<strong>memory_object_lock_completed</strong> call is the only sure
\rmeans of detecting completion. The completion call
\rincludes the offset and length values from the consistency request
\rto distinguish
\rit from other consistency requests.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>,
\r<a href="memory_object_server.html"><strong>memory_object_server</strong></a>,
\r<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_lock_completed</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Report to memory manager that a previous consistency control request has been handled.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_lock_completed</strong>
+ <strong>(memory_object_t</strong> <var>reply_port</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>vm_size_t</strong> <var>length</var><strong>);</strong>
+
+
+<strong>kern_return_t seqnos_memory_object_lock_completed</strong>
+ <strong>(memory_object_t</strong> <var>reply_port</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>vm_size_t</strong> <var>length</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>reply_port</var>
+<dd>
+[in reply (receive) right]
+The port supplied in the corresponding
+<strong>memory_object_lock_request</strong> call.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the port
+named in the <strong>memory_object_lock_completed</strong> message.
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used for a response by the memory manager. If the memory
+object has been supplied to more than one kernel, this parameter
+identifies the kernel that is making the call.
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar]
+The offset within the memory object.
+<p>
+<dt> <var>length</var>
+<dd>
+[in scalar]
+The number of bytes to which the call refers, starting at
+<var>offset</var>. The number converts to an integral number of memory object
+pages.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>memory_object_lock_completed</strong> function is called as
+the result of a kernel
+message confirming the kernel's action in response to a
+<strong>memory_object_lock_request</strong> call from the memory manager.
+The memory manager can use the <strong>memory_object_lock_request</strong> call to:
+<ul>
+<li>
+Alter access restrictions specified in the <strong>memory_object_data_supply</strong>
+call or a previous <strong>memory_object_lock_request</strong> call.
+<p>
+<li>
+Write back modifications made in memory.
+<p>
+<li>
+Invalidate its cached data.
+</ul>
+<p>
+When the kernel completes the requested actions, it calls
+<strong>memory_object_lock_completed</strong> (asynchronously) using
+the port explicitly provided in the
+<strong>memory_object_lock_request</strong> call. Because the memory manager cannot
+know which pages have been modified, or even which pages remain in the
+cache, it cannot know how many pages will be written back in response to a
+<strong>memory_object_lock_request</strong> call. Receiving the
+<strong>memory_object_lock_completed</strong> call is the only sure
+means of detecting completion. The completion call
+includes the offset and length values from the consistency request
+to distinguish
+it from other consistency requests.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>,
+<a href="memory_object_server.html"><strong>memory_object_server</strong></a>,
+<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>.
-<h2>memory_object_supply_completed</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Return results associated with the kernel's handling of a particular memory manager request.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_supply_completed</strong>
\r <strong>(memory_object_t</strong> <var>reply_port</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>vm_size_t</strong> <var>length</var>,
\r <strong>kern_return_t</strong> <var>result</var>,
\r <strong>vm_offset_t</strong> <var>error_offset</var><strong>);</strong>
\r\r\r<strong>kern_return_t seqnos_memory_object_supply_completed</strong>
\r <strong>(memory_object_t</strong> <var>reply_port</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>vm_size_t</strong> <var>length</var>,
\r <strong>kern_return_t</strong> <var>result</var>,
\r <strong>vm_offset_t</strong> <var>error_offset</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>reply_port</var>
\r<dd>
\r[in reply (receive) right]
\rThe port supplied in the corresponding
\r<strong>memory_object_data_supply</strong> call.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the port
\rnamed in the <strong>memory_object_data_supply</strong> call.
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used for a response by the memory manager. If the memory
\robject has been supplied to more than one kernel, this parameter
\ridentifies the kernel that is making the call.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar]
\rThe offset within the memory object from the corresponding
\rdata supply call.
\r<p>
\r<dt> <var>length</var>
\r<dd>
\r[in scalar]
\rThe number of bytes accepted. The number converts to an
\rintegral number of memory object pages.
\r<p>
\r<dt> <var>result</var>
\r<dd>
\r[in scalar]
\rA kernel return code indicating the result of the supply
\roperation, possibly <strong>KERN_SUCCESS</strong>. <strong>KERN_MEMORY_PRESENT</strong> is
\rcurrently the only error returned; other errors (invalid arguments, for
\rexample) abort the data supply operation.
\r<p>
\r<dt> <var>error_offset</var>
\r<dd>
\r[in scalar]
\rThe offset within the memory object where the first error
\roccurred.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>memory_object_supply_completed</strong> function is called
\ras the result of a
\rkernel message confirming the kernel's action in response to a
\r<strong>memory_object_data_supply</strong> call from the memory manager.
\r<p>
\rWhen the kernel accepts the pages, it calls
\r<strong>memory_object_supply_completed</strong>
\r(asynchronously) using the port explicitly provided in the
\r<strong>memory_object_data_supply</strong> call. Because the data supply
\rcall can provide multiple pages, not
\rall of which the kernel may necessarily accept and some of which the kernel
\rmay have to return to the manager (if precious), the kernel provides this
\rresponse. If the kernel does not accept all of the pages in
\rthe data supply message,
\rit will indicate so in the completion response. If the pages not accepted are
\rprecious, they will be returned (in <strong>memory_object_data_return</strong>
\rmessages) before
\rit sends this completion message. The completion call includes the offset and
\rlength values from the supply request to distinguish it from other supply
\rrequests.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>,
\r<a href="memory_object_server.html"><strong>memory_object_server</strong></a>,
\r<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_supply_completed</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Return results associated with the kernel's handling of a particular memory manager request.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_supply_completed</strong>
+ <strong>(memory_object_t</strong> <var>reply_port</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>vm_size_t</strong> <var>length</var>,
+ <strong>kern_return_t</strong> <var>result</var>,
+ <strong>vm_offset_t</strong> <var>error_offset</var><strong>);</strong>
+
+
+<strong>kern_return_t seqnos_memory_object_supply_completed</strong>
+ <strong>(memory_object_t</strong> <var>reply_port</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>vm_size_t</strong> <var>length</var>,
+ <strong>kern_return_t</strong> <var>result</var>,
+ <strong>vm_offset_t</strong> <var>error_offset</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>reply_port</var>
+<dd>
+[in reply (receive) right]
+The port supplied in the corresponding
+<strong>memory_object_data_supply</strong> call.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the port
+named in the <strong>memory_object_data_supply</strong> call.
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used for a response by the memory manager. If the memory
+object has been supplied to more than one kernel, this parameter
+identifies the kernel that is making the call.
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar]
+The offset within the memory object from the corresponding
+data supply call.
+<p>
+<dt> <var>length</var>
+<dd>
+[in scalar]
+The number of bytes accepted. The number converts to an
+integral number of memory object pages.
+<p>
+<dt> <var>result</var>
+<dd>
+[in scalar]
+A kernel return code indicating the result of the supply
+operation, possibly <strong>KERN_SUCCESS</strong>. <strong>KERN_MEMORY_PRESENT</strong> is
+currently the only error returned; other errors (invalid arguments, for
+example) abort the data supply operation.
+<p>
+<dt> <var>error_offset</var>
+<dd>
+[in scalar]
+The offset within the memory object where the first error
+occurred.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>memory_object_supply_completed</strong> function is called
+as the result of a
+kernel message confirming the kernel's action in response to a
+<strong>memory_object_data_supply</strong> call from the memory manager.
+<p>
+When the kernel accepts the pages, it calls
+<strong>memory_object_supply_completed</strong>
+(asynchronously) using the port explicitly provided in the
+<strong>memory_object_data_supply</strong> call. Because the data supply
+call can provide multiple pages, not
+all of which the kernel may necessarily accept and some of which the kernel
+may have to return to the manager (if precious), the kernel provides this
+response. If the kernel does not accept all of the pages in
+the data supply message,
+it will indicate so in the completion response. If the pages not accepted are
+precious, they will be returned (in <strong>memory_object_data_return</strong>
+messages) before
+it sends this completion message. The completion call includes the offset and
+length values from the supply request to distinguish it from other supply
+requests.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>,
+<a href="memory_object_server.html"><strong>memory_object_server</strong></a>,
+<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>.
-<h2>mach_port_allocate_subsystem</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Create a port right associated with the caller-specified subsystem.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_allocate_subsystem</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>subsystem_t</strong> <var>subsys</var>,
\r <strong>mach_port_name_t</strong> <var>mach_port_name_t</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right] The task acquiring the port right.
\r<p>
\r<dt> <var>subsys</var>
\r<dd>
\r[in scalar] The port right naming the subsystem the newly created port
\ris to be associated with.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[out scalar] The task's name for the port right. This can be any name
\rthat wasn't in use.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_allocate_subsystem</strong> function creates a new right
\rand associates it
\rwith the specifed subsystem (specified via the <var>subsys</var> parameter)
\rpreviously registered via a call to the
\r<strong>mach_subsystem_create</strong> interface.
\rThe new right's name is returned in the <var>name</var> parameter. The
\rassociation of this port with the subsystem is immutable for the
\rlife of the port.
\r<p>
\rAny RPC targeted at the new port will cause the kernel glue-code
\rto locate the server function address and argument signature in the
\rassociated subsystem.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port
\rname parameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe right is allocated.
\r<p>
\r<dt> <strong>KERN_INVALID_TASK</strong>
\r<dd>
\rThe space is null.
\r<p>
\r<dt> <strong>KERN_INVALID_TASK</strong>
\r<dd>
\rThe space is dead.
\r<p>
\r<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
\r<dd>
\rCouldn't allocate memory.
\r<p>
\r<dt> <strong>KERN_NO_SPACE</strong>
\r<dd>
\rNo room in space for another right.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_subsystem_create.html"><strong>mach_subsystem_create</strong></a>,
\r<a href="thread_activation_create.html"><strong>thread_activation_create</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_allocate_subsystem</h2>
+<hr>
+<p>
+<strong>Function</strong> - Create a port right associated with the caller-specified subsystem.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_allocate_subsystem</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>subsystem_t</strong> <var>subsys</var>,
+ <strong>mach_port_name_t</strong> <var>mach_port_name_t</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right] The task acquiring the port right.
+<p>
+<dt> <var>subsys</var>
+<dd>
+[in scalar] The port right naming the subsystem the newly created port
+is to be associated with.
+<p>
+<dt> <var>name</var>
+<dd>
+[out scalar] The task's name for the port right. This can be any name
+that wasn't in use.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_allocate_subsystem</strong> function creates a new right
+and associates it
+with the specifed subsystem (specified via the <var>subsys</var> parameter)
+previously registered via a call to the
+<strong>mach_subsystem_create</strong> interface.
+The new right's name is returned in the <var>name</var> parameter. The
+association of this port with the subsystem is immutable for the
+life of the port.
+<p>
+Any RPC targeted at the new port will cause the kernel glue-code
+to locate the server function address and argument signature in the
+associated subsystem.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port
+name parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The right is allocated.
+<p>
+<dt> <strong>KERN_INVALID_TASK</strong>
+<dd>
+The space is null.
+<p>
+<dt> <strong>KERN_INVALID_TASK</strong>
+<dd>
+The space is dead.
+<p>
+<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
+<dd>
+Couldn't allocate memory.
+<p>
+<dt> <strong>KERN_NO_SPACE</strong>
+<dd>
+No room in space for another right.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_subsystem_create.html"><strong>mach_subsystem_create</strong></a>,
+<a href="thread_activation_create.html"><strong>thread_activation_create</strong></a>.
-<h2>mach_port_request_notification</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Request notification of the specified port event type.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_request_notification</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_name_t</strong> <var>name</var>,
\r <strong>mach_msg_id_t</strong> <var>variant</var>,
\r <strong>mach_port_mscount_t</strong> <var>sync</var>,
\r <strong>mach_port_send_once_t</strong> <var>notify</var>,
\r <strong>mach_msg_type_name_t</strong> <var>notify_type</var>,
\r <strong>mach_port_send_once_t</strong> <var>*previous</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task holding the specified right.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\rThe task's name for the right.
\r<p>
\r<dt> <var>variant</var>
\r<dd>
\r[in scalar]
\rThe type of notification.
\r<p>
\r<dt> <var>sync</var>
\r<dd>
\r[in scalar]
\rSome variants use this value to overcome race conditions.
\r<p>
\r<dt> <var>notify</var>
\r<dd>
\r[in notify send-once or receive (to be converted to send-once) right]
\rA
\rsend-once right, to which the notification will be sent.
\r<p>
\r<dt> <var>notify_type</var>
\r<dd>
\r[in scalar]
\rIPC type of the <var>notify</var> right; either
\r<strong>MACH_MSG_TYPE_MAKE_SEND_ONCE</strong> or <strong>MACH_MSG_TYPE_MOVE_SEND_ONCE</strong>.
\r<p>
\r<dt> <var>previous</var>
\r<dd>
\r[out notify send-once right]
\rThe previously registered send-once right.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_request_notification</strong> function registers a request for a
\rnotification and supplies a send-once right that the notification
\rwill use. It is an atomic
\rswap, returning the previously registered send-once right (or
\r<strong>MACH_PORT_NULL</strong> for none). A notification request may be
\rcancelled by providing <strong>MACH_PORT_NULL</strong>.
\r<p>
\rThe <var>variant</var> argument takes the following values:
\r<dl>
\r<dt> <strong>MACH_NOTIFY_PORT_DESTROYED</strong>
\r<dd>
\r<var>sync</var> must be zero. The <var>name</var> must specify a receive right,
\rand the call requests a port-destroyed notification for the receive
\rright. If the receive right were to have been destroyed, for instance
\rby <strong>mach_port_destroy</strong>, then instead the receive right will be
\rsent in a port-destroyed notification to the registered send-once right.
\r<p>
\r<dt> <strong>MACH_NOTIFY_DEAD_NAME</strong>
\r<dd>
\rThe call requests a dead-name notification. <var>name</var> specifies send,
\rreceive, or send-once rights for a port. If the port is destroyed (and the
\rright remains, becoming a dead name), then a dead-name notification
\rwhich carries the name of the right will be sent to the registered
\rsend-once right. If <var>sync</var> is non-zero,
\rthe <var>name</var> may specify a dead name, and
\ra dead-name notification is immediately generated.
\r<p>
\rWhenever a dead-name notification is generated, the user reference
\rcount of the dead name is incremented. For example, a send right with
\rtwo user refs has a registered dead-name request. If the port is
\rdestroyed, the send right turns into a dead name with three user refs
\r(instead of two), and a dead-name notification is generated.
\r<p>
\rIf the name is made available for reuse, perhaps because of
\r<strong>mach_port_destroy</strong> or <strong>mach_port_mod_refs</strong>,
\ror the name denotes a
\rsend-once right which has a message sent to it, then the registered send-once
\rright is used to generate a port-deleted notification instead.
\r<p>
\r<dt> <strong>MACH_NOTIFY_NO_SENDERS</strong>
\r<dd>
\rThe call requests a no-senders notification. <var>name</var> must specify a
\rreceive right. If the receive right's make-send count is greater than or
\requal to the sync value, and it has no extant send rights, than an
\rimmediate no-senders notification is generated. Otherwise the notification is
\rgenerated when the receive right next loses its last extant send right. In
\reither case, any previously registered send-once right is returned.
\r<p>
\rThe no-senders notification carries the value the port's make-send
\rcount had when it was generated. The make-send count is incremented
\rwhenever a send right is made directly from a receive right. The
\rmake-send count is reset to zero when the receive right is carried in a
\rmessage.
\r<p>
\rWhen moving a receive right, no-senders notifications are canceled,
\rwith a send-once notification sent to indicate the cancelation.
\r</dl>
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_NAME</strong>
\r<dd>
\r<var>name</var> did not denote a right.
\r<p>
\r<dt> <strong>KERN_INVALID_RIGHT</strong>
\r<dd>
\r<var>name</var> denoted an invalid right.
\r<p>
\r<dt> <strong>KERN_INVALID_CAPABILITY</strong>
\r<dd>
\r<var>notify</var> was invalid.
\r</dl>
\r<p>
\rWhen using <strong>MACH_NOTIFY_DEAD_NAME</strong>:
\r<dl>
\r<p>
\r<dt> <strong>KERN_UREFS_OVERFLOW</strong>
\r<dd>
\r<var>name</var> denotes a dead name, but generating an immediate dead-name
\rnotification would overflow the name's user-reference count.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>,
\r<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_request_notification</h2>
+<hr>
+<p>
+<strong>Function</strong> - Request notification of the specified port event type.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_request_notification</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_name_t</strong> <var>name</var>,
+ <strong>mach_msg_id_t</strong> <var>variant</var>,
+ <strong>mach_port_mscount_t</strong> <var>sync</var>,
+ <strong>mach_port_send_once_t</strong> <var>notify</var>,
+ <strong>mach_msg_type_name_t</strong> <var>notify_type</var>,
+ <strong>mach_port_send_once_t</strong> <var>*previous</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task holding the specified right.
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+The task's name for the right.
+<p>
+<dt> <var>variant</var>
+<dd>
+[in scalar]
+The type of notification.
+<p>
+<dt> <var>sync</var>
+<dd>
+[in scalar]
+Some variants use this value to overcome race conditions.
+<p>
+<dt> <var>notify</var>
+<dd>
+[in notify send-once or receive (to be converted to send-once) right]
+A
+send-once right, to which the notification will be sent.
+<p>
+<dt> <var>notify_type</var>
+<dd>
+[in scalar]
+IPC type of the <var>notify</var> right; either
+<strong>MACH_MSG_TYPE_MAKE_SEND_ONCE</strong> or <strong>MACH_MSG_TYPE_MOVE_SEND_ONCE</strong>.
+<p>
+<dt> <var>previous</var>
+<dd>
+[out notify send-once right]
+The previously registered send-once right.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_request_notification</strong> function registers a request for a
+notification and supplies a send-once right that the notification
+will use. It is an atomic
+swap, returning the previously registered send-once right (or
+<strong>MACH_PORT_NULL</strong> for none). A notification request may be
+cancelled by providing <strong>MACH_PORT_NULL</strong>.
+<p>
+The <var>variant</var> argument takes the following values:
+<dl>
+<dt> <strong>MACH_NOTIFY_PORT_DESTROYED</strong>
+<dd>
+<var>sync</var> must be zero. The <var>name</var> must specify a receive right,
+and the call requests a port-destroyed notification for the receive
+right. If the receive right were to have been destroyed, for instance
+by <strong>mach_port_destroy</strong>, then instead the receive right will be
+sent in a port-destroyed notification to the registered send-once right.
+<p>
+<dt> <strong>MACH_NOTIFY_DEAD_NAME</strong>
+<dd>
+The call requests a dead-name notification. <var>name</var> specifies send,
+receive, or send-once rights for a port. If the port is destroyed (and the
+right remains, becoming a dead name), then a dead-name notification
+which carries the name of the right will be sent to the registered
+send-once right. If <var>sync</var> is non-zero,
+the <var>name</var> may specify a dead name, and
+a dead-name notification is immediately generated.
+<p>
+Whenever a dead-name notification is generated, the user reference
+count of the dead name is incremented. For example, a send right with
+two user refs has a registered dead-name request. If the port is
+destroyed, the send right turns into a dead name with three user refs
+(instead of two), and a dead-name notification is generated.
+<p>
+If the name is made available for reuse, perhaps because of
+<strong>mach_port_destroy</strong> or <strong>mach_port_mod_refs</strong>,
+or the name denotes a
+send-once right which has a message sent to it, then the registered send-once
+right is used to generate a port-deleted notification instead.
+<p>
+<dt> <strong>MACH_NOTIFY_NO_SENDERS</strong>
+<dd>
+The call requests a no-senders notification. <var>name</var> must specify a
+receive right. If the receive right's make-send count is greater than or
+equal to the sync value, and it has no extant send rights, than an
+immediate no-senders notification is generated. Otherwise the notification is
+generated when the receive right next loses its last extant send right. In
+either case, any previously registered send-once right is returned.
+<p>
+The no-senders notification carries the value the port's make-send
+count had when it was generated. The make-send count is incremented
+whenever a send right is made directly from a receive right. The
+make-send count is reset to zero when the receive right is carried in a
+message.
+<p>
+When moving a receive right, no-senders notifications are canceled,
+with a send-once notification sent to indicate the cancelation.
+</dl>
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_NAME</strong>
+<dd>
+<var>name</var> did not denote a right.
+<p>
+<dt> <strong>KERN_INVALID_RIGHT</strong>
+<dd>
+<var>name</var> denoted an invalid right.
+<p>
+<dt> <strong>KERN_INVALID_CAPABILITY</strong>
+<dd>
+<var>notify</var> was invalid.
+</dl>
+<p>
+When using <strong>MACH_NOTIFY_DEAD_NAME</strong>:
+<dl>
+<p>
+<dt> <strong>KERN_UREFS_OVERFLOW</strong>
+<dd>
+<var>name</var> denotes a dead name, but generating an immediate dead-name
+notification would overflow the name's user-reference count.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_msg.html"><strong>mach_msg</strong></a>,
+<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>.
-<h2>processor_set_policy_control</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set target processor set's scheduling policy state.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t processor_set_policy_control</strong>
\r <strong>(processor_set_t</strong> <var>processor_set_control</var>,
\r <strong>processor_set_flavor_t</strong> <var>flavor</var>,
\r <strong>processor_set_info_t</strong> <var>policy_info</var>,
\r <strong>mach_msg_type_number_t*</strong> <var>policy_info_count</var>,
\r <strong>boolean_t</strong> <var>change_tasks_threads</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>processor_set_control</var>
\r<dd>
\r[in processor-set-control send right]
\rA processor set control port.
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of policy change to make.
\r<dl>
\r<dt> <strong>PROCESSOR_SET_TIMESHARE_DEFAULT</strong>
\r<dd>
\rChange the base attributes for the timeshare scheduling
\rpolicy, making timeshare the default policy. The structure is
\r<strong>policy_timeshare_base</strong>.
\r<dt> <strong>PROCESSOR_SET_FIFO_DEFAULT</strong>
\r<dd>
\rChange the base attributes for the FIFO (first-in, first-out)
\rscheduling policy, making FIFO the default policy. The
\rstructure is <strong>policy_fifo_base</strong>.
\r<dt> <strong>PROCESSOR_SET_RR_DEFAULT</strong>
\r<dd>
\rChanged the base attributes for the round-robin scheduling
\rpolicy, making round robin the default policy. The structure is
\r<strong>policy_rr_base</strong>.
\r<dt> <strong>PROCESSOR_SET_TIMESHARE_LIMITS</strong>
\r<dd>
\rChange the limits on the allowed timeshare policy attributes.
\rThe structure is defined by <strong>policy_timeshare_limit</strong>.
\r<dt> <strong>PROCESSOR_SET_RR_LIMITS</strong>
\r<dd>
\rChange the limits on the allowed round robin policy
\rattributes. The structure is defined by <strong>policy_rr_limit</strong>.
\r<dt> <strong>PROCESSOR_SET_FIFO_LIMITS</strong>
\r<dd>
\rChange the limits on the allowed first-in, first-out policy
\rattributes. The structure is defined by <strong>policy_fifo_limit</strong>.
\r<dt> <strong>PROCESSOR_SET_ENABLED_POLICIES</strong>
\r<dd>
\rChange the set of enabled policies. The data is a bit-vector.
\r</dl>
\r<dt> <var>policy_info</var>
\r<dd>
\r[in structure]
\rThe relevant policy information.
\r<dt> <var>policy_info_count</var>
\r<dd>
\r[in scalar]
\rThe size of the buffer (in natural-sized units).
\r<dt> <var>change_tasks_threads</var>
\r<dd>
\r[in scalar]
\rIf true, any assigned task or thread whose policy is no
\rlonger enabled or whose scheduling attributes exceed the current limits will
\rhave their limits adjusted or their policy set to the default as
\rappropriate.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_set_policy_control</strong> function controls
\rscheduling attributes governing the processor set.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_set_statistics.html">processor_set_statistics</a>,
\r<a href="processor_set_create.html">processor_set_create</a>,
\r<a href="processor_set_default.html">processor_set_default</a>,
\r<a href="processor_assign.html">processor_assign</a>,
\r<a href="processor_set_info.html">processor_set_info</a>.
\r<p>
\rData Structures:
\r<a href="policy_timeshare_info.html">policy_timeshare_info</a>,
\r<a href="policy_rr_info.html">policy_rr_info</a>,
\r<a href="policy_fifo_info.html">policy_fifo_info</a>.
\r\ No newline at end of file
+<h2>processor_set_policy_control</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set target processor set's scheduling policy state.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t processor_set_policy_control</strong>
+ <strong>(processor_set_t</strong> <var>processor_set_control</var>,
+ <strong>processor_set_flavor_t</strong> <var>flavor</var>,
+ <strong>processor_set_info_t</strong> <var>policy_info</var>,
+ <strong>mach_msg_type_number_t*</strong> <var>policy_info_count</var>,
+ <strong>boolean_t</strong> <var>change_tasks_threads</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>processor_set_control</var>
+<dd>
+[in processor-set-control send right]
+A processor set control port.
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of policy change to make.
+<dl>
+<dt> <strong>PROCESSOR_SET_TIMESHARE_DEFAULT</strong>
+<dd>
+Change the base attributes for the timeshare scheduling
+policy, making timeshare the default policy. The structure is
+<strong>policy_timeshare_base</strong>.
+<dt> <strong>PROCESSOR_SET_FIFO_DEFAULT</strong>
+<dd>
+Change the base attributes for the FIFO (first-in, first-out)
+scheduling policy, making FIFO the default policy. The
+structure is <strong>policy_fifo_base</strong>.
+<dt> <strong>PROCESSOR_SET_RR_DEFAULT</strong>
+<dd>
+Changed the base attributes for the round-robin scheduling
+policy, making round robin the default policy. The structure is
+<strong>policy_rr_base</strong>.
+<dt> <strong>PROCESSOR_SET_TIMESHARE_LIMITS</strong>
+<dd>
+Change the limits on the allowed timeshare policy attributes.
+The structure is defined by <strong>policy_timeshare_limit</strong>.
+<dt> <strong>PROCESSOR_SET_RR_LIMITS</strong>
+<dd>
+Change the limits on the allowed round robin policy
+attributes. The structure is defined by <strong>policy_rr_limit</strong>.
+<dt> <strong>PROCESSOR_SET_FIFO_LIMITS</strong>
+<dd>
+Change the limits on the allowed first-in, first-out policy
+attributes. The structure is defined by <strong>policy_fifo_limit</strong>.
+<dt> <strong>PROCESSOR_SET_ENABLED_POLICIES</strong>
+<dd>
+Change the set of enabled policies. The data is a bit-vector.
+</dl>
+<dt> <var>policy_info</var>
+<dd>
+[in structure]
+The relevant policy information.
+<dt> <var>policy_info_count</var>
+<dd>
+[in scalar]
+The size of the buffer (in natural-sized units).
+<dt> <var>change_tasks_threads</var>
+<dd>
+[in scalar]
+If true, any assigned task or thread whose policy is no
+longer enabled or whose scheduling attributes exceed the current limits will
+have their limits adjusted or their policy set to the default as
+appropriate.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_set_policy_control</strong> function controls
+scheduling attributes governing the processor set.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_set_statistics.html">processor_set_statistics</a>,
+<a href="processor_set_create.html">processor_set_create</a>,
+<a href="processor_set_default.html">processor_set_default</a>,
+<a href="processor_assign.html">processor_assign</a>,
+<a href="processor_set_info.html">processor_set_info</a>.
+<p>
+Data Structures:
+<a href="policy_timeshare_info.html">policy_timeshare_info</a>,
+<a href="policy_rr_info.html">policy_rr_info</a>,
+<a href="policy_fifo_info.html">policy_fifo_info</a>.
-<h2>processor_set_policy_disable</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Disables a scheduling policy for a processor set.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include< mach/mach_host.h></strong>
\r\r<strong>kern_return_t processor_set_policy_disable</strong>
\r <strong>(processor_set_t</strong> <var>processor_set</var>,
\r <strong>int</strong> <var>policy</var>,
\r <strong>boolean_t</strong> <var>change_threads</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>processor_set</var>
\r<dd>
\r[in processor-set-control port] The control port for the processor set for which a scheduling policy is to be disabled.
\r<dt> <var>policy</var>
\r<dd>
\r[in scalar] Policy to be disabled. The values currently defined are POLICY_TIMESHARE and POLICY_FIXEDPRI.
\r<dt> <var>change_threads</var>
\r<dd>
\r[in scalar] If true, causes the scheduling policy for all threads currently running with policy to POLICY_TIMESHARE.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_set_policy_disable</strong>
\rfunction restricts the set of scheduling policies allowed for
\r<var>processor_set</var>. The set of scheduling policies allowed for a
\rprocessor set is the set of policies allowed to be set for threads
\rassigned to that processor set. The current set of permitted policies
\rcan be obtained from <strong>processor_set_info</strong>. Timesharing may
\rnot be forbidden for any processor set. This is a compromise to reduce
\rthe complexity of the assign operation; any thread whose
\r<var>policy</var> is forbidden by its target processor set has its
\r<var>policy</var> reset to timesharing. Disabling a scheduling
\r<var>policy</var> for a processor set has no effect on threads
\rcurrently assigned to that processor set unless
\r<var>change_threads</var> is TRUE, in which case their policies will
\rbe reset to timesharing.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="P_set_policy_enable.html">processor_set_policy_enable</a>,
\r<a href="processor_set_info.html">processor_set_info</a>,
\r<a href="thread_policy.html">thread_policy</a>.
\r\ No newline at end of file
+<h2>processor_set_policy_disable</h2>
+<hr>
+<p>
+<strong>Function</strong> - Disables a scheduling policy for a processor set.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include< mach/mach_host.h></strong>
+
+<strong>kern_return_t processor_set_policy_disable</strong>
+ <strong>(processor_set_t</strong> <var>processor_set</var>,
+ <strong>int</strong> <var>policy</var>,
+ <strong>boolean_t</strong> <var>change_threads</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>processor_set</var>
+<dd>
+[in processor-set-control port] The control port for the processor set for which a scheduling policy is to be disabled.
+<dt> <var>policy</var>
+<dd>
+[in scalar] Policy to be disabled. The values currently defined are POLICY_TIMESHARE and POLICY_FIXEDPRI.
+<dt> <var>change_threads</var>
+<dd>
+[in scalar] If true, causes the scheduling policy for all threads currently running with policy to POLICY_TIMESHARE.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_set_policy_disable</strong>
+function restricts the set of scheduling policies allowed for
+<var>processor_set</var>. The set of scheduling policies allowed for a
+processor set is the set of policies allowed to be set for threads
+assigned to that processor set. The current set of permitted policies
+can be obtained from <strong>processor_set_info</strong>. Timesharing may
+not be forbidden for any processor set. This is a compromise to reduce
+the complexity of the assign operation; any thread whose
+<var>policy</var> is forbidden by its target processor set has its
+<var>policy</var> reset to timesharing. Disabling a scheduling
+<var>policy</var> for a processor set has no effect on threads
+currently assigned to that processor set unless
+<var>change_threads</var> is TRUE, in which case their policies will
+be reset to timesharing.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="P_set_policy_enable.html">processor_set_policy_enable</a>,
+<a href="processor_set_info.html">processor_set_info</a>,
+<a href="thread_policy.html">thread_policy</a>.
-<h2>processor_set_policy_enable</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Enables a scheduling policy for a processor set.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include< mach/mach_host.h></strong>
\r\r<strong>kern_return_t processor_set_policy_enable</strong>
\r <strong>(processor_set_t</strong> <var>processor_set</var>,
\r <strong>int</strong> <var>policy</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>processor_set</var>
\r<dd>
\r[in processor-set-control port] The control port for the processor set for which a scheduling policy is to be enabled.
\r<dt> <var>policy</var>
\r<dd>
\r[in scalar] Policy to be enabled. The values currently defined are POLICY_TIMESHARE and POLICY_FIXEDPRI.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_set_policy_enable</strong>
\rfunction extends the set of scheduling policies allowed for
\r<var>processor_set</var>. The set of scheduling policies allowed for a
\rprocessor set is the set of policies allowed to be set for threads
\rassigned to that processor set. The current set of permitted policies
\rcan be obtained from <strong>processor_set_info</strong>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_set_info.html">processor_set_info</a>,
\r<a href="P_set_policy_disable.html">processor_set_policy_disable</a>,
\r<a href="thread_policy.html">thread_policy</a>.
\r\ No newline at end of file
+<h2>processor_set_policy_enable</h2>
+<hr>
+<p>
+<strong>Function</strong> - Enables a scheduling policy for a processor set.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include< mach/mach_host.h></strong>
+
+<strong>kern_return_t processor_set_policy_enable</strong>
+ <strong>(processor_set_t</strong> <var>processor_set</var>,
+ <strong>int</strong> <var>policy</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>processor_set</var>
+<dd>
+[in processor-set-control port] The control port for the processor set for which a scheduling policy is to be enabled.
+<dt> <var>policy</var>
+<dd>
+[in scalar] Policy to be enabled. The values currently defined are POLICY_TIMESHARE and POLICY_FIXEDPRI.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_set_policy_enable</strong>
+function extends the set of scheduling policies allowed for
+<var>processor_set</var>. The set of scheduling policies allowed for a
+processor set is the set of policies allowed to be set for threads
+assigned to that processor set. The current set of permitted policies
+can be obtained from <strong>processor_set_info</strong>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_set_info.html">processor_set_info</a>,
+<a href="P_set_policy_disable.html">processor_set_policy_disable</a>,
+<a href="thread_policy.html">thread_policy</a>.
-<h2>seqnos_memory_object_default_server</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Handle kernel operation request targeted for the default pager.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>boolean_t seqnos_memory_object_default_server</strong>
\r <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
\r <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>in_msg</var>
\r<dd>
\r[pointer to in structure]
\rThe memory manager message received from
\rthe kernel.
\r<p>
\r<dt> <var>out_msg</var>
\r<dd>
\r[out structure]
\rA reply message. Note that no kernel messages to a
\rmemory manager expect a direct reply.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>seqnos_memory_object_default_server</strong> function is
\rthe MIG generated
\rserver handling function to handle messages from the kernel targeted to the
\rdefault memory manager. This server function only handles messages unique to
\rthe default memory manager. Messages that are common to all memory
\rmanagers are handled by <strong>seqnos_memory_object_server</strong>.
\r<p>
\rA \*Vmemory manager\*O
\ris a server task that responds to specific messages from the
\rkernel in order to handle memory management functions for the kernel. The
\r<strong>seqnos_memory_object_default_server</strong> function performs all necessary
\rargument handling for a kernel message and calls one of the default memory
\rmanager functions.
\r<h3>NOTES</h3>
\r<p>
\r<strong>seqnos_memory_object_default_server</strong> differs from
\r<strong>memory_object_default_server</strong> in that it supplies message
\rsequence numbers to the server
\rinterfaces it calls.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>TRUE</strong>
\r<dd>
\rThe message was handled and the appropriate function was called.
\r<p>
\r<dt> <strong>FALSE</strong>
\r<dd>
\rThe message did not apply to this memory management interface and
\rno other action was taken.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="MO_default_server.html"><strong>memory_object_default_server<strong></a>,
\r<a href="SMO_server.html"><strong>seqnos_memory_object_server<strong></a>,
\r<a href="memory_object_create.html"><strong>seqnos_memory_object_create<strong></a>,
\r<a href="MO_data_initialize.html"><strong>seqnos_memory_object_data_initialize<strong></a>,
\r<a href="DP_object_create.html"><strong>seqnos_default_pager_object_create<strong></a>,
\r<a href="default_pager_info.html"><strong>seqnos_default_pager_info<strong></a>.
\r\ No newline at end of file
+<h2>seqnos_memory_object_default_server</h2>
+<hr>
+<p>
+<strong>Function</strong> - Handle kernel operation request targeted for the default pager.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>boolean_t seqnos_memory_object_default_server</strong>
+ <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
+ <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>in_msg</var>
+<dd>
+[pointer to in structure]
+The memory manager message received from
+the kernel.
+<p>
+<dt> <var>out_msg</var>
+<dd>
+[out structure]
+A reply message. Note that no kernel messages to a
+memory manager expect a direct reply.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>seqnos_memory_object_default_server</strong> function is
+the MIG generated
+server handling function to handle messages from the kernel targeted to the
+default memory manager. This server function only handles messages unique to
+the default memory manager. Messages that are common to all memory
+managers are handled by <strong>seqnos_memory_object_server</strong>.
+<p>
+A \*Vmemory manager\*O
+is a server task that responds to specific messages from the
+kernel in order to handle memory management functions for the kernel. The
+<strong>seqnos_memory_object_default_server</strong> function performs all necessary
+argument handling for a kernel message and calls one of the default memory
+manager functions.
+<h3>NOTES</h3>
+<p>
+<strong>seqnos_memory_object_default_server</strong> differs from
+<strong>memory_object_default_server</strong> in that it supplies message
+sequence numbers to the server
+interfaces it calls.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>TRUE</strong>
+<dd>
+The message was handled and the appropriate function was called.
+<p>
+<dt> <strong>FALSE</strong>
+<dd>
+The message did not apply to this memory management interface and
+no other action was taken.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="MO_default_server.html"><strong>memory_object_default_server<strong></a>,
+<a href="SMO_server.html"><strong>seqnos_memory_object_server<strong></a>,
+<a href="memory_object_create.html"><strong>seqnos_memory_object_create<strong></a>,
+<a href="MO_data_initialize.html"><strong>seqnos_memory_object_data_initialize<strong></a>,
+<a href="DP_object_create.html"><strong>seqnos_default_pager_object_create<strong></a>,
+<a href="default_pager_info.html"><strong>seqnos_default_pager_info<strong></a>.
-<h2>seqnos_memory_object_server</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Handle kernel operation request aimed at a given memory manager.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>boolean_t seqnos_memory_object_server</strong>
\r <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
\r <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>in_msg</var>
\r<dd>
\r[pointer to in structure]
\rThe memory manager message received from
\rthe kernel.
\r<p>
\r<dt> <var>out_msg</var>
\r<dd>
\r[out structure]
\rA reply message. No messages to a memory manager
\rexpect a direct reply, so this field is not used.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>seqnos_memory_object_server</strong> function is the MIG generated server
\rhandling function to handle messages from the kernel targeted to a memory
\rmanager.
\r<p>
\rA \*Vmemory manager\*O
\ris a server task that responds to specific messages from the
\rkernel in order to handle memory management functions for the kernel. The
\r<strong>seqnos_memory_object_server</strong> function performs all necessary argument
\rhandling for a kernel message and calls one of the memory manager functions to
\rinterpret the message.
\r<h3>NOTES</h3>
\r<p>
\r<strong>seqnos_memory_object_server</strong> differs from <strong>memory_object_server</strong>
\rin that it
\rsupplies message sequence numbers to the server interfaces.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>TRUE</strong>
\r<dd>
\rThe message was handled and the appropriate function was called.
\r<p>
\r<dt> <strong>FALSE</strong>
\r<dd>
\rThe message did not apply to this memory management interface and
\rno other action was taken.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server<strong></a>,
\r<a href="memory_object_data_request.html"><strong>seqnos_memory_object_data_request<strong></a>,
\r<a href="memory_object_data_unlock.html"><strong>seqnos_memory_object_data_unlock<strong></a>,
\r<a href="memory_object_data_return.html"><strong>seqnos_memory_object_data_return<strong></a>,
\r<a href="MO_supply_completed.html"><strong>seqnos_memory_object_supply_completed<strong></a>,
\r<a href="MO_lock_completed.html"><strong>seqnos_memory_object_lock_completed<strong></a>,
\r<a href="MO_change_completed.html"><strong>seqnos_seqnos_memory_object_change_completed<strong></a>,
\r<a href="memory_object_terminate.html"><strong>seqnos_memory_object_terminate<strong></a>,
\r<a href="memory_object_synchronize.html"><strong>seqnos_memory_object_synchronize<strong></a>,
\r<a href="memory_object_server.html"><strong>memory_object_server<strong></a>.
\r\ No newline at end of file
+<h2>seqnos_memory_object_server</h2>
+<hr>
+<p>
+<strong>Function</strong> - Handle kernel operation request aimed at a given memory manager.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>boolean_t seqnos_memory_object_server</strong>
+ <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
+ <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>in_msg</var>
+<dd>
+[pointer to in structure]
+The memory manager message received from
+the kernel.
+<p>
+<dt> <var>out_msg</var>
+<dd>
+[out structure]
+A reply message. No messages to a memory manager
+expect a direct reply, so this field is not used.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>seqnos_memory_object_server</strong> function is the MIG generated server
+handling function to handle messages from the kernel targeted to a memory
+manager.
+<p>
+A \*Vmemory manager\*O
+is a server task that responds to specific messages from the
+kernel in order to handle memory management functions for the kernel. The
+<strong>seqnos_memory_object_server</strong> function performs all necessary argument
+handling for a kernel message and calls one of the memory manager functions to
+interpret the message.
+<h3>NOTES</h3>
+<p>
+<strong>seqnos_memory_object_server</strong> differs from <strong>memory_object_server</strong>
+in that it
+supplies message sequence numbers to the server interfaces.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>TRUE</strong>
+<dd>
+The message was handled and the appropriate function was called.
+<p>
+<dt> <strong>FALSE</strong>
+<dd>
+The message did not apply to this memory management interface and
+no other action was taken.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server<strong></a>,
+<a href="memory_object_data_request.html"><strong>seqnos_memory_object_data_request<strong></a>,
+<a href="memory_object_data_unlock.html"><strong>seqnos_memory_object_data_unlock<strong></a>,
+<a href="memory_object_data_return.html"><strong>seqnos_memory_object_data_return<strong></a>,
+<a href="MO_supply_completed.html"><strong>seqnos_memory_object_supply_completed<strong></a>,
+<a href="MO_lock_completed.html"><strong>seqnos_memory_object_lock_completed<strong></a>,
+<a href="MO_change_completed.html"><strong>seqnos_seqnos_memory_object_change_completed<strong></a>,
+<a href="memory_object_terminate.html"><strong>seqnos_memory_object_terminate<strong></a>,
+<a href="memory_object_synchronize.html"><strong>seqnos_memory_object_synchronize<strong></a>,
+<a href="memory_object_server.html"><strong>memory_object_server<strong></a>.
-<h2>thread_swap_exception_ports</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Swap exception ports for a thread.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_swap_exception_ports</strong>
\r <strong>(thread_act_t</strong> <var>thread</var>,
\r <strong>exception_mask_t</strong> <var>exception_types</var>,
\r <strong>mach_port_t</strong> <var>exception_port</var>,
\r <strong>exception_behavior_t</strong> <var>behavior</var>,
\r <strong>thread_state_flavor_t</strong> <var>flavor</var>,
\r <strong>exception_mask_array_t</strong> <var>old_exception_masks</var>,
\r <strong>old_exception_masks</strong> <var>old_exception_count</var>,
\r <strong>exception_port_array_t</strong> <var>old_exception_ports</var>,
\r <strong>exception_behavior_array_t</strong> <var>old_behaviors</var>,
\r <strong>exception_flavor_array_t</strong> <var>old_flavors</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>thread</var>
\r<dd>
\r[in thread send right]
\rThe thread for which to set the ports.
\r<p>
\r<dt> <var>exception_types</var>
\r<dd>
\r[in scalar]
\rA flag word indicating the types of exceptions for which the
\rexception port applies:
\r<dl>
\r<p>
\r<dt> <strong>EXC_MASK_BAD_ACCESS</strong>
\r<dd>
\rCould not access memory.
\r<p>
\r<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
\r<dd>
\rInstruction failed. Illegal or undefined instruction or operand.
\r<p>
\r<dt> <strong>EXC_MASK_ARITHMETIC</strong>
\r<dd>
\rArithmetic exception
\r<p>
\r<dt> <strong>EXC_MASK_EMULATION</strong>
\r<dd>
\rEmulation instruction. Emulation support instruction
\rencountered.
\r<p>
\r<dt> <strong>EXC_MASK_SOFTWARE</strong>
\r<dd>
\rSoftware generated exception.
\r<p>
\r<dt> <strong>EXC_MASK_BREAKPOINT</strong>
\r<dd>
\rTrace, breakpoint, etc.
\r<p>
\r<dt> <strong>EXC_MASK_SYSCALL</strong>
\r<dd>
\rSystem call requested.
\r<p>
\r<dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
\r<dd>
\rSystem call with a number in the Mach call range requested.
\r</dl>
\r<p>
\r<dt> <var>exception_port</var>
\r<dd>
\r[in exception send right]
\rThe exception port for all selected exception
\rtypes.
\r<p>
\r<dt> <var>behavior</var>
\r<dd>
\r[in scalar]
\rControl of the behavior of the exception processing. Defined
\rtypes are:
\r<dl>
\r<p>
\r<dt> <strong>EXCEPTION_DEFAULT</strong>
\r<dd>
\rSend a <strong>catch_exception_raise</strong> message including the thread
\ridentity.
\r<p>
\r<dt> <strong>EXCEPTION_DEFAULT_PROTECTED</strong>
\r<dd>
\rSend a <strong>catch_exception_raise</strong> message including the thread
\ridentity. Mark the exception port (and associated exceptions)
\ras protected.
\r<p>
\r<dt> <strong>EXCEPTION_STATE</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state</strong> message including the
\rthread state.
\r<p>
\r<dt> <strong>EXCEPTION_STATE_PROTECTED</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state</strong> message including the
\rthread state. Mark the exception port (and associated
\rexceptions) as protected.
\r<p>
\r<dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state_identity</strong> message
\rincluding the thread identity and state.
\r<p>
\r<dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state_identity</strong> message
\rincluding the thread identity and state. Mark the exception port
\r(and associated exceptions) as protected.
\r</dl>
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of state to be sent with the exception message.
\rThese types are defined in \*L<mach/thread_states.h>\*O.
\r<p>
\r<dt> <var>old_exception_masks</var>
\r<dd>
\r[out array of <var>exception_mask_t</var>]
\rAn array, each element being a mask
\rspecifying for which exception types the corresponding element of the
\rother arrays apply.
\r<p>
\r<dt> <var>old_exception_count</var>
\r<dd>
\r[pointer to in/out scalar]
\rOn input, the maximum size of the array
\rbuffers; on output, the number of returned <exception type mask,
\rexception port, behavior, flavor> sets returned.
\r<p>
\r<dt> <var>old_exception_ports</var>
\r<dd>
\r[out array of exception send rights]
\rThe returned exception ports.
\r<p>
\r<dt> <var>old_behaviors</var>
\r<dd>
\r[out array of <var>exception_behavior_t</var>]
\rThe type of exception message to
\rbe sent as with <var>behavior</var>.
\r<p>
\r<dt> <var>old_flavors</var>
\r<dd>
\r[out array of <var>thread_state_flavor_t</var>]
\rThe type of state to be sent with
\rthe exception message. These types are defined in
\r\*L<mach/thread_states.h>\*O.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_swap_exception_ports</strong> function sets a specified
\rset of exception
\rports belonging to <var>thread</var>, returning the old set.
\r<h3>NOTES</h3>
\r<p>
\rIf the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is
\rthe host name port, Mach kernel traps are executed by the kernel as expected;
\rany other value causes the attempted execution of these system call numbers to
\rbe considered an exception.
\r<p>
\rA "protected" exception port is one which cannot be fetched and for which
\rexception processing cannot be aborted (<strong>thread_abort</strong>).
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_EXCEPTION_PROTECTED</strong>
\r<dd>
\rOne of the requested exception ports is protected and cannot be returned.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,
\r<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
\r<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
\r<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
\r<a href="thread_create.html"><strong>thread_create</strong></a>,
\r<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
\r<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
\r<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>,
\r<a href="thread_abort.html"><strong>thread_abort</strong></a>.
\r\ No newline at end of file
+<h2>thread_swap_exception_ports</h2>
+<hr>
+<p>
+<strong>Function</strong> - Swap exception ports for a thread.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_swap_exception_ports</strong>
+ <strong>(thread_act_t</strong> <var>thread</var>,
+ <strong>exception_mask_t</strong> <var>exception_types</var>,
+ <strong>mach_port_t</strong> <var>exception_port</var>,
+ <strong>exception_behavior_t</strong> <var>behavior</var>,
+ <strong>thread_state_flavor_t</strong> <var>flavor</var>,
+ <strong>exception_mask_array_t</strong> <var>old_exception_masks</var>,
+ <strong>old_exception_masks</strong> <var>old_exception_count</var>,
+ <strong>exception_port_array_t</strong> <var>old_exception_ports</var>,
+ <strong>exception_behavior_array_t</strong> <var>old_behaviors</var>,
+ <strong>exception_flavor_array_t</strong> <var>old_flavors</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>thread</var>
+<dd>
+[in thread send right]
+The thread for which to set the ports.
+<p>
+<dt> <var>exception_types</var>
+<dd>
+[in scalar]
+A flag word indicating the types of exceptions for which the
+exception port applies:
+<dl>
+<p>
+<dt> <strong>EXC_MASK_BAD_ACCESS</strong>
+<dd>
+Could not access memory.
+<p>
+<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
+<dd>
+Instruction failed. Illegal or undefined instruction or operand.
+<p>
+<dt> <strong>EXC_MASK_ARITHMETIC</strong>
+<dd>
+Arithmetic exception
+<p>
+<dt> <strong>EXC_MASK_EMULATION</strong>
+<dd>
+Emulation instruction. Emulation support instruction
+encountered.
+<p>
+<dt> <strong>EXC_MASK_SOFTWARE</strong>
+<dd>
+Software generated exception.
+<p>
+<dt> <strong>EXC_MASK_BREAKPOINT</strong>
+<dd>
+Trace, breakpoint, etc.
+<p>
+<dt> <strong>EXC_MASK_SYSCALL</strong>
+<dd>
+System call requested.
+<p>
+<dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
+<dd>
+System call with a number in the Mach call range requested.
+</dl>
+<p>
+<dt> <var>exception_port</var>
+<dd>
+[in exception send right]
+The exception port for all selected exception
+types.
+<p>
+<dt> <var>behavior</var>
+<dd>
+[in scalar]
+Control of the behavior of the exception processing. Defined
+types are:
+<dl>
+<p>
+<dt> <strong>EXCEPTION_DEFAULT</strong>
+<dd>
+Send a <strong>catch_exception_raise</strong> message including the thread
+identity.
+<p>
+<dt> <strong>EXCEPTION_DEFAULT_PROTECTED</strong>
+<dd>
+Send a <strong>catch_exception_raise</strong> message including the thread
+identity. Mark the exception port (and associated exceptions)
+as protected.
+<p>
+<dt> <strong>EXCEPTION_STATE</strong>
+<dd>
+Send a <strong>catch_exception_raise_state</strong> message including the
+thread state.
+<p>
+<dt> <strong>EXCEPTION_STATE_PROTECTED</strong>
+<dd>
+Send a <strong>catch_exception_raise_state</strong> message including the
+thread state. Mark the exception port (and associated
+exceptions) as protected.
+<p>
+<dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
+<dd>
+Send a <strong>catch_exception_raise_state_identity</strong> message
+including the thread identity and state.
+<p>
+<dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong>
+<dd>
+Send a <strong>catch_exception_raise_state_identity</strong> message
+including the thread identity and state. Mark the exception port
+(and associated exceptions) as protected.
+</dl>
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of state to be sent with the exception message.
+These types are defined in \*L<mach/thread_states.h>\*O.
+<p>
+<dt> <var>old_exception_masks</var>
+<dd>
+[out array of <var>exception_mask_t</var>]
+An array, each element being a mask
+specifying for which exception types the corresponding element of the
+other arrays apply.
+<p>
+<dt> <var>old_exception_count</var>
+<dd>
+[pointer to in/out scalar]
+On input, the maximum size of the array
+buffers; on output, the number of returned <exception type mask,
+exception port, behavior, flavor> sets returned.
+<p>
+<dt> <var>old_exception_ports</var>
+<dd>
+[out array of exception send rights]
+The returned exception ports.
+<p>
+<dt> <var>old_behaviors</var>
+<dd>
+[out array of <var>exception_behavior_t</var>]
+The type of exception message to
+be sent as with <var>behavior</var>.
+<p>
+<dt> <var>old_flavors</var>
+<dd>
+[out array of <var>thread_state_flavor_t</var>]
+The type of state to be sent with
+the exception message. These types are defined in
+\*L<mach/thread_states.h>\*O.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_swap_exception_ports</strong> function sets a specified
+set of exception
+ports belonging to <var>thread</var>, returning the old set.
+<h3>NOTES</h3>
+<p>
+If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is
+the host name port, Mach kernel traps are executed by the kernel as expected;
+any other value causes the attempted execution of these system call numbers to
+be considered an exception.
+<p>
+A "protected" exception port is one which cannot be fetched and for which
+exception processing cannot be aborted (<strong>thread_abort</strong>).
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_EXCEPTION_PROTECTED</strong>
+<dd>
+One of the requested exception ports is protected and cannot be returned.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,
+<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
+<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
+<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
+<a href="thread_create.html"><strong>thread_create</strong></a>,
+<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
+<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
+<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>,
+<a href="thread_abort.html"><strong>thread_abort</strong></a>.
-<h2>vm_set_default_memory_manager</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Obsolete interface. Functionality now provided via host_set_default_memory_manager interface.<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_set_default_memory_manager</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>mach_port_move_send_t</strong> <var>default_manager</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host_priv</var>
\r<dd>
\r[in host-control send right]
\rThe control port naming the host for which
\rthe default memory manager is to be set.
\r<p>
\r<dt> <var>default_manager</var>
\r<dd>
\r[pointer to in/out default-pager send right]
\rA memory manager port to
\rthe new default memory manager. If this value is <strong>MACH_PORT_NULL</strong>,
\rthe old memory manager is not changed. The old memory
\rmanager port is returned in this variable.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_set_default_memory_manager</strong> function establishes the default
\rmemory manager for a host. The named manager will be the target for future
\r<strong>memory_object_create</strong> calls.
\r<h3>NOTES</h3>
\rThe <strong>vm_set_default_memory_manager</strong> interface has been
\rrenamed to <strong>host_default_memory_manager</strong>. The old
\r<strong>vm_set_default_memory_manager</strong> interface has been retained
\rfor backward compatibility, without the <var>cluster_size</var> parameter.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_create.html"><strong>memory_object_create</strong></a>,
\r<a href="vm_allocate.html"><strong>vm_allocate</strong></a>.
\r\ No newline at end of file
+<h2>vm_set_default_memory_manager</h2>
+<hr>
+<p>
+<strong>Function</strong> - Obsolete interface. Functionality now provided via host_set_default_memory_manager interface.<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t vm_set_default_memory_manager</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>mach_port_move_send_t</strong> <var>default_manager</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host_priv</var>
+<dd>
+[in host-control send right]
+The control port naming the host for which
+the default memory manager is to be set.
+<p>
+<dt> <var>default_manager</var>
+<dd>
+[pointer to in/out default-pager send right]
+A memory manager port to
+the new default memory manager. If this value is <strong>MACH_PORT_NULL</strong>,
+the old memory manager is not changed. The old memory
+manager port is returned in this variable.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_set_default_memory_manager</strong> function establishes the default
+memory manager for a host. The named manager will be the target for future
+<strong>memory_object_create</strong> calls.
+<h3>NOTES</h3>
+The <strong>vm_set_default_memory_manager</strong> interface has been
+renamed to <strong>host_default_memory_manager</strong>. The old
+<strong>vm_set_default_memory_manager</strong> interface has been retained
+for backward compatibility, without the <var>cluster_size</var> parameter.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_create.html"><strong>memory_object_create</strong></a>,
+<a href="vm_allocate.html"><strong>vm_allocate</strong></a>.
-<h2>bootstrap_arguments</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return a set of arguments to the bootstrap task.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t bootstrap_arguments</strong>
\r <strong>(mach_port_t</strong> <var>bootstrap</var>,
\r <strong>task_t</strong> <var>task</var>,
\r <strong>pointer_t</strong> <var>pointer_t</var>,
\r <strong>mach_msg_type_number_t</strong> <var>mach_msg_type_number_t</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>bootstrap</var>
\r<dd>
\r[in bootstrap send right]
\rThe bootstrap port for the task, obtained from
\r<strong>task_get_special_ports</strong>.
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task port for the task whose argument strings are requested.
\r<p>
\r<dt> <var>arguments</var>
\r<dd>
\r[pointer to dynamic out array of characters]
\rThe argument strings for the task. This is an array of
\r<var>argumentCnt</var> bytes, containing NUL characters
\rseparating the strings.
\r<p>
\r<dt> <var>argumentsCnt</var>
\r<dd>
\r[out pointer to scalar]
\rNumber of bytes contained in <var>arguments</var>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe kernel will respond to the bootstrap task (task 1) with the
\rarguments and environment specified to the boot loader. The bootstrap
\rtask can act as a server on this interface for the tasks that it
\rcreates in order to pass arguments to them. The <strong>libsa_mach.a</strong>
\rstandalone Mach C runtime startup code uses <strong>bootstrap_arguments</strong> and
\r<strong>bootstrap_environment</strong> to initialize <var>argc</var>, <var>argv</var>,
\rand <var>envp</var> for <strong>main</strong>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="bootstrap_ports.html"><strong>bootstrap_ports</strong></a>,
\r<a href="bootstrap_environment.html"><strong>bootstrap_environment</strong></a>.
\r\r\ No newline at end of file
+<h2>bootstrap_arguments</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return a set of arguments to the bootstrap task.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t bootstrap_arguments</strong>
+ <strong>(mach_port_t</strong> <var>bootstrap</var>,
+ <strong>task_t</strong> <var>task</var>,
+ <strong>pointer_t</strong> <var>pointer_t</var>,
+ <strong>mach_msg_type_number_t</strong> <var>mach_msg_type_number_t</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>bootstrap</var>
+<dd>
+[in bootstrap send right]
+The bootstrap port for the task, obtained from
+<strong>task_get_special_ports</strong>.
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task port for the task whose argument strings are requested.
+<p>
+<dt> <var>arguments</var>
+<dd>
+[pointer to dynamic out array of characters]
+The argument strings for the task. This is an array of
+<var>argumentCnt</var> bytes, containing NUL characters
+separating the strings.
+<p>
+<dt> <var>argumentsCnt</var>
+<dd>
+[out pointer to scalar]
+Number of bytes contained in <var>arguments</var>.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The kernel will respond to the bootstrap task (task 1) with the
+arguments and environment specified to the boot loader. The bootstrap
+task can act as a server on this interface for the tasks that it
+creates in order to pass arguments to them. The <strong>libsa_mach.a</strong>
+standalone Mach C runtime startup code uses <strong>bootstrap_arguments</strong> and
+<strong>bootstrap_environment</strong> to initialize <var>argc</var>, <var>argv</var>,
+and <var>envp</var> for <strong>main</strong>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="bootstrap_ports.html"><strong>bootstrap_ports</strong></a>,
+<a href="bootstrap_environment.html"><strong>bootstrap_environment</strong></a>.
+
-<h2>bootstrap_completed</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Inform bootstrap server that
\rinitialization is complete.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t bootstrap_completed</strong>
\r <strong>(mach_port_t</strong> <var>bootstrap_port</var>,
\r <strong>task_t</strong> <var>task</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>bootstrap_port</var>
\r<dd>
\rThe port representing the calling task's bootstrap server.
\r<p>
\r<dt> <var>task</var>
\r<dd>
\rThis parameter represents the calling task.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThis interface allows a given server task to inform the bootstrap
\rserver that it is fully initialized and ready to handle requests.
\rUpon receiving such notification, the bootstrap server can initialize
\rany additional servers that may require services provided by the
\rpreviously initialized server.
\r<p>
\rNote the following: not all servers that may be invoked by the bootstrap server
\rsend this message upon startup. If the bootstrap server is told to
\rwait for this message before spawning further servers (via setting a
\rflag in the <strong>bootstrap.conf</strong> file) and the server just invoked never
\rsends this message, the bootstrap server will wait forever.
\r<h3>NOTES</h3>
\r<p>
\rCurrently, this interface is used exclusively by the default
\rpager server so that the bootstrap server can defer initializing the
\rOS server until the default pager is in place. (In small memory
\rconfigurations, an OS server may not be able to initialize
\rsuccessfully unless the default pager is ready to handle paging
\rrequests.)
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe bootstrap server has updated the calling server's state with
\rrespect to bootstrap completion.
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe bootstrap server does not recognize the calling server (the task
\rspecified by the <var>task</var> parameter).
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r\ No newline at end of file
+<h2>bootstrap_completed</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Inform bootstrap server that
+initialization is complete.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t bootstrap_completed</strong>
+ <strong>(mach_port_t</strong> <var>bootstrap_port</var>,
+ <strong>task_t</strong> <var>task</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>bootstrap_port</var>
+<dd>
+The port representing the calling task's bootstrap server.
+<p>
+<dt> <var>task</var>
+<dd>
+This parameter represents the calling task.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+This interface allows a given server task to inform the bootstrap
+server that it is fully initialized and ready to handle requests.
+Upon receiving such notification, the bootstrap server can initialize
+any additional servers that may require services provided by the
+previously initialized server.
+<p>
+Note the following: not all servers that may be invoked by the bootstrap server
+send this message upon startup. If the bootstrap server is told to
+wait for this message before spawning further servers (via setting a
+flag in the <strong>bootstrap.conf</strong> file) and the server just invoked never
+sends this message, the bootstrap server will wait forever.
+<h3>NOTES</h3>
+<p>
+Currently, this interface is used exclusively by the default
+pager server so that the bootstrap server can defer initializing the
+OS server until the default pager is in place. (In small memory
+configurations, an OS server may not be able to initialize
+successfully unless the default pager is ready to handle paging
+requests.)
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The bootstrap server has updated the calling server's state with
+respect to bootstrap completion.
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The bootstrap server does not recognize the calling server (the task
+specified by the <var>task</var> parameter).
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
-<h2>bootstrap_environment</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return to the bootstrap task an array of strings specifying the task's environment.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t bootstrap_environment</strong>
\r <strong>(mach_port_t</strong> <var>bootstrap</var>,
\r <strong>task_t</strong> <var>task</var>,
\r <strong>pointer_t</strong> <var>pointer_t</var>,
\r <strong>mach_msg_type_number_t</strong> <var>mach_msg_type_number_t</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>bootstrap</var>
\r<dd>
\r[in bootstrap send right]
\rThe bootstrap port for the task, obtained from
\r<strong>task_get_special_ports</strong>.
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task port for the task whose argument strings are requested.
\r<p>
\r<dt> <var>environment</var>
\r<dd>
\r[pointer to dynamic out array of characters]
\rThe environment strings for the task. This is an array of
\r\*V*_environmentCnt_\*O bytes, containing NUL characters
\rseparating the strings.
\r<p>
\r<dt> <var>environmentCnt</var>
\r<dd>
\r[out pointer to scalar]
\rNumber of bytes contained in <var>_environment_</var>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\rThe kernel will respond to the bootstrap task (task 1) with the
\rarguments and environment specified to the boot loader. The bootstrap
\rtask can act as a server on this interface for the tasks that it
\rcreates in order to pass an environment to them. The \*Llibsa_mach.a\*O
\rstandalone Mach C runtime startup code uses <strong>bootstrap_arguments</strong> and
\r<strong>bootstrap_environment</strong> to initialize <var>argc</var>, <var>argv</var>,
\rand <var>envp</var> for <strong>main</strong>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="bootstrap_ports.html"><strong>bootstrap_ports</strong></a>,
\r<a href="bootstrap_arguments.html"><strong>bootstrap_arguments</strong></a>.
\r\r\r\ No newline at end of file
+<h2>bootstrap_environment</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return to the bootstrap task an array of strings specifying the task's environment.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t bootstrap_environment</strong>
+ <strong>(mach_port_t</strong> <var>bootstrap</var>,
+ <strong>task_t</strong> <var>task</var>,
+ <strong>pointer_t</strong> <var>pointer_t</var>,
+ <strong>mach_msg_type_number_t</strong> <var>mach_msg_type_number_t</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>bootstrap</var>
+<dd>
+[in bootstrap send right]
+The bootstrap port for the task, obtained from
+<strong>task_get_special_ports</strong>.
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task port for the task whose argument strings are requested.
+<p>
+<dt> <var>environment</var>
+<dd>
+[pointer to dynamic out array of characters]
+The environment strings for the task. This is an array of
+\*V*_environmentCnt_\*O bytes, containing NUL characters
+separating the strings.
+<p>
+<dt> <var>environmentCnt</var>
+<dd>
+[out pointer to scalar]
+Number of bytes contained in <var>_environment_</var>.
+</dl>
+<h3>DESCRIPTION</h3>
+The kernel will respond to the bootstrap task (task 1) with the
+arguments and environment specified to the boot loader. The bootstrap
+task can act as a server on this interface for the tasks that it
+creates in order to pass an environment to them. The \*Llibsa_mach.a\*O
+standalone Mach C runtime startup code uses <strong>bootstrap_arguments</strong> and
+<strong>bootstrap_environment</strong> to initialize <var>argc</var>, <var>argv</var>,
+and <var>envp</var> for <strong>main</strong>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="bootstrap_ports.html"><strong>bootstrap_ports</strong></a>,
+<a href="bootstrap_arguments.html"><strong>bootstrap_arguments</strong></a>.
+
+
-<h2>bootstrap_ports</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return send rights to the system's control ports.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t bootstrap_ports</strong>
\r <strong>(mach_port_t</strong> <var>bootstrap</var>,
\r <strong>bootstrap</strong> <var>host_control</var>,
\r <strong>host_control</strong> <var>device_master</var>,
\r <strong>device_master</strong> <var>root_wired_ledger</var>,
\r <strong>root_wired_ledger</strong> <var>root_paged_ledger</var>,
\r <strong>bootstrap</strong> <var>security</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>bootstrap</var>
\r<dd>
\r[in bootstrap send right]
\rThe bootstrap port obtained from \*Ltask_get_special_ports()\*O.
\r<p>
\r<dt> <var>host_priv</var>
\r<dd>
\r[out host-control send right]
\rThe control port for the host.
\r<p>
\r<dt> <var>device_master</var>
\r<dd>
\r[out device-master send right]
\rThe device master port.
\r<p>
\r<dt> <var>root_wired_ledger</var>
\r<dd>
\r[out ledger send right]
\rThe root wired kernel memory ledger port.
\r<p>
\r<dt> <var>root_paged_ledger</var>
\r<dd>
\r[out ledger send right]
\rThe root default memory managed space ledger
\rport.
\r<p>
\r<dt> <var>security</var>
\r<dd>
\r[out security send right]
\rThe host security port, used for setting task
\ridentity.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>bootstrap_ports</strong> function returns a send right to
\rthe host control, root
\rledger, host security and device master ports. The kernel will respond
\rto this message on the <strong>TASK_BOOTSTRAP_PORT</strong> given to the system bootstrap
\rtask (task 1) with the system privileged ports. It is the
\rresponsibility of the bootstrap task to manage the distribution
\rof these rights to other servers.
\r<p>
\rAn OS personality can serve as a server on the TASK_BOOTSTRAP_PORT
\rfor tasks or servers that it manages, and can regulate or interpose on
\rthe ports in any way it deems necessary.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_open.html"><strong>device_open</strong></a>,
\r<a href="host_get_clock_control.html"><strong>host_get_clock_control</strong></a>,
\r<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>,
\r<a href="host_processor_set_priv.html"><strong>host_processor_set_priv</strong></a>,
\r<a href="host_processors.html"><strong>host_processors</strong></a>,
\r<a href="ledger_create.html"><strong>ledger_create</strong></a>,
\r<a href="task_set_security_token.html"><strong>task_set_security_token</strong></a>.
\r\ No newline at end of file
+<h2>bootstrap_ports</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return send rights to the system's control ports.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t bootstrap_ports</strong>
+ <strong>(mach_port_t</strong> <var>bootstrap</var>,
+ <strong>bootstrap</strong> <var>host_control</var>,
+ <strong>host_control</strong> <var>device_master</var>,
+ <strong>device_master</strong> <var>root_wired_ledger</var>,
+ <strong>root_wired_ledger</strong> <var>root_paged_ledger</var>,
+ <strong>bootstrap</strong> <var>security</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>bootstrap</var>
+<dd>
+[in bootstrap send right]
+The bootstrap port obtained from \*Ltask_get_special_ports()\*O.
+<p>
+<dt> <var>host_priv</var>
+<dd>
+[out host-control send right]
+The control port for the host.
+<p>
+<dt> <var>device_master</var>
+<dd>
+[out device-master send right]
+The device master port.
+<p>
+<dt> <var>root_wired_ledger</var>
+<dd>
+[out ledger send right]
+The root wired kernel memory ledger port.
+<p>
+<dt> <var>root_paged_ledger</var>
+<dd>
+[out ledger send right]
+The root default memory managed space ledger
+port.
+<p>
+<dt> <var>security</var>
+<dd>
+[out security send right]
+The host security port, used for setting task
+identity.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>bootstrap_ports</strong> function returns a send right to
+the host control, root
+ledger, host security and device master ports. The kernel will respond
+to this message on the <strong>TASK_BOOTSTRAP_PORT</strong> given to the system bootstrap
+task (task 1) with the system privileged ports. It is the
+responsibility of the bootstrap task to manage the distribution
+of these rights to other servers.
+<p>
+An OS personality can serve as a server on the TASK_BOOTSTRAP_PORT
+for tasks or servers that it manages, and can regulate or interpose on
+the ports in any way it deems necessary.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_open.html"><strong>device_open</strong></a>,
+<a href="host_get_clock_control.html"><strong>host_get_clock_control</strong></a>,
+<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>,
+<a href="host_processor_set_priv.html"><strong>host_processor_set_priv</strong></a>,
+<a href="host_processors.html"><strong>host_processors</strong></a>,
+<a href="ledger_create.html"><strong>ledger_create</strong></a>,
+<a href="task_set_security_token.html"><strong>task_set_security_token</strong></a>.
-<h2>catch_exception_raise</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Handles the occurrence of an exception within a thread.
\r\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t catch_exception_raise</strong>
\r <strong>(mach_port_t</strong> <var>exception_port</var>,
\r <strong>mach_port_t</strong> <var>thread</var>,
\r <strong>mach_port_t</strong> <var>task</var>,
\r <strong>exception_type_t</strong> <var>exception</var>,
\r <strong>exception_data_t</strong> <var>code</var>,
\r <strong>mach_msg_type_number_t</strong> <var>code_count</var><strong>);</strong>
\r</pre>
\r<p>
\r<strong>catch_exception_raise_state</strong>
\rexpanded form:
\r<pre>
\r<strong>kern_return_t catch_exception_raise_state</strong>
\r <strong>(mach_port_t</strong> <var>exception_port</var>,
\r <strong>exception_type_t</strong> <var>exception</var>,
\r <strong>exception_data_t</strong> <var>code</var>,
\r <strong>mach_msg_type_number_t</strong> <var>code_count</var>,
\r <strong>int *</strong> <var>flavor</var>,
\r <strong>thread_state_t</strong> <var>in_state</var>,
\r <strong>mach_msg_type_number_t</strong> <var>in_state_count</var>,
\r <strong>thread_state_t</strong> <var>out_state</var>,
\r <strong>mach_msg_type_number_t *</strong> <var>out_state_count</var><strong>);</strong>
\r</pre>
\r<p>
\r<strong>catch_exception_raise_state_identity</strong>
\rexpanded form:
\r<pre>
\r<strong>kern_return_t catch_exception_raise_state_identity</strong>
\r <strong>(mach_port_t</strong> <var>exception_port</var>,
\r <strong>mach_port_t</strong> <var>thread</var>,
\r <strong>mach_port_t</strong> <var>task</var>,
\r <strong>exception_type_t</strong> <var>exception</var>,
\r <strong>exception_data_t</strong> <var>code</var>,
\r <strong>mach_msg_type_number_t</strong> <var>code_count</var>,
\r <strong>int *</strong> <var>flavor</var>,
\r <strong>thread_state_t</strong> <var>in_state</var>,
\r <strong>mach_msg_type_number_t</strong> <var>in_state_count</var>,
\r <strong>thread_state_t</strong> <var>out_state</var>,
\r <strong>mach_msg_type_number_t *</strong> <var>out_state_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>exception_port</var>
\r<dd>
\r[in exception (receive) right] The port to which the exception
\rnotification was sent.
\r<p>
\r<dt> <var>thread</var>
\r<dd>
\r[in thread-self send right] The thread self port for the thread taking the
\rexception.
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task-self send right] The task self port for the task containing the
\rthread taking the exception.
\r<p>
\r<dt> <var>exception</var>
\r<dd>
\r[in scalar] The type of the exception.
\rThe machine independent values raised by all implementations are:
\r <dl>
\r<p>
\r<dt> EXC_BAD_ACCESS
\r<dd>
\rCould not access memory. subcode contains the bad memory
\raddress.
\r<p>
\r<dt> EXC_BAD_INSTRUCTION
\r<dd>
\rInstruction failed. Illegal or undefined instruction or operand.
\r<p>
\r<dt> EXC_ARITHMETIC
\r<dd>
\rArithmetic exception; exact nature of exception is in subcode
\rfield.
\r<p>
\r<dt> EXC_EMULATION
\r<dd>
\rEmulation instruction. Emulation support instruction encountered.
\rDetails in subcode field.
\r<p>
\r<dt> EXC_SOFTWARE
\r<dd>
\rSoftware generated exception; exact exception is in subcode
\rfield. Codes 0 - 0xFFFF reserved to hardware; codes 0x10000
\r- 0x1FFFF reserved for OS emulation.
\r<p>
\r<dt> EXC_BREAKPOINT
\r<dd>
\rTrace, breakpoint, etc. Details in subcode field.
\r<p>
\r<dt> EXC_SYSCALL
\r<dd>
\rSystem call requested. Details in subcode field.
\r<p>
\r<dt> EXC_MACH_SYSCALL
\r<dd>
\rSystem call with a number in the Mach call range requested.
\rDetails in subcode field.
\r </dl
\r<p>
\r<dt> <var>code</var>
\r<dd>
\r[in scalar] A machine dependent array indicating a particular instance
\rof exception.
\r<p>
\r<dt> <var>code_count</var>
\r<dd>
\r[in scalar] The size of the buffer (in natural-sized units).
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[pointer to in/out scalar] On input, the type of state included as selected
\rwhen the exception port was set. On output, the type of state being
\rreturned.
\r<p>
\r<dt> <var>in_state</var>
\r<dd>
\r[pointer to in structure] State information of the thread at the time of
\rthe exception.
\r<p>
\r<dt> <var>in_state_count</var>
\r<dd>
\r[in scalar] The size of the in state buffer (in natural-sized units).
\r<p>
\r<dt> <var>out_state</var>
\r<dd>
\r[out structure] The state the thread will have if continued from the
\rpoint of the exception. The maximum size of this array is
\rTHREAD_STATE_MAX.
\r<p>
\r<dt> <var>out_state_count</var>
\r<dd>
\r[pointer to out scalar] The size of the out state buffer (in natural-sized units).
\r </dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>catch_exception_raise</strong> function is called by
\r<strong>exc_server</strong> as the result of a
\rkernel message indicating that an exception occurred within a thread.
\rThe <var>exception_port</var> parameter specifies the port named via
\ra previous call to <strong>thread_set_exception_ports</strong> or
\r<strong>task_set_exception_ports</strong>
\ras the port that responds when the thread takes an
\rexception.
\r<p>
\rThe alternate message forms (the format being selected when the exception port
\rwas set) allow for selected thread state to be included.
\r\r<h3>NOTES</h3>
\r<p>
\rWhen an exception occurs in a thread, the thread sends an exception message to
\rits exception port, blocking in the kernel waiting for the receipt of a reply. It is
\rassumed that some task is listening
\r(most likely with <strong>mach_msg_server</strong>) to this
\rport, using the <strong>exc_server</strong> function
\rto decode the messages and then call the
\rlinked in <strong>catch_exception_raise</strong>.
\rIt is the job of <strong>catch_exception_raise</strong> to handle
\rthe exception and decide the course of action for thread.
\r <p>
\rIf the thread should continue from the point of exception,
\r<strong>catch_exception_raise</strong> would return KERN_SUCCESS. This causes a reply
\rmessage to be sent to the kernel, which will allow the thread to continue from
\rthe point of the exception.
\rIf some other action should be taken by thread, the following actions should be
\rperformed by <strong>catch_exception_raise</strong>:
\r <dl>
\r <dt> <strong>thread_suspend</strong>
\r <dd>
\r This keeps the thread from proceeding after the next step.
\r <p>
\r<dt> <strong>thread_abort</strong>
\r <dd>
\r This aborts the message receive operation currently blocking
\rthe thread.
\r <p>
\r<dt> <strong>thread_set_state</strong>
\r <dd>
\r (if using the <strong>catch_exception_raise</strong> form). Set the
\rthread's state so that it continues doing something else.
\r <p>
\r <dt> <strong>thread_resume</strong>
\r <dd>
\r Let the thread start running from its new state.
\r</dl>
\rReturning a value other than KERN_SUCCESS insures that no reply message
\rwill be sent.
\rsent. (Actually, the kernel uses a send once right to send the exception
\rmessage, which <strong>thread_abort</strong> destroys, so replying to the message is harmless.)
\rThe thread can always be destroyed with <strong>thread_terminate</strong>.
\r<p>
\rA thread can have two exception ports active for it: its thread type specific exception
\rport and the task type specific exception port. The kernel will try sending
\ran exception message to both ports looking for a reply message with a
\rreturn value of KERN_SUCCESS. The kernel tries the thread specific port first,
\rthen the task specific port. If the return value from the first exception message
\rthe kernel sends has a return value of KERN_SUCCESS, the thread continues
\r(with a possibly modified state). If the return value is not KERN_SUCCESS,
\rthe kernel tries the second port. If that return value is KERN_SUCCESS, the
\rthread continues; otherwise, the thread is terminated.
\r<p>
\rTo get the effect of a non-success return value, the server interface should return
\rMIG_DESTROY_REQUEST. This causes <strong>exc_server</strong> and <strong>mach_msg_server</strong>
\rto destroy the kernel's request (as opposed to sending a reply with a
\rKERN_SUCCESS value).
\r\r<h3>RETURN VALUES</h3>
\r<p>
\rA return value of KERN_SUCCESS indicates that the thread is to continue
\rfrom the point of exception. A return value of MIG_NO_REPLY indicates that
\rthe exception was handled directly and the thread was restarted or terminated by
\rthe exception handler. A return value of MIG_DESTROY_REQUEST causes
\rthe kernel to try another exception handler (or terminate the thread). Any other
\rvalue will cause
\r<strong>mach_msg_server</strong> to remove the task and thread port references.
\r\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="exc_server.html"><strong>exc_server</strong></a>,
\r<a href="thread_abort.html"><strong>thread_abort</strong></a>,
\r<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
\r<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
\r<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
\r<a href="thread_resume.html"><strong>thread_resume</strong></a>,
\r<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
\r<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
\r<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
\r<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
\r<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
\r<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
\r<a href="thread_terminate.html"><strong>thread_terminate</strong></a>.
\r\ No newline at end of file
+<h2>catch_exception_raise</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Handles the occurrence of an exception within a thread.
+
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t catch_exception_raise</strong>
+ <strong>(mach_port_t</strong> <var>exception_port</var>,
+ <strong>mach_port_t</strong> <var>thread</var>,
+ <strong>mach_port_t</strong> <var>task</var>,
+ <strong>exception_type_t</strong> <var>exception</var>,
+ <strong>exception_data_t</strong> <var>code</var>,
+ <strong>mach_msg_type_number_t</strong> <var>code_count</var><strong>);</strong>
+</pre>
+<p>
+<strong>catch_exception_raise_state</strong>
+expanded form:
+<pre>
+<strong>kern_return_t catch_exception_raise_state</strong>
+ <strong>(mach_port_t</strong> <var>exception_port</var>,
+ <strong>exception_type_t</strong> <var>exception</var>,
+ <strong>exception_data_t</strong> <var>code</var>,
+ <strong>mach_msg_type_number_t</strong> <var>code_count</var>,
+ <strong>int *</strong> <var>flavor</var>,
+ <strong>thread_state_t</strong> <var>in_state</var>,
+ <strong>mach_msg_type_number_t</strong> <var>in_state_count</var>,
+ <strong>thread_state_t</strong> <var>out_state</var>,
+ <strong>mach_msg_type_number_t *</strong> <var>out_state_count</var><strong>);</strong>
+</pre>
+<p>
+<strong>catch_exception_raise_state_identity</strong>
+expanded form:
+<pre>
+<strong>kern_return_t catch_exception_raise_state_identity</strong>
+ <strong>(mach_port_t</strong> <var>exception_port</var>,
+ <strong>mach_port_t</strong> <var>thread</var>,
+ <strong>mach_port_t</strong> <var>task</var>,
+ <strong>exception_type_t</strong> <var>exception</var>,
+ <strong>exception_data_t</strong> <var>code</var>,
+ <strong>mach_msg_type_number_t</strong> <var>code_count</var>,
+ <strong>int *</strong> <var>flavor</var>,
+ <strong>thread_state_t</strong> <var>in_state</var>,
+ <strong>mach_msg_type_number_t</strong> <var>in_state_count</var>,
+ <strong>thread_state_t</strong> <var>out_state</var>,
+ <strong>mach_msg_type_number_t *</strong> <var>out_state_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>exception_port</var>
+<dd>
+[in exception (receive) right] The port to which the exception
+notification was sent.
+<p>
+<dt> <var>thread</var>
+<dd>
+[in thread-self send right] The thread self port for the thread taking the
+exception.
+<p>
+<dt> <var>task</var>
+<dd>
+[in task-self send right] The task self port for the task containing the
+thread taking the exception.
+<p>
+<dt> <var>exception</var>
+<dd>
+[in scalar] The type of the exception.
+The machine independent values raised by all implementations are:
+ <dl>
+<p>
+<dt> EXC_BAD_ACCESS
+<dd>
+Could not access memory. subcode contains the bad memory
+address.
+<p>
+<dt> EXC_BAD_INSTRUCTION
+<dd>
+Instruction failed. Illegal or undefined instruction or operand.
+<p>
+<dt> EXC_ARITHMETIC
+<dd>
+Arithmetic exception; exact nature of exception is in subcode
+field.
+<p>
+<dt> EXC_EMULATION
+<dd>
+Emulation instruction. Emulation support instruction encountered.
+Details in subcode field.
+<p>
+<dt> EXC_SOFTWARE
+<dd>
+Software generated exception; exact exception is in subcode
+field. Codes 0 - 0xFFFF reserved to hardware; codes 0x10000
+- 0x1FFFF reserved for OS emulation.
+<p>
+<dt> EXC_BREAKPOINT
+<dd>
+Trace, breakpoint, etc. Details in subcode field.
+<p>
+<dt> EXC_SYSCALL
+<dd>
+System call requested. Details in subcode field.
+<p>
+<dt> EXC_MACH_SYSCALL
+<dd>
+System call with a number in the Mach call range requested.
+Details in subcode field.
+ </dl
+<p>
+<dt> <var>code</var>
+<dd>
+[in scalar] A machine dependent array indicating a particular instance
+of exception.
+<p>
+<dt> <var>code_count</var>
+<dd>
+[in scalar] The size of the buffer (in natural-sized units).
+<p>
+<dt> <var>flavor</var>
+<dd>
+[pointer to in/out scalar] On input, the type of state included as selected
+when the exception port was set. On output, the type of state being
+returned.
+<p>
+<dt> <var>in_state</var>
+<dd>
+[pointer to in structure] State information of the thread at the time of
+the exception.
+<p>
+<dt> <var>in_state_count</var>
+<dd>
+[in scalar] The size of the in state buffer (in natural-sized units).
+<p>
+<dt> <var>out_state</var>
+<dd>
+[out structure] The state the thread will have if continued from the
+point of the exception. The maximum size of this array is
+THREAD_STATE_MAX.
+<p>
+<dt> <var>out_state_count</var>
+<dd>
+[pointer to out scalar] The size of the out state buffer (in natural-sized units).
+ </dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>catch_exception_raise</strong> function is called by
+<strong>exc_server</strong> as the result of a
+kernel message indicating that an exception occurred within a thread.
+The <var>exception_port</var> parameter specifies the port named via
+a previous call to <strong>thread_set_exception_ports</strong> or
+<strong>task_set_exception_ports</strong>
+as the port that responds when the thread takes an
+exception.
+<p>
+The alternate message forms (the format being selected when the exception port
+was set) allow for selected thread state to be included.
+
+<h3>NOTES</h3>
+<p>
+When an exception occurs in a thread, the thread sends an exception message to
+its exception port, blocking in the kernel waiting for the receipt of a reply. It is
+assumed that some task is listening
+(most likely with <strong>mach_msg_server</strong>) to this
+port, using the <strong>exc_server</strong> function
+to decode the messages and then call the
+linked in <strong>catch_exception_raise</strong>.
+It is the job of <strong>catch_exception_raise</strong> to handle
+the exception and decide the course of action for thread.
+ <p>
+If the thread should continue from the point of exception,
+<strong>catch_exception_raise</strong> would return KERN_SUCCESS. This causes a reply
+message to be sent to the kernel, which will allow the thread to continue from
+the point of the exception.
+If some other action should be taken by thread, the following actions should be
+performed by <strong>catch_exception_raise</strong>:
+ <dl>
+ <dt> <strong>thread_suspend</strong>
+ <dd>
+ This keeps the thread from proceeding after the next step.
+ <p>
+<dt> <strong>thread_abort</strong>
+ <dd>
+ This aborts the message receive operation currently blocking
+the thread.
+ <p>
+<dt> <strong>thread_set_state</strong>
+ <dd>
+ (if using the <strong>catch_exception_raise</strong> form). Set the
+thread's state so that it continues doing something else.
+ <p>
+ <dt> <strong>thread_resume</strong>
+ <dd>
+ Let the thread start running from its new state.
+</dl>
+Returning a value other than KERN_SUCCESS insures that no reply message
+will be sent.
+sent. (Actually, the kernel uses a send once right to send the exception
+message, which <strong>thread_abort</strong> destroys, so replying to the message is harmless.)
+The thread can always be destroyed with <strong>thread_terminate</strong>.
+<p>
+A thread can have two exception ports active for it: its thread type specific exception
+port and the task type specific exception port. The kernel will try sending
+an exception message to both ports looking for a reply message with a
+return value of KERN_SUCCESS. The kernel tries the thread specific port first,
+then the task specific port. If the return value from the first exception message
+the kernel sends has a return value of KERN_SUCCESS, the thread continues
+(with a possibly modified state). If the return value is not KERN_SUCCESS,
+the kernel tries the second port. If that return value is KERN_SUCCESS, the
+thread continues; otherwise, the thread is terminated.
+<p>
+To get the effect of a non-success return value, the server interface should return
+MIG_DESTROY_REQUEST. This causes <strong>exc_server</strong> and <strong>mach_msg_server</strong>
+to destroy the kernel's request (as opposed to sending a reply with a
+KERN_SUCCESS value).
+
+<h3>RETURN VALUES</h3>
+<p>
+A return value of KERN_SUCCESS indicates that the thread is to continue
+from the point of exception. A return value of MIG_NO_REPLY indicates that
+the exception was handled directly and the thread was restarted or terminated by
+the exception handler. A return value of MIG_DESTROY_REQUEST causes
+the kernel to try another exception handler (or terminate the thread). Any other
+value will cause
+<strong>mach_msg_server</strong> to remove the task and thread port references.
+
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="exc_server.html"><strong>exc_server</strong></a>,
+<a href="thread_abort.html"><strong>thread_abort</strong></a>,
+<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
+<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
+<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
+<a href="thread_resume.html"><strong>thread_resume</strong></a>,
+<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
+<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
+<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
+<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
+<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
+<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
+<a href="thread_terminate.html"><strong>thread_terminate</strong></a>.
-<h2>clock_alarm</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set off an alarm.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t clock_alarm</strong>
\r <strong>(clock_t</strong> <var>clock_name</var>,
\r <strong>alarm_type_t</strong> <var>alarm_type</var>,
\r <strong>tvalspec_t</strong> <var>alarm_time</var>,
\r <strong>mach_port_t</strong> <var>alarm_reply_port</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>clock_name</var>
\r<dd>
\r[in clock-name send right]
\rThe name (or control) port for the clock.
\r<p>
\r<dt> <var>alarm_type</var>
\r<dd>
\r[in scalar]
\rHow to interpret the <var>alarm_time</var> value:
\r<dl>
\r<p>
\r<dt> <strong>TIME_RELATIVE</strong>
\r<dd>
\rInterpret the alarm time as relative to the current time.
\r<p>
\r<dt> <strong>TIME_ABSOLUTE</strong>
\r<dd>
\rInterpret the alarm time as an absolute time.
\r</dl>
\r<p>
\r<dt> <var>alarm_time</var>
\r<dd>
\r[in structure]
\rThe time when the alarm is to be sent.
\r<p>
\r<dt> <var>alarm_reply_port</var>
\r<dd>
\r[in alarm receive (to be converted to send-once) right]
\rA port into
\rwhich the alarm message is to be sent.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>clock_alarm</strong> function requests that a clock send
\ran alarm message to a
\rspecified port at a given future time. The alarm message is specified by the
\r<strong>clock_alarm_reply</strong> server interface.
\r<h3>NOTES</h3>
\r<p>
\rIf the specified alarm time is in the past, the alarm message
\ris sent immediately
\rand time-stamped with the current time. Otherwise, the alarm is queued and
\rdelivered at the specified alarm time and time-stamped at that time.
\r<p>
\rThe alarm will be serviced at the service time nearest the specified
\ralarm time
\ras governed by the current clock alarm resolution.
\r<p>
\rNot all clocks implement this service, but the REALTIME clock must. If the
\rclock does not provide this service, this call is ignored.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>,
\r<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>,
\r<a href="clock_get_time.html"><strong>clock_get_time</strong></a>,
\r<a href="clock_sleep.html"><strong>clock_sleep</strong></a>,
\r<a href="clock_alarm_reply.html"><strong>clock_alarm_reply</strong></a>.
\r<p>
\rData Structures:
\r<a href="tvalspec.html"><strong>tvalspec</strong></a>.
\r\ No newline at end of file
+<h2>clock_alarm</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set off an alarm.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t clock_alarm</strong>
+ <strong>(clock_t</strong> <var>clock_name</var>,
+ <strong>alarm_type_t</strong> <var>alarm_type</var>,
+ <strong>tvalspec_t</strong> <var>alarm_time</var>,
+ <strong>mach_port_t</strong> <var>alarm_reply_port</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>clock_name</var>
+<dd>
+[in clock-name send right]
+The name (or control) port for the clock.
+<p>
+<dt> <var>alarm_type</var>
+<dd>
+[in scalar]
+How to interpret the <var>alarm_time</var> value:
+<dl>
+<p>
+<dt> <strong>TIME_RELATIVE</strong>
+<dd>
+Interpret the alarm time as relative to the current time.
+<p>
+<dt> <strong>TIME_ABSOLUTE</strong>
+<dd>
+Interpret the alarm time as an absolute time.
+</dl>
+<p>
+<dt> <var>alarm_time</var>
+<dd>
+[in structure]
+The time when the alarm is to be sent.
+<p>
+<dt> <var>alarm_reply_port</var>
+<dd>
+[in alarm receive (to be converted to send-once) right]
+A port into
+which the alarm message is to be sent.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>clock_alarm</strong> function requests that a clock send
+an alarm message to a
+specified port at a given future time. The alarm message is specified by the
+<strong>clock_alarm_reply</strong> server interface.
+<h3>NOTES</h3>
+<p>
+If the specified alarm time is in the past, the alarm message
+is sent immediately
+and time-stamped with the current time. Otherwise, the alarm is queued and
+delivered at the specified alarm time and time-stamped at that time.
+<p>
+The alarm will be serviced at the service time nearest the specified
+alarm time
+as governed by the current clock alarm resolution.
+<p>
+Not all clocks implement this service, but the REALTIME clock must. If the
+clock does not provide this service, this call is ignored.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>,
+<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>,
+<a href="clock_get_time.html"><strong>clock_get_time</strong></a>,
+<a href="clock_sleep.html"><strong>clock_sleep</strong></a>,
+<a href="clock_alarm_reply.html"><strong>clock_alarm_reply</strong></a>.
+<p>
+Data Structures:
+<a href="tvalspec.html"><strong>tvalspec</strong></a>.
-<h2>clock_alarm_reply</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Ring a preset alarm.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t clock_alarm_reply</strong>
\r <strong>(reply_port_t</strong> <var>alarm_reply_port</var>,
\r <strong>kern_return_t</strong> <var>reply_code</var>,
\r <strong>alarm_type_t</strong> <var>alarm_type</var>,
\r <strong>tvalspec_t</strong> <var>wake_time</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>alarm_reply_port</var>
\r<dd>
\r[in alarm (receive) right]
\rThe reply port named in the corresponding
\r<strong>clock_alarm</strong> call.
\r<p>
\r<dt> <var>reply_code</var>
\r<dd>
\r[in scalar]
\rThe reply status code from the alarm. The possible values
\rare:
\r<dl>
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe alarm was delivered without problem.
\r<p>
\r<dt> <strong>KERN_INVALID_VALUE</strong>
\r<dd>
\rThe <var>alarm_type</var> and/or <var>alarm_time</var> values supplied to
\r<strong>clock_alarm</strong> were invalid.
\r<p>
\r<dt> <strong>KERN_INVALID_LEDGER</strong>
\r<dd>
\rThe <var>ledger</var> supplied to <strong>clock_alarm</strong> was not a ledger.
\r<p>
\r<dt> <strong>KERN_ABORTED</strong>
\r<dd>
\rThe alarm was terminated via use of <strong>clock_set_time</strong>.
\r</dl>
\r<p>
\r<dt> <var>alarm_type</var>
\r<dd>
\r[in scalar]
\rThe alarm type value supplied to the <strong>clock_alarm</strong> call.
\rOnly the low order bits of this value are used by the kernel so the high
\rorder bits are available for application use as an alarm identifier.
\r<p>
\r<dt> <var>wake_time</var>
\r<dd>
\r[in structure]
\rThe time when the alarm message was sent.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>clock_alarm_reply</strong> function is called as the result
\rof a message from the
\rkernel indicating that a previously requested alarm time (<strong>clock_alarm</strong>)
\rhas arrived.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>,
\r<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>,
\r<a href="clock_get_time.html"><strong>clock_get_time</strong></a>,
\r<a href="clock_sleep.html"><strong>clock_sleep</strong></a>,
\r<a href="clock_alarm.html"><strong>clock_alarm</strong></a>,
\r<a href="clock_reply_server.html"><strong>clock_reply_server</strong></a>,
\r<a href="clock_set_time.html"><strong>clock_set_time</strong></a>.
\r<p>
\rData Structures:
\r<a href="tvalspec.html"><strong>tvalspec</strong></a>.
\r\ No newline at end of file
+<h2>clock_alarm_reply</h2>
+<hr>
+<p>
+<strong>Function</strong> - Ring a preset alarm.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t clock_alarm_reply</strong>
+ <strong>(reply_port_t</strong> <var>alarm_reply_port</var>,
+ <strong>kern_return_t</strong> <var>reply_code</var>,
+ <strong>alarm_type_t</strong> <var>alarm_type</var>,
+ <strong>tvalspec_t</strong> <var>wake_time</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>alarm_reply_port</var>
+<dd>
+[in alarm (receive) right]
+The reply port named in the corresponding
+<strong>clock_alarm</strong> call.
+<p>
+<dt> <var>reply_code</var>
+<dd>
+[in scalar]
+The reply status code from the alarm. The possible values
+are:
+<dl>
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The alarm was delivered without problem.
+<p>
+<dt> <strong>KERN_INVALID_VALUE</strong>
+<dd>
+The <var>alarm_type</var> and/or <var>alarm_time</var> values supplied to
+<strong>clock_alarm</strong> were invalid.
+<p>
+<dt> <strong>KERN_INVALID_LEDGER</strong>
+<dd>
+The <var>ledger</var> supplied to <strong>clock_alarm</strong> was not a ledger.
+<p>
+<dt> <strong>KERN_ABORTED</strong>
+<dd>
+The alarm was terminated via use of <strong>clock_set_time</strong>.
+</dl>
+<p>
+<dt> <var>alarm_type</var>
+<dd>
+[in scalar]
+The alarm type value supplied to the <strong>clock_alarm</strong> call.
+Only the low order bits of this value are used by the kernel so the high
+order bits are available for application use as an alarm identifier.
+<p>
+<dt> <var>wake_time</var>
+<dd>
+[in structure]
+The time when the alarm message was sent.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>clock_alarm_reply</strong> function is called as the result
+of a message from the
+kernel indicating that a previously requested alarm time (<strong>clock_alarm</strong>)
+has arrived.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>,
+<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>,
+<a href="clock_get_time.html"><strong>clock_get_time</strong></a>,
+<a href="clock_sleep.html"><strong>clock_sleep</strong></a>,
+<a href="clock_alarm.html"><strong>clock_alarm</strong></a>,
+<a href="clock_reply_server.html"><strong>clock_reply_server</strong></a>,
+<a href="clock_set_time.html"><strong>clock_set_time</strong></a>.
+<p>
+Data Structures:
+<a href="tvalspec.html"><strong>tvalspec</strong></a>.
-<h2>clock_get_attributes</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return attributes of a clock.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t clock_get_attributes</strong>
\r <strong>(clock_t</strong> <var>clock_name</var>,
\r <strong>clock_flavor_t</strong> <var>flavor</var>,
\r <strong>clock_attr_t</strong> <var>attribute</var>,
\r <strong>mach_msg_type_number_t</strong> <var>attribute_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>clock_name</var>
\r<dd>
\r[in clock-name send right]
\rThe name (or control) port for the clock.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rType of information desired. Defined values are:
\r<dl>
\r<p>
\r<dt> <strong>CLOCK_GET_TIME_RES</strong>
\r<dd>
\rThe resolution, in nanoseconds, with which the value returned
\rby <strong>clock_get_time</strong> is updated.
\r<p>
\r<dt> <strong>CLOCK_MAP_TIME_RES</strong>
\r<dd>
\rThe resolution, in nanoseconds, with which the value visible
\rvia <strong>clock_map_time</strong> is updated.
\r<p>
\r<dt> <strong>CLOCK_ALARM_CURRES</strong>
\r<dd>
\rThe resolution, in nanoseconds, at which clock alarm and
\rsleep timers are currently serviced.
\r<p>
\r<dt> <strong>CLOCK_ALARM_MINRES</strong>
\r<dd>
\rThe minimum resolution, in nanoseconds, at which clock
\ralarm and sleep timers can be serviced.
\r<p>
\r<dt> <strong>CLOCK_ALARM_MAXRES</strong>
\r<dd>
\rThe maximum resolution, in nanoseconds, at which clock
\ralarm and sleep timers can be serviced.
\r</dl>
\r<p>
\r<dt> <var>attribute</var>
\r<dd>
\r[out scalar]
\rThe returned attribute.
\r<p>
\r<dt> <var>attribute_count</var>
\r<dd>
\r[in/out scalar]
\rOn input, the maximum size of the buffer; on output, the
\rsize returned (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>clock_get_attributes</strong> function returns attributes of a clock's
\rimplementation or operation.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>,
\r<a href="clock_get_time.html"><strong>clock_get_time</strong></a>,
\r<a href="clock_map_time.html"><strong>clock_map_time</strong></a>,
\r<a href="clock_sleep.html"><strong>clock_sleep</strong></a>,
\r<a href="clock_alarm.html"><strong>clock_alarm</strong></a>,
\r<a href="clock_set_attributes.html"><strong>clock_set_attributes</strong></a>.
\r\ No newline at end of file
+<h2>clock_get_attributes</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return attributes of a clock.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t clock_get_attributes</strong>
+ <strong>(clock_t</strong> <var>clock_name</var>,
+ <strong>clock_flavor_t</strong> <var>flavor</var>,
+ <strong>clock_attr_t</strong> <var>attribute</var>,
+ <strong>mach_msg_type_number_t</strong> <var>attribute_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>clock_name</var>
+<dd>
+[in clock-name send right]
+The name (or control) port for the clock.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+Type of information desired. Defined values are:
+<dl>
+<p>
+<dt> <strong>CLOCK_GET_TIME_RES</strong>
+<dd>
+The resolution, in nanoseconds, with which the value returned
+by <strong>clock_get_time</strong> is updated.
+<p>
+<dt> <strong>CLOCK_MAP_TIME_RES</strong>
+<dd>
+The resolution, in nanoseconds, with which the value visible
+via <strong>clock_map_time</strong> is updated.
+<p>
+<dt> <strong>CLOCK_ALARM_CURRES</strong>
+<dd>
+The resolution, in nanoseconds, at which clock alarm and
+sleep timers are currently serviced.
+<p>
+<dt> <strong>CLOCK_ALARM_MINRES</strong>
+<dd>
+The minimum resolution, in nanoseconds, at which clock
+alarm and sleep timers can be serviced.
+<p>
+<dt> <strong>CLOCK_ALARM_MAXRES</strong>
+<dd>
+The maximum resolution, in nanoseconds, at which clock
+alarm and sleep timers can be serviced.
+</dl>
+<p>
+<dt> <var>attribute</var>
+<dd>
+[out scalar]
+The returned attribute.
+<p>
+<dt> <var>attribute_count</var>
+<dd>
+[in/out scalar]
+On input, the maximum size of the buffer; on output, the
+size returned (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>clock_get_attributes</strong> function returns attributes of a clock's
+implementation or operation.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>,
+<a href="clock_get_time.html"><strong>clock_get_time</strong></a>,
+<a href="clock_map_time.html"><strong>clock_map_time</strong></a>,
+<a href="clock_sleep.html"><strong>clock_sleep</strong></a>,
+<a href="clock_alarm.html"><strong>clock_alarm</strong></a>,
+<a href="clock_set_attributes.html"><strong>clock_set_attributes</strong></a>.
-<h2>clock_get_time</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return the current time.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t clock_get_time</strong>
\r <strong>(clock_t</strong> <var>clock_name</var>,
\r <strong>tvalspec_t</strong> <var>cur_time</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>clock_name</var>
\r<dd>
\r[in clock-name send right]
\rThe name (or control) port for the clock.
\r<p>
\r<dt> <var>cur_time</var>
\r<dd>
\r[out structure]
\rCurrent time
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>clock_get_time</strong> function returns the current time
\rkept by a clock. The
\rvalue returned is a monotonically increasing value (unless tampered
\rwith via the
\r<strong>clock_set_time</strong> function).
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>,
\r<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>,
\r<a href="clock_map_time.html"><strong>clock_map_time</strong></a>,
\r<a href="clock_sleep.html"><strong>clock_sleep</strong></a>,
\r<a href="clock_alarm.html"><strong>clock_alarm</strong></a>,
\r<a href="clock_set_time.html"><strong>clock_set_time</strong></a>.
\r<p>
\rData Structures:
\r<a href="tvalspec.html"><strong>tvalspec</strong></a>.
\r\ No newline at end of file
+<h2>clock_get_time</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return the current time.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t clock_get_time</strong>
+ <strong>(clock_t</strong> <var>clock_name</var>,
+ <strong>tvalspec_t</strong> <var>cur_time</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>clock_name</var>
+<dd>
+[in clock-name send right]
+The name (or control) port for the clock.
+<p>
+<dt> <var>cur_time</var>
+<dd>
+[out structure]
+Current time
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>clock_get_time</strong> function returns the current time
+kept by a clock. The
+value returned is a monotonically increasing value (unless tampered
+with via the
+<strong>clock_set_time</strong> function).
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>,
+<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>,
+<a href="clock_map_time.html"><strong>clock_map_time</strong></a>,
+<a href="clock_sleep.html"><strong>clock_sleep</strong></a>,
+<a href="clock_alarm.html"><strong>clock_alarm</strong></a>,
+<a href="clock_set_time.html"><strong>clock_set_time</strong></a>.
+<p>
+Data Structures:
+<a href="tvalspec.html"><strong>tvalspec</strong></a>.
-<h2>clock_map_time</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return a memory object that maps a clock.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t clock_map_time</strong>
\r <strong>(clock_t</strong> <var>clock_name</var>,
\r <strong>memory_object_t</strong> <var>clock_memory</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>clock_name</var>
\r<dd>
\r[in clock-name send right]
\rThe name (or control) port for the clock.
\r<p>
\r<dt> <var>clock_memory</var>
\r<dd>
\r[out memory-object-representative send right]
\rMapped clock time
\rmemory object representative.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>clock_map_time</strong> function returns a memory object representative port
\rrepresenting read access to a memory object that contains (at offset zero) a
\rmapped version of the clock time (structure <strong>mapped_tvalspec</strong>).
\rThe returned right is suitable as an argument for <strong>vm_map</strong>.
\r<h3>NOTES</h3>
\r<p>
\rNot all clocks provide this service, but the REALTIME clock must.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_FAILURE</strong>
\r<dd>
\rThe specified clock does not provide this service.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>,
\r<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>,
\r<a href="clock_get_time.html"><strong>clock_get_time</strong></a>,
\r<a href="clock_sleep.html"><strong>clock_sleep</strong></a>,
\r<a href="clock_alarm.html"><strong>clock_alarm</strong></a>.
\r<p>
\rData Structures:
\r<a href="mapped_tvalspec.html"><strong>mapped_tvalspec</strong></a>.
\r\ No newline at end of file
+<h2>clock_map_time</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return a memory object that maps a clock.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t clock_map_time</strong>
+ <strong>(clock_t</strong> <var>clock_name</var>,
+ <strong>memory_object_t</strong> <var>clock_memory</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>clock_name</var>
+<dd>
+[in clock-name send right]
+The name (or control) port for the clock.
+<p>
+<dt> <var>clock_memory</var>
+<dd>
+[out memory-object-representative send right]
+Mapped clock time
+memory object representative.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>clock_map_time</strong> function returns a memory object representative port
+representing read access to a memory object that contains (at offset zero) a
+mapped version of the clock time (structure <strong>mapped_tvalspec</strong>).
+The returned right is suitable as an argument for <strong>vm_map</strong>.
+<h3>NOTES</h3>
+<p>
+Not all clocks provide this service, but the REALTIME clock must.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_FAILURE</strong>
+<dd>
+The specified clock does not provide this service.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>,
+<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>,
+<a href="clock_get_time.html"><strong>clock_get_time</strong></a>,
+<a href="clock_sleep.html"><strong>clock_sleep</strong></a>,
+<a href="clock_alarm.html"><strong>clock_alarm</strong></a>.
+<p>
+Data Structures:
+<a href="mapped_tvalspec.html"><strong>mapped_tvalspec</strong></a>.
-<h2>clock_reply_server</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Handle kernel-generated alarm.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>boolean_t clock_reply_server</strong>
\r <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
\r <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>in_msg</var>
\r<dd>
\r[pointer to in structure]
\rThe alarm message received from the kernel.
\r<p>
\r<dt> <var>out_msg</var>
\r<dd>
\r[out structure]
\rNot used.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>clock_reply_server</strong> function is the MIG generated server handling
\rfunction to handle messages from the kernel corresponding to
\rclock alarms. Such
\rmessages are delivered to the alarm reply port named in a <strong>clock_alarm</strong>
\rcall. The <strong>clock_reply_server</strong> function performs all necessary
\rargument handling for
\rthis kernel message and calls the appropriate handling function. These functions
\rmust be supplied by the caller.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>TRUE</strong>
\r<dd>
\rThe message was handled and the appropriate function was called.
\r<p>
\r<dt> <strong>FALSE</strong>
\r<dd>
\rThe message did not apply to the alarm mechanism and no other action
\rwas taken.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="clock_alarm_reply.html"><strong>clock_alarm_reply<strong></a>.
\r\ No newline at end of file
+<h2>clock_reply_server</h2>
+<hr>
+<p>
+<strong>Function</strong> - Handle kernel-generated alarm.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>boolean_t clock_reply_server</strong>
+ <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
+ <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>in_msg</var>
+<dd>
+[pointer to in structure]
+The alarm message received from the kernel.
+<p>
+<dt> <var>out_msg</var>
+<dd>
+[out structure]
+Not used.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>clock_reply_server</strong> function is the MIG generated server handling
+function to handle messages from the kernel corresponding to
+clock alarms. Such
+messages are delivered to the alarm reply port named in a <strong>clock_alarm</strong>
+call. The <strong>clock_reply_server</strong> function performs all necessary
+argument handling for
+this kernel message and calls the appropriate handling function. These functions
+must be supplied by the caller.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>TRUE</strong>
+<dd>
+The message was handled and the appropriate function was called.
+<p>
+<dt> <strong>FALSE</strong>
+<dd>
+The message did not apply to the alarm mechanism and no other action
+was taken.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="clock_alarm_reply.html"><strong>clock_alarm_reply<strong></a>.
-<h2>clock_set_attributes</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set a particular clock's attributes.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t clock_set_attributes</strong>
\r <strong>(clock_ctrl_t</strong> <var>clock_control</var>,
\r <strong>clock_flavor_t</strong> <var>flavor</var>,
\r <strong>clock_attr_t</strong> <var>attribute</var>,
\r <strong>clock_control</strong> <var>attribute_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>clock_control</var>
\r<dd>
\r[in clock-control send right]
\rThe control port for the clock.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rType of information to be set. Defined values are:
\r<dl>
\r<p>
\r<dt> <strong>CLOCK_ALARM_CURRES</strong>
\r<dd>
\rThe resolution, in nanoseconds, at which clock alarm and
\rsleep timers are currently serviced. Increasing the current
\rresolution will have no impact on any pending clock alarms (i.e.
\rthey will go off as originally scheduled). Decreasing the
\rcurrent resolution will truncate any pending alarms to the
\rgranularity of the new current resolution. This value must be a
\rmultiple of the minimum resolution and not greater than the
\rmaximum resolution of the clock.
\r</dl>
\r<p>
\r<dt> <var>attribute</var>
\r<dd>
\r[pointer to in scalar]
\rNew attribute.
\r<p>
\r<dt> <var>attribute_count</var>
\r<dd>
\r[in scalar]
\rThe size of the buffer (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>clock_set_attributes</strong> function sets attributes of
\ra clock's operation.
\r<h3>NOTES</h3>
\r<p>
\rThe main reason a clock's current resolution would not always equal its
\rminimum resolution is because the overhead of sustaining the
\rminimum resolution,
\rwhen it is not needed by any existing alarm service client, may be prohibitive
\rfor a given hardware platform and underlying clock device.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_get_clock_control.html"><strong>host_get_clock_control</strong></a>,
\r<a href="clock_set_time.html"><strong>clock_set_time</strong></a>,
\r<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>.
\r\ No newline at end of file
+<h2>clock_set_attributes</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set a particular clock's attributes.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t clock_set_attributes</strong>
+ <strong>(clock_ctrl_t</strong> <var>clock_control</var>,
+ <strong>clock_flavor_t</strong> <var>flavor</var>,
+ <strong>clock_attr_t</strong> <var>attribute</var>,
+ <strong>clock_control</strong> <var>attribute_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>clock_control</var>
+<dd>
+[in clock-control send right]
+The control port for the clock.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+Type of information to be set. Defined values are:
+<dl>
+<p>
+<dt> <strong>CLOCK_ALARM_CURRES</strong>
+<dd>
+The resolution, in nanoseconds, at which clock alarm and
+sleep timers are currently serviced. Increasing the current
+resolution will have no impact on any pending clock alarms (i.e.
+they will go off as originally scheduled). Decreasing the
+current resolution will truncate any pending alarms to the
+granularity of the new current resolution. This value must be a
+multiple of the minimum resolution and not greater than the
+maximum resolution of the clock.
+</dl>
+<p>
+<dt> <var>attribute</var>
+<dd>
+[pointer to in scalar]
+New attribute.
+<p>
+<dt> <var>attribute_count</var>
+<dd>
+[in scalar]
+The size of the buffer (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>clock_set_attributes</strong> function sets attributes of
+a clock's operation.
+<h3>NOTES</h3>
+<p>
+The main reason a clock's current resolution would not always equal its
+minimum resolution is because the overhead of sustaining the
+minimum resolution,
+when it is not needed by any existing alarm service client, may be prohibitive
+for a given hardware platform and underlying clock device.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_get_clock_control.html"><strong>host_get_clock_control</strong></a>,
+<a href="clock_set_time.html"><strong>clock_set_time</strong></a>,
+<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>.
-<h2>clock_set_time</h2>
\r<hr>
\r<p><strong>Function</strong> - Set the current time.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t clock_set_time</strong>
\r <strong>(clock_ctrl_t</strong> <var>clock_control</var>,
\r <strong>tvalspec_t</strong> <var>new_time</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>clock_control</var>
\r<dd>
\r[in clock-control send right]
\rThe control port for the clock.
\r<p>
\r<dt> <var>new_time</var>
\r<dd>
\r[in structure]
\rNew time
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>clock_set_time</strong> function sets the time kept by a
\rclock. Setting the clock
\rtime will cause all pending clock alarms and sleeps to be terminated with
\rtimestamps set to the current clock time just prior to the new
\rtime being set with a
\rreturn code of <strong>KERN_ABORTED</strong>.
\r<h3>CAUTIONS</h3>
\r<p>
\rThe use of this function is \*Vstrongly discouraged\*O since it could affect the
\rmonotonically increasing nature of the clock.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_get_clock_control.html"><strong>host_get_clock_control</strong></a>,
\r<a href="clock_set_attributes.html"><strong>clock_set_attributes</strong></a>,
\r<a href="clock_get_time.html"><strong>clock_get_time</strong></a>,
\r<a href="clock_alarm.html"><strong>clock_alarm</strong></a>,
\r<a href="clock_sleep.html"><strong>clock_sleep</strong></a>.
\r<p>
\rData Structures:
\r<a href="tvalspec.html"><strong>tvalspec</strong></a>.
\r\ No newline at end of file
+<h2>clock_set_time</h2>
+<hr>
+<p><strong>Function</strong> - Set the current time.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t clock_set_time</strong>
+ <strong>(clock_ctrl_t</strong> <var>clock_control</var>,
+ <strong>tvalspec_t</strong> <var>new_time</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>clock_control</var>
+<dd>
+[in clock-control send right]
+The control port for the clock.
+<p>
+<dt> <var>new_time</var>
+<dd>
+[in structure]
+New time
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>clock_set_time</strong> function sets the time kept by a
+clock. Setting the clock
+time will cause all pending clock alarms and sleeps to be terminated with
+timestamps set to the current clock time just prior to the new
+time being set with a
+return code of <strong>KERN_ABORTED</strong>.
+<h3>CAUTIONS</h3>
+<p>
+The use of this function is \*Vstrongly discouraged\*O since it could affect the
+monotonically increasing nature of the clock.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_get_clock_control.html"><strong>host_get_clock_control</strong></a>,
+<a href="clock_set_attributes.html"><strong>clock_set_attributes</strong></a>,
+<a href="clock_get_time.html"><strong>clock_get_time</strong></a>,
+<a href="clock_alarm.html"><strong>clock_alarm</strong></a>,
+<a href="clock_sleep.html"><strong>clock_sleep</strong></a>.
+<p>
+Data Structures:
+<a href="tvalspec.html"><strong>tvalspec</strong></a>.
-<h2>clock_sleep</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> - Sleep until a given time.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t clock_sleep</strong>
\r <strong>(mach_port_t</strong> <var>clock_name</var>,
\r <strong>sleep_type_t</strong> <var>sleep_type</var>,
\r <strong>tvalspec_t</strong> <var>sleep_time</var>,
\r <strong>clock_name</strong> <var>wake_time</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt><var>clock_name</var>
\r<dd>
\r[in clock-name send right] The name (or control) port for the clock.
\r<p>
\r<dt><var>sleep_type</var>
\r<dd>
\r[in scalar] How to interpret the sleep_time value:
\r <dl>
\r<p>
\r<dt><strong>TIME_RELATIVE</strong>
\r<dd>
\rInterpret the sleep time as relative to the current time.
\r<p>
\r<dt><strong>TIME_ABSOLUTE</strong>
\r<dd>
\rInterpret the sleep time as an absolute time.
\r </dl>
\r<p>
\r<dt><var>sleep_time</var>
\r<dd>
\r[in structure] The time when the sleep is to terminate.
\r<p>
\r<dt><var>wake_time</var>
\r<dd>
\r[out structure] The actual (absolute) time at which the sleep terminated.
\r</dl>
\r\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>clock_sleep</strong> system trap delays the invoking
\rthread until a specified time. This sleep may be aborted by
\r<strong>thread_abort</strong>. Not all clocks provide this service
\rbut the REALTIME clock must.
\r<p>
\rIf the specified time is in the past, the call returns immediately
\rwith the wake time being the current time. If the clock's time is
\rchanged (<strong>clock_set_time</strong>), the sleep will be
\rinterrupted. The thread will waken at the service time nearest the
\rspecified sleep time as governed by the current clock alarm
\rresolution.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_FAILURE</strong>
\r<dd>
\rThe clock does not support a sleep service.
\r<p>
\r<dt> <strong>KERN_ABORTED</strong>
\r<dd>
\rThe sleep was interrupted by thread_abort or terminated via use of
\rclock_set_time.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>,
\r<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>,
\r<a href="clock_get_time.html"><strong>clock_get_time</strong></a>,
\r<a href="clock_alarm.html"><strong>clock_alarm</strong></a>,
\r<a href="clock_set_time.html"><strong>clock_set_time</strong></a>,
\r<a href="thread_abort.html"><strong>thread_abort</strong></a>,
\r<p>
\rData Structures:
\rtvalspec.
\r\ No newline at end of file
+<h2>clock_sleep</h2>
+<hr>
+<p>
+<strong>System Trap</strong> - Sleep until a given time.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t clock_sleep</strong>
+ <strong>(mach_port_t</strong> <var>clock_name</var>,
+ <strong>sleep_type_t</strong> <var>sleep_type</var>,
+ <strong>tvalspec_t</strong> <var>sleep_time</var>,
+ <strong>clock_name</strong> <var>wake_time</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt><var>clock_name</var>
+<dd>
+[in clock-name send right] The name (or control) port for the clock.
+<p>
+<dt><var>sleep_type</var>
+<dd>
+[in scalar] How to interpret the sleep_time value:
+ <dl>
+<p>
+<dt><strong>TIME_RELATIVE</strong>
+<dd>
+Interpret the sleep time as relative to the current time.
+<p>
+<dt><strong>TIME_ABSOLUTE</strong>
+<dd>
+Interpret the sleep time as an absolute time.
+ </dl>
+<p>
+<dt><var>sleep_time</var>
+<dd>
+[in structure] The time when the sleep is to terminate.
+<p>
+<dt><var>wake_time</var>
+<dd>
+[out structure] The actual (absolute) time at which the sleep terminated.
+</dl>
+
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>clock_sleep</strong> system trap delays the invoking
+thread until a specified time. This sleep may be aborted by
+<strong>thread_abort</strong>. Not all clocks provide this service
+but the REALTIME clock must.
+<p>
+If the specified time is in the past, the call returns immediately
+with the wake time being the current time. If the clock's time is
+changed (<strong>clock_set_time</strong>), the sleep will be
+interrupted. The thread will waken at the service time nearest the
+specified sleep time as governed by the current clock alarm
+resolution.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_FAILURE</strong>
+<dd>
+The clock does not support a sleep service.
+<p>
+<dt> <strong>KERN_ABORTED</strong>
+<dd>
+The sleep was interrupted by thread_abort or terminated via use of
+clock_set_time.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>,
+<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>,
+<a href="clock_get_time.html"><strong>clock_get_time</strong></a>,
+<a href="clock_alarm.html"><strong>clock_alarm</strong></a>,
+<a href="clock_set_time.html"><strong>clock_set_time</strong></a>,
+<a href="thread_abort.html"><strong>thread_abort</strong></a>,
+<p>
+Data Structures:
+tvalspec.
-<h2>default_pager_add_segment</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Add additional backing storage for a default pager.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include< mach/default_pager_object.h></strong>
\r\r<strong>kern_return_t default_pager_add_segment</strong>
\r <strong>(mach_port_t</strong> <var>backing_store</var>,
\r <strong>mach_port_t</strong> <var>device</var>,
\r <strong>recnum_t</strong> <var>offset</var>,
\r <strong>recnum_t</strong> <var>count</var>,
\r <strong>int</strong> <var>record_size</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>backing_store</var>
\r<dd>
\r[in backing store (receive) right] The backing store port.
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device port] The port for the device containing the backing storage
\rpartition.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar] The offset, in <var>record_size units</var>, to the beginning of the
\rbacking storage on the device.
\r<p>
\r<dt> <var>count</var>
\r<dd>
\r[in scalar] The number of <var>record_size</var> units
\rin the partition/segment.
\r<p>
\r<dt> <var>record_size</var>
\r<dd>
\r[in scalar] The size, in bytes, of the storage device record.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>default_pager_add_segment</strong> function is called to add a partition to
\ra default pager's backing storage (i.e. expand the amount of backing
\rstorage available to a memory manager). The kernel does not make
\rthis call itself (which is why it can be a synchronous call); this
\rrequest is only issued by tasks holding the backing store port,
\rcreated with <strong>default_pager_backing_store_create</strong>, for a default memory
\rmanager.
\rThe result is that the pager may use count records on device starting
\rat offset for paging, and each record is record_size bytes in length
\r(note that the device_* calls are, or can be, record oriented).
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_FAILURE</strong>
\r<dd>
\rThe default pager does not support this operation.
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe <var>backing_store</var> port does not represent a valid backing store or the
\rspecified segment overlaps an existing partition.
\r<p>
\r<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
\r<dd>
\rThe default pager is unable to allocate internal resources
\r to manage the new backing storage.
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe operation was successful.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="DP_backing_store_create.html"><strong>default_pager_backing_store_create</strong></a>,
\r<a href="DP_backing_store_delete.html"><strong>default_pager_backing_store_delete</strong></a>,
\r<a href="DP_backing_store_info.html"><strong>default_pager_backing_store_info</strong></a>.
\r\ No newline at end of file
+<h2>default_pager_add_segment</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Add additional backing storage for a default pager.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include< mach/default_pager_object.h></strong>
+
+<strong>kern_return_t default_pager_add_segment</strong>
+ <strong>(mach_port_t</strong> <var>backing_store</var>,
+ <strong>mach_port_t</strong> <var>device</var>,
+ <strong>recnum_t</strong> <var>offset</var>,
+ <strong>recnum_t</strong> <var>count</var>,
+ <strong>int</strong> <var>record_size</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>backing_store</var>
+<dd>
+[in backing store (receive) right] The backing store port.
+<p>
+<dt> <var>device</var>
+<dd>
+[in device port] The port for the device containing the backing storage
+partition.
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar] The offset, in <var>record_size units</var>, to the beginning of the
+backing storage on the device.
+<p>
+<dt> <var>count</var>
+<dd>
+[in scalar] The number of <var>record_size</var> units
+in the partition/segment.
+<p>
+<dt> <var>record_size</var>
+<dd>
+[in scalar] The size, in bytes, of the storage device record.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>default_pager_add_segment</strong> function is called to add a partition to
+a default pager's backing storage (i.e. expand the amount of backing
+storage available to a memory manager). The kernel does not make
+this call itself (which is why it can be a synchronous call); this
+request is only issued by tasks holding the backing store port,
+created with <strong>default_pager_backing_store_create</strong>, for a default memory
+manager.
+The result is that the pager may use count records on device starting
+at offset for paging, and each record is record_size bytes in length
+(note that the device_* calls are, or can be, record oriented).
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_FAILURE</strong>
+<dd>
+The default pager does not support this operation.
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The <var>backing_store</var> port does not represent a valid backing store or the
+specified segment overlaps an existing partition.
+<p>
+<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
+<dd>
+The default pager is unable to allocate internal resources
+ to manage the new backing storage.
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The operation was successful.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="DP_backing_store_create.html"><strong>default_pager_backing_store_create</strong></a>,
+<a href="DP_backing_store_delete.html"><strong>default_pager_backing_store_delete</strong></a>,
+<a href="DP_backing_store_info.html"><strong>default_pager_backing_store_info</strong></a>.
-<h2>default_pager_info</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Furnish caller with information about the pager's paging partition.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t default_pager_info</strong>
\r <strong>(mach_port_t</strong> <var>pager</var>,
\r <strong>default_pager_info_t</strong> <var>info</var><strong>);</strong>
\r\r\r<strong>kern_return_t seqnos_default_pager_info</strong>
\r <strong>(mach_port_t</strong> <var>pager</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>default_pager_info_t</strong> <var>*info</var><strong>);</strong>
\r\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>pager</var>
\r<dd>
\r[in default-pager (receive) right]
\rThe default memory manager service
\rport.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the pager
\rport.
\r<p>
\r<dt> <var>info</var>
\r<dd>
\r[out structure]
\rTotal and free space consumption.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>default_pager_info</strong> function is called as the result
\rof a message requesting
\rthat the default memory manager return information concerning the default
\rpager's paging partitions. The kernel does not make this call
\ritself (which is why it
\rcan be a synchronous call); this request is only issued by (privileged) tasks
\rholding the default memory manager port.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="HD_memory_manager.html"><strong>vm_set_default_memory_manager</strong></a>,
\r<a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>,
\r<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>.
\r<p>
\rData Structures:
\r<a href="default_pager_info.html"><strong>default_pager_info</strong></a>.
\r\ No newline at end of file
+<h2>default_pager_info</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Furnish caller with information about the pager's paging partition.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t default_pager_info</strong>
+ <strong>(mach_port_t</strong> <var>pager</var>,
+ <strong>default_pager_info_t</strong> <var>info</var><strong>);</strong>
+
+
+<strong>kern_return_t seqnos_default_pager_info</strong>
+ <strong>(mach_port_t</strong> <var>pager</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>default_pager_info_t</strong> <var>*info</var><strong>);</strong>
+
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>pager</var>
+<dd>
+[in default-pager (receive) right]
+The default memory manager service
+port.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the pager
+port.
+<p>
+<dt> <var>info</var>
+<dd>
+[out structure]
+Total and free space consumption.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>default_pager_info</strong> function is called as the result
+of a message requesting
+that the default memory manager return information concerning the default
+pager's paging partitions. The kernel does not make this call
+itself (which is why it
+can be a synchronous call); this request is only issued by (privileged) tasks
+holding the default memory manager port.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="HD_memory_manager.html"><strong>vm_set_default_memory_manager</strong></a>,
+<a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>,
+<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>.
+<p>
+Data Structures:
+<a href="default_pager_info.html"><strong>default_pager_info</strong></a>.
-<h2>device_close</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - De-establish a connection to a device.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include< device/device.h></strong>
\r\r<strong>kern_return_t device_close</strong>
\r <strong>(mach_port_t</strong> <var>device</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right]
\rA device port to the device to be closed.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_close</strong> function destroys the associated device
\rport. The open count
\rfor the named device is decremented. If this count reaches zero, the close
\roperation of the device driver is invoked, closing the device.
\r<h3>NOTES</h3>
\r<p>
\r<strong>device_close</strong> will destroy any mapped device windows
\robtained through this
\rdevice port.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>D_NO_SUCH_DEVICE</strong>
\r<dd>
\rNo device with that name, or the device is not operational.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_open.html"><strong>device_open</strong></a>.
\r\ No newline at end of file
+<h2>device_close</h2>
+<hr>
+<p>
+<strong>Function</strong> - De-establish a connection to a device.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include< device/device.h></strong>
+
+<strong>kern_return_t device_close</strong>
+ <strong>(mach_port_t</strong> <var>device</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right]
+A device port to the device to be closed.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_close</strong> function destroys the associated device
+port. The open count
+for the named device is decremented. If this count reaches zero, the close
+operation of the device driver is invoked, closing the device.
+<h3>NOTES</h3>
+<p>
+<strong>device_close</strong> will destroy any mapped device windows
+obtained through this
+device port.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>D_NO_SUCH_DEVICE</strong>
+<dd>
+No device with that name, or the device is not operational.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_open.html"><strong>device_open</strong></a>.
-<h2>device_get_status</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return the current device status.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include< device/device.h></strong>
\r\r<strong>kern_return_t device_get_status</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>dev_flavor_t</strong> <var>flavor</var>,
\r <strong>dev_status_t</strong> <var>status</var>,
\r <strong>mach_msg_type_number_t</strong> <var>*status_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right]
\rA device port to the device to be interrogated.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of status information requested.
\r<p>
\r<dt> <var>status</var>
\r<dd>
\r[out array of natural-sized units]
\rThe returned device status.
\r<p>
\r<dt> <var>status_count</var>
\r<dd>
\r[pointer to in/out scalar]
\rOn input, the reserved size of <var>status</var>; on
\routput, the size of the returned device status (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_get_status</strong> function returns status information
\rpertaining to an open device. The possible values for <var>flavor</var> as well
\ras the meaning of the returned status information is device dependent.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>D_DEVICE_DOWN</strong>
\r<dd>
\rDevice has been shut down
\r<p>
\r<dt> <strong>D_NO_SUCH_DEVICE</strong>
\r<dd>
\rNo device with that name, or the device is not operational.
\r<p>
\r<dt> <strong>D_OUT_OF_BAND</strong>
\r<dd>
\rOut-of-band condition occurred on device (such as typing \*L<Ctrl>-C\*O)
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_set_status.html"><strong>device_set_status</strong></a>.
\r\ No newline at end of file
+<h2>device_get_status</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return the current device status.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include< device/device.h></strong>
+
+<strong>kern_return_t device_get_status</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>dev_flavor_t</strong> <var>flavor</var>,
+ <strong>dev_status_t</strong> <var>status</var>,
+ <strong>mach_msg_type_number_t</strong> <var>*status_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right]
+A device port to the device to be interrogated.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of status information requested.
+<p>
+<dt> <var>status</var>
+<dd>
+[out array of natural-sized units]
+The returned device status.
+<p>
+<dt> <var>status_count</var>
+<dd>
+[pointer to in/out scalar]
+On input, the reserved size of <var>status</var>; on
+output, the size of the returned device status (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_get_status</strong> function returns status information
+pertaining to an open device. The possible values for <var>flavor</var> as well
+as the meaning of the returned status information is device dependent.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>D_DEVICE_DOWN</strong>
+<dd>
+Device has been shut down
+<p>
+<dt> <strong>D_NO_SUCH_DEVICE</strong>
+<dd>
+No device with that name, or the device is not operational.
+<p>
+<dt> <strong>D_OUT_OF_BAND</strong>
+<dd>
+Out-of-band condition occurred on device (such as typing \*L<Ctrl>-C\*O)
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_set_status.html"><strong>device_set_status</strong></a>.
-<h2>device_map</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Establish the specified device's memory manager.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include< device/device.h></strong>
\r\r<strong>kern_return_t device_map</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>vm_prot_t</strong> <var>prot</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>mach_port_t</strong> <var>mem_obj_t</var>,
\r <strong>boolean_t</strong> <var>unmap</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right]
\rA device port to the device to be mapped.
\r<p>
\r<dt> <var>prot</var>
\r<dd>
\r[in scalar]
\rProtection for the device memory.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar]
\r15~Offset in memory object.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe size of the device memory object.
\r<p>
\r<dt> <var>pager</var>
\r<dd>
\r[out memory-object send right]
\rThe returned memory
\robject representative port to a memory manager that represents the
\rdevice.
\r<p>
\r<dt> <var>unmap</var>
\r<dd>
\rUnused.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_map</strong> function establishes a memory manager that presents a
\rmemory object representing a device. The resulting port is suitable
\rfor use as the
\rmemory manager port in a <strong>vm_map</strong> call. This call is device dependent.
\r<h3>NOTES</h3>
\r<p>
\rPort rights are maintained as follows:
\r<ul>
\r<li>
\rMemory object port: the
\rdevice memory manager has all rights.
\r<li>
\rMemory cache control port: the device memory manager has only send rights.
\r</ul>
\r<p>
\rRegardless of how the object is created, the control port is created by
\rthe kernel and passed through the memory management interface.
\r<p>
\rIf the device port used is restricted to use by a single identity,
\rthe generated
\rrepresentative port will be likewise restricted.
\r<h3>CAUTIONS</h3>
\r<p>
\rThe device memory manager assumes that access to its memory objects will not
\rbe propagated to more that one host, and therefore provides no consistency
\rguarantees beyond those made by the kernel.
\r<p>
\rIn the event that more than one host attempts to use a device
\rmemory object, the
\rdevice memory manager will only record the last set of port names. Currently,
\rthe device memory manager assumes that its clients adhere to
\rthe initialization
\rand termination protocols in the memory management interface; otherwise, port
\rrights or out-of-line memory from erroneous messages may be allowed to
\raccumulate.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>D_DEVICE_DOWN</strong>
\r<dd>
\rDevice has been shut down
\r<p>
\r<dt> <strong>D_NO_SUCH_DEVICE</strong>
\r<dd>
\rNo device with that name, or the device is not operational.
\r<p>
\r<dt> <strong>D_READ_ONLY</strong>
\r<dd>
\rData cannot be written to this device.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_map.html"><strong>vm_map</strong></a>.
\r\ No newline at end of file
+<h2>device_map</h2>
+<hr>
+<p>
+<strong>Function</strong> - Establish the specified device's memory manager.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include< device/device.h></strong>
+
+<strong>kern_return_t device_map</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>vm_prot_t</strong> <var>prot</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>mach_port_t</strong> <var>mem_obj_t</var>,
+ <strong>boolean_t</strong> <var>unmap</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right]
+A device port to the device to be mapped.
+<p>
+<dt> <var>prot</var>
+<dd>
+[in scalar]
+Protection for the device memory.
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar]
+15~Offset in memory object.
+<p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The size of the device memory object.
+<p>
+<dt> <var>pager</var>
+<dd>
+[out memory-object send right]
+The returned memory
+object representative port to a memory manager that represents the
+device.
+<p>
+<dt> <var>unmap</var>
+<dd>
+Unused.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_map</strong> function establishes a memory manager that presents a
+memory object representing a device. The resulting port is suitable
+for use as the
+memory manager port in a <strong>vm_map</strong> call. This call is device dependent.
+<h3>NOTES</h3>
+<p>
+Port rights are maintained as follows:
+<ul>
+<li>
+Memory object port: the
+device memory manager has all rights.
+<li>
+Memory cache control port: the device memory manager has only send rights.
+</ul>
+<p>
+Regardless of how the object is created, the control port is created by
+the kernel and passed through the memory management interface.
+<p>
+If the device port used is restricted to use by a single identity,
+the generated
+representative port will be likewise restricted.
+<h3>CAUTIONS</h3>
+<p>
+The device memory manager assumes that access to its memory objects will not
+be propagated to more that one host, and therefore provides no consistency
+guarantees beyond those made by the kernel.
+<p>
+In the event that more than one host attempts to use a device
+memory object, the
+device memory manager will only record the last set of port names. Currently,
+the device memory manager assumes that its clients adhere to
+the initialization
+and termination protocols in the memory management interface; otherwise, port
+rights or out-of-line memory from erroneous messages may be allowed to
+accumulate.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>D_DEVICE_DOWN</strong>
+<dd>
+Device has been shut down
+<p>
+<dt> <strong>D_NO_SUCH_DEVICE</strong>
+<dd>
+No device with that name, or the device is not operational.
+<p>
+<dt> <strong>D_READ_ONLY</strong>
+<dd>
+Data cannot be written to this device.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="vm_map.html"><strong>vm_map</strong></a>.
-<h2>device_open</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Establish a connection to a device.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<device/device.h></strong>
\r\r<strong>kern_return_t device_open</strong>
\r <strong>(mach_port_t</strong> <var>master_port</var>,
\r <strong>mach_port_t</strong> <var>ledger</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>security_token_t</strong> <var>security_id</var>,
\r <strong>dev_name_t</strong> <var>name</var>,
\r <strong>mach_port_t</strong> <var>device</var><strong>);</strong>
\r\r\r<strong>#include<device/device_request.h></strong>
\r\r<strong>kern_return_t device_open_request</strong>
\r <strong>(mach_port_t</strong> <var>master_port</var>,
\r <strong>mach_port_t</strong> <var>reply_port</var>,
\r <strong>mach_port_t</strong> <var>ledger</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>security_token_t</strong> <var>security_id</var>,
\r <strong>dev_name_t</strong> <var>name</var><strong>);</strong>
\r\r\r<strong>kern_return_t ds_device_open_reply</strong>
\r <strong>(mach_port_t</strong> <var>reply_port</var>,
\r <strong>kern_return_t</strong> <var>return_code</var>,
\r <strong>mach_port_t</strong> <var>device</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>master_port</var>
\r<dd>
\r[in device-master send right]
\rThe master device port. This port is
\rprovided to the bootstrap task.
\r<p>
\r<dt> <var>reply_port</var>
\r<dd>
\r[in reply receive (to be converted to send-once) right]
\rThe port to
\rwhich a reply is to be sent when the device is open.
\r<p>
\r<dt> <var>ledger</var>
\r<dd>
\r[pointer to a ledger send right]
\rResource ledger from which the device will draw its resources.
\r<p>
\r<dt> <var>mode</var>
\r<dd>
\r[in scalar]
\rOpening mode. This is the bit-wise <strong>OR</strong> of the following
\rvalues:
\r<dl>
\r<p>
\r<dt> <strong>D_READ</strong>
\r<dd>
\rRead access
\r<p>
\r<dt> <strong>D_WRITE</strong>
\r<dd>
\rWrite access
\r<p>
\r<dt> <strong>D_NODELAY</strong>
\r<dd>
\rDo not delay on open
\r</dl>
\r<p>
\r<dt> <var>security_id</var>
\r<dd>
\r[in scalar]
\rThe security ID that tasks attempting to use this device port
\rmust have. A zero value indicates all identities.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[pointer to in array of <var>char</var>]
\rName of the device to open.
\r<p>
\r<dt> <var>return_code</var>
\r<dd>
\r[in scalar]
\rStatus of the open.
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[out device send right, in for asynchronous form]
\rThe returned device
\rport.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_open</strong> function opens a device object. The
\ropen operation of the
\rdevice is invoked, if the device is not already open. The open
\rcount for the device
\ris incremented. Each open for a device returns a port, the allowed
\roperations upon which being governed by <var>mode</var>. The port is not
\rdistinct.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_close.html"><strong>device_close</strong></a>,
\r<a href="device_reply_server.html"><strong>device_reply_server</strong></a>.
\r\ No newline at end of file
+<h2>device_open</h2>
+<hr>
+<p>
+<strong>Function</strong> - Establish a connection to a device.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<device/device.h></strong>
+
+<strong>kern_return_t device_open</strong>
+ <strong>(mach_port_t</strong> <var>master_port</var>,
+ <strong>mach_port_t</strong> <var>ledger</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>security_token_t</strong> <var>security_id</var>,
+ <strong>dev_name_t</strong> <var>name</var>,
+ <strong>mach_port_t</strong> <var>device</var><strong>);</strong>
+
+
+<strong>#include<device/device_request.h></strong>
+
+<strong>kern_return_t device_open_request</strong>
+ <strong>(mach_port_t</strong> <var>master_port</var>,
+ <strong>mach_port_t</strong> <var>reply_port</var>,
+ <strong>mach_port_t</strong> <var>ledger</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>security_token_t</strong> <var>security_id</var>,
+ <strong>dev_name_t</strong> <var>name</var><strong>);</strong>
+
+
+<strong>kern_return_t ds_device_open_reply</strong>
+ <strong>(mach_port_t</strong> <var>reply_port</var>,
+ <strong>kern_return_t</strong> <var>return_code</var>,
+ <strong>mach_port_t</strong> <var>device</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>master_port</var>
+<dd>
+[in device-master send right]
+The master device port. This port is
+provided to the bootstrap task.
+<p>
+<dt> <var>reply_port</var>
+<dd>
+[in reply receive (to be converted to send-once) right]
+The port to
+which a reply is to be sent when the device is open.
+<p>
+<dt> <var>ledger</var>
+<dd>
+[pointer to a ledger send right]
+Resource ledger from which the device will draw its resources.
+<p>
+<dt> <var>mode</var>
+<dd>
+[in scalar]
+Opening mode. This is the bit-wise <strong>OR</strong> of the following
+values:
+<dl>
+<p>
+<dt> <strong>D_READ</strong>
+<dd>
+Read access
+<p>
+<dt> <strong>D_WRITE</strong>
+<dd>
+Write access
+<p>
+<dt> <strong>D_NODELAY</strong>
+<dd>
+Do not delay on open
+</dl>
+<p>
+<dt> <var>security_id</var>
+<dd>
+[in scalar]
+The security ID that tasks attempting to use this device port
+must have. A zero value indicates all identities.
+<p>
+<dt> <var>name</var>
+<dd>
+[pointer to in array of <var>char</var>]
+Name of the device to open.
+<p>
+<dt> <var>return_code</var>
+<dd>
+[in scalar]
+Status of the open.
+<p>
+<dt> <var>device</var>
+<dd>
+[out device send right, in for asynchronous form]
+The returned device
+port.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_open</strong> function opens a device object. The
+open operation of the
+device is invoked, if the device is not already open. The open
+count for the device
+is incremented. Each open for a device returns a port, the allowed
+operations upon which being governed by <var>mode</var>. The port is not
+distinct.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_close.html"><strong>device_close</strong></a>,
+<a href="device_reply_server.html"><strong>device_reply_server</strong></a>.
-<h2>device_read</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Read a sequence of bytes from a specific device.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<device/device.h></strong>
\r\r<strong>kern_return_t device_read</strong>
\r <strong>(device_t</strong> <var>device</var>,
\r <strong>mach_port_t</strong> <var>reply_port</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>recnum_t</strong> <var>recnum</var>,
\r <strong>io_buf_len_t</strong> <var>bytes_wanted</var>,
\r <strong>io_buf_ptr_t</strong> <var>io_buf_ptr_t</var>,
\r <strong>mach_msg_type_number_t</strong> <var>mach_msg_type_number_t</var><strong>);</strong>
\r\r\r<strong>#include<device/device_request.h></strong>
\r\r<strong>kern_return_t device_read_request</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>mach_port_t</strong> <var>reply_port</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>recnum_t</strong> <var>recnum</var>,
\r <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong>
\r\r\r\r<strong>kern_return_t ds_device_read_reply</strong>
\r <strong>(mach_port_t</strong> <var>reply_port</var>,
\r <strong>kern_return_t</strong> <var>return_code</var>,
\r <strong>io_buf_ptr_t</strong> <var>data</var>,
\r <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right]
\rA device port to the device to be read.
\r<p>
\r<dt> <var>reply_port</var>
\r<dd>
\r[in reply receive (to be converted to send-once) right]
\rThe port to
\rwhich the reply message is to be sent.
\r<p>
\r<dt> <var>mode</var>
\r<dd>
\r[in scalar]
\rI/O mode value. Meaningful options are:
\r<dl>
\r<p>
\r<dt> <strong>D_NOWAIT</strong>
\r<dd>
\rDo not wait if data is unavailable.
\r</dl>
\r<p>
\r<dt> <var>recnum</var>
\r<dd>
\r[in scalar]
\rRecord number to be read.
\r<p>
\r<dt> <var>bytes_wanted</var>
\r<dd>
\r[in scalar]
\rSize of data transfer.
\r<p>
\r<dt> <var>return_code</var>
\r<dd>
\r[in scalar]
\rThe return status code from the read.
\r<p>
\r<dt> <var>data</var>
\r<dd>
\r[out pointer to dynamic array of bytes, in for asynchronous form]
\rReturned data bytes.
\r<p>
\r<dt> <var>data_count</var>
\r<dd>
\r[out scalar, in for asynchronous form]
\rNumber of returned data bytes.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_read</strong> function reads a sequence of bytes
\rfrom a device object. The
\rmeaning of <var>recnum</var> as well as the specific operation performed is device
\rdependent.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_read_inband.html"><strong>device_read_inband</strong></a>,
\r<a href="device_read_overwrite.html"><strong>device_read_overwrite</strong></a>,
\r<a href="device_reply_server.html"><strong>device_reply_server</strong></a>.
\r\ No newline at end of file
+<h2>device_read</h2>
+<hr>
+<p>
+<strong>Function</strong> - Read a sequence of bytes from a specific device.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<device/device.h></strong>
+
+<strong>kern_return_t device_read</strong>
+ <strong>(device_t</strong> <var>device</var>,
+ <strong>mach_port_t</strong> <var>reply_port</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>recnum_t</strong> <var>recnum</var>,
+ <strong>io_buf_len_t</strong> <var>bytes_wanted</var>,
+ <strong>io_buf_ptr_t</strong> <var>io_buf_ptr_t</var>,
+ <strong>mach_msg_type_number_t</strong> <var>mach_msg_type_number_t</var><strong>);</strong>
+
+
+<strong>#include<device/device_request.h></strong>
+
+<strong>kern_return_t device_read_request</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>mach_port_t</strong> <var>reply_port</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>recnum_t</strong> <var>recnum</var>,
+ <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong>
+
+
+
+<strong>kern_return_t ds_device_read_reply</strong>
+ <strong>(mach_port_t</strong> <var>reply_port</var>,
+ <strong>kern_return_t</strong> <var>return_code</var>,
+ <strong>io_buf_ptr_t</strong> <var>data</var>,
+ <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right]
+A device port to the device to be read.
+<p>
+<dt> <var>reply_port</var>
+<dd>
+[in reply receive (to be converted to send-once) right]
+The port to
+which the reply message is to be sent.
+<p>
+<dt> <var>mode</var>
+<dd>
+[in scalar]
+I/O mode value. Meaningful options are:
+<dl>
+<p>
+<dt> <strong>D_NOWAIT</strong>
+<dd>
+Do not wait if data is unavailable.
+</dl>
+<p>
+<dt> <var>recnum</var>
+<dd>
+[in scalar]
+Record number to be read.
+<p>
+<dt> <var>bytes_wanted</var>
+<dd>
+[in scalar]
+Size of data transfer.
+<p>
+<dt> <var>return_code</var>
+<dd>
+[in scalar]
+The return status code from the read.
+<p>
+<dt> <var>data</var>
+<dd>
+[out pointer to dynamic array of bytes, in for asynchronous form]
+Returned data bytes.
+<p>
+<dt> <var>data_count</var>
+<dd>
+[out scalar, in for asynchronous form]
+Number of returned data bytes.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_read</strong> function reads a sequence of bytes
+from a device object. The
+meaning of <var>recnum</var> as well as the specific operation performed is device
+dependent.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_read_inband.html"><strong>device_read_inband</strong></a>,
+<a href="device_read_overwrite.html"><strong>device_read_overwrite</strong></a>,
+<a href="device_reply_server.html"><strong>device_reply_server</strong></a>.
-<h2>device_read_async</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> - Read a sequence of bytes from a device object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t device_read_async</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>mach_port_t</strong> <var>queue</var>,
\r <strong>mach_port_t</strong> <var>request_id</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>recnum_t</strong> <var>recnum</var>,
\r <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right] A device port to the device to be read.
\r<p>
\r<dt> <var>queue</var>
\r<dd>
\r[in io_done queue send right] The port returned from
\rio_done_queue_create.
\r<p>
\r<dt> <var>request_id</var>
\r<dd>
\r[in send right] An unique request identifier that will be passed back as
\rpart of the io_done_result structure.
\r<p>
\r<dt> <var>mode</var>
\r<dd>
\r[in scalar] I/O mode value. Meaningful options are:
\r<p>
\r <dl>
\r<dt> <strong>D_NOWAIT</strong>
\r<dd>
\rDo not wait if data is unavailable.
\r </dl>
\r<p>
\r<dt> <var>recnum</var>
\r<dd>
\r[in scalar] Record number to be read.
\r<p>
\r<dt> <var>bytes_wanted</var>
\r<dd>
\r[in scalar] Size of data transfer.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_read_async</strong> interface enqueues a read operation for a
\rsequence of bytes from a device object. The meaning of recnum as well
\ras the specific operation performed is device dependent.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<strong>device_read_async</strong> returns only invalid parameter errors.
\r<dd>
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>,
\r<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>,
\r<a href="device_write_async.html"><strong>device_write_async</strong></a>,
\r<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>,
\r<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>.
\r\ No newline at end of file
+<h2>device_read_async</h2>
+<hr>
+<p>
+<strong>System Trap</strong> - Read a sequence of bytes from a device object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t device_read_async</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>mach_port_t</strong> <var>queue</var>,
+ <strong>mach_port_t</strong> <var>request_id</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>recnum_t</strong> <var>recnum</var>,
+ <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right] A device port to the device to be read.
+<p>
+<dt> <var>queue</var>
+<dd>
+[in io_done queue send right] The port returned from
+io_done_queue_create.
+<p>
+<dt> <var>request_id</var>
+<dd>
+[in send right] An unique request identifier that will be passed back as
+part of the io_done_result structure.
+<p>
+<dt> <var>mode</var>
+<dd>
+[in scalar] I/O mode value. Meaningful options are:
+<p>
+ <dl>
+<dt> <strong>D_NOWAIT</strong>
+<dd>
+Do not wait if data is unavailable.
+ </dl>
+<p>
+<dt> <var>recnum</var>
+<dd>
+[in scalar] Record number to be read.
+<p>
+<dt> <var>bytes_wanted</var>
+<dd>
+[in scalar] Size of data transfer.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_read_async</strong> interface enqueues a read operation for a
+sequence of bytes from a device object. The meaning of recnum as well
+as the specific operation performed is device dependent.
+<h3>RETURN VALUES</h3>
+<dl>
+<strong>device_read_async</strong> returns only invalid parameter errors.
+<dd>
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>,
+<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>,
+<a href="device_write_async.html"><strong>device_write_async</strong></a>,
+<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>,
+<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>.
-<h2>device_read_async_inband</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> - Read a sequence of bytes "inband" from a device object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t device_read_async_inband</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>mach_port_t</strong> <var>queue</var>,
\r <strong>mach_port_t</strong> <var>request_id</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>recnum_t</strong> <var>recnum</var>,
\r <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right] A device port to the device to be read.
\r<p>
\r<dt> <var>queue</var>
\r<dd>
\r[in io_done queue send right] The port returned from
\r<strong>io_done_queue_create</strong>.
\r<p>
\r<dt> <var>request_id</var>
\r<dd>
\r[in send right] An unique request identifier that will be passed back as
\rpart of the io_done_result structure.
\r<p>
\r<dt> <var>mode</var>
\r<dd>
\r[in scalar] I/O mode value. Meaningful options are:
\r<p>
\r <dl>
\r<dt> <strong>D_NOWAIT</strong>
\r<dd>
\rDo not wait if data is unavailable.
\r </dl>
\r<p>
\r<dt> <var>recnum</var>
\r<dd>
\r[in scalar] Record number to be read.
\r<p>
\r<dt> <var>bytes_wanted</var>
\r<dd>
\r[in scalar] Size of data transfer.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_read_async_inband</strong> function enqueues a read operation for a
\rsequence of bytes from a device object. The meaning of <var>recnum</var> as
\rwell as the specific operation performed is device dependent. This
\rcall differs from <strong>device_read_async</strong> in that the returned bytes are
\rreturned "inband" in the completion IPC message (in
\r<strong>io_done_result.qd_inline</strong>).
\r<h3>RETURN VALUES</h3>
\r<p>
\r<strong>device_read_async_inband</strong> returns only invalid parameter errors.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_read_async.html"><strong>device_read_async</strong></a>,
\r<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>,
\r<a href="device_write_async.html"><strong>device_write_async</strong></a>,
\r<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>,
\r<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>.
\r\ No newline at end of file
+<h2>device_read_async_inband</h2>
+<hr>
+<p>
+<strong>System Trap</strong> - Read a sequence of bytes "inband" from a device object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t device_read_async_inband</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>mach_port_t</strong> <var>queue</var>,
+ <strong>mach_port_t</strong> <var>request_id</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>recnum_t</strong> <var>recnum</var>,
+ <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right] A device port to the device to be read.
+<p>
+<dt> <var>queue</var>
+<dd>
+[in io_done queue send right] The port returned from
+<strong>io_done_queue_create</strong>.
+<p>
+<dt> <var>request_id</var>
+<dd>
+[in send right] An unique request identifier that will be passed back as
+part of the io_done_result structure.
+<p>
+<dt> <var>mode</var>
+<dd>
+[in scalar] I/O mode value. Meaningful options are:
+<p>
+ <dl>
+<dt> <strong>D_NOWAIT</strong>
+<dd>
+Do not wait if data is unavailable.
+ </dl>
+<p>
+<dt> <var>recnum</var>
+<dd>
+[in scalar] Record number to be read.
+<p>
+<dt> <var>bytes_wanted</var>
+<dd>
+[in scalar] Size of data transfer.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_read_async_inband</strong> function enqueues a read operation for a
+sequence of bytes from a device object. The meaning of <var>recnum</var> as
+well as the specific operation performed is device dependent. This
+call differs from <strong>device_read_async</strong> in that the returned bytes are
+returned "inband" in the completion IPC message (in
+<strong>io_done_result.qd_inline</strong>).
+<h3>RETURN VALUES</h3>
+<p>
+<strong>device_read_async_inband</strong> returns only invalid parameter errors.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_read_async.html"><strong>device_read_async</strong></a>,
+<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>,
+<a href="device_write_async.html"><strong>device_write_async</strong></a>,
+<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>,
+<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>.
-<h2>device_read_inband</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Read a sequence of bytes "inband" from a device object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<device/device.h></strong>
\r\r<strong>kern_return_t device_read_inband</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>recnum_t</strong> <var>recnum</var>,
\r <strong>io_buf_len_t</strong> <var>bytes_wanted</var>,
\r <strong>io_buf_ptr_inband_t</strong> <var>data</var>,
\r <strong>mach_msg_type_number_t</strong> <var>*data_count</var><strong>);</strong>
\r\r\r<strong>#include<device/device_request.h></strong>
\r\r<strong>kern_return_t device_read_request_inband</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>mach_port_t</strong> <var>reply_port</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>recnum_t</strong> <var>recnum</var>,
\r <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong>
\r\r\r<strong>kern_return_t ds_device_read_reply_inband</strong>
\r <strong>(mach_port_t</strong> <var>reply_port</var>,
\r <strong>kern_return_t</strong> <var>return_code</var>,
\r <strong>io_buf_ptr_inband_t</strong> <var>data</var>,
\r <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right]
\rA device port to the device to be read.
\r<p>
\r<dt> <var>reply_port</var>
\r<dd>
\r[in reply receive (to be converted to send-once) right]
\rThe port to
\rwhich the reply message is to be sent.
\r<p>
\r<dt> <var>mode</var>
\r<dd>
\r[in scalar]
\rI/O mode value. Meaningful options are:
\r<dl>
\r<p>
\r<dt> <strong>D_NOWAIT</strong>
\r<dd>
\rDo not wait if data is unavailable.
\r</dl>
\r<p>
\r<dt> <var>recnum</var>
\r<dd>
\r[in scalar]
\rRecord number to be read.
\r<p>
\r<dt> <var>bytes_wanted</var>
\r<dd>
\r[in scalar]
\rSize of data transfer.
\r<p>
\r<dt> <var>return_code</var>
\r<dd>
\r[in scalar]
\rThe return status code from the read.
\r<p>
\r<dt> <var>data</var>
\r<dd>
\r[out array of bytes, in for asynchronous form]
\rReturned data bytes.
\r<p>
\r<dt> <var>data_count</var>
\r<dd>
\r[out scalar, in for asynchronous form]
\rNumber of returned data bytes.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_read_inband</strong> function reads a sequence of bytes
\rfrom a device object. The
\rmeaning of <var>recnum</var> as well as the specific operation performed is device
\rdependent. This call differs from <strong>device_read</strong> in that
\rthe returned bytes are returned
\r"inband" in the reply IPC message.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_read.html"><strong>device_read</strong></a>,
\r<a href="device_read_overwrite.html"><strong>device_read_overwrite</strong></a>,
\r<a href="device_reply_server.html"><strong>device_reply_server</strong></a>.
\r\ No newline at end of file
+<h2>device_read_inband</h2>
+<hr>
+<p>
+<strong>Function</strong> - Read a sequence of bytes "inband" from a device object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<device/device.h></strong>
+
+<strong>kern_return_t device_read_inband</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>recnum_t</strong> <var>recnum</var>,
+ <strong>io_buf_len_t</strong> <var>bytes_wanted</var>,
+ <strong>io_buf_ptr_inband_t</strong> <var>data</var>,
+ <strong>mach_msg_type_number_t</strong> <var>*data_count</var><strong>);</strong>
+
+
+<strong>#include<device/device_request.h></strong>
+
+<strong>kern_return_t device_read_request_inband</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>mach_port_t</strong> <var>reply_port</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>recnum_t</strong> <var>recnum</var>,
+ <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong>
+
+
+<strong>kern_return_t ds_device_read_reply_inband</strong>
+ <strong>(mach_port_t</strong> <var>reply_port</var>,
+ <strong>kern_return_t</strong> <var>return_code</var>,
+ <strong>io_buf_ptr_inband_t</strong> <var>data</var>,
+ <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right]
+A device port to the device to be read.
+<p>
+<dt> <var>reply_port</var>
+<dd>
+[in reply receive (to be converted to send-once) right]
+The port to
+which the reply message is to be sent.
+<p>
+<dt> <var>mode</var>
+<dd>
+[in scalar]
+I/O mode value. Meaningful options are:
+<dl>
+<p>
+<dt> <strong>D_NOWAIT</strong>
+<dd>
+Do not wait if data is unavailable.
+</dl>
+<p>
+<dt> <var>recnum</var>
+<dd>
+[in scalar]
+Record number to be read.
+<p>
+<dt> <var>bytes_wanted</var>
+<dd>
+[in scalar]
+Size of data transfer.
+<p>
+<dt> <var>return_code</var>
+<dd>
+[in scalar]
+The return status code from the read.
+<p>
+<dt> <var>data</var>
+<dd>
+[out array of bytes, in for asynchronous form]
+Returned data bytes.
+<p>
+<dt> <var>data_count</var>
+<dd>
+[out scalar, in for asynchronous form]
+Number of returned data bytes.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_read_inband</strong> function reads a sequence of bytes
+from a device object. The
+meaning of <var>recnum</var> as well as the specific operation performed is device
+dependent. This call differs from <strong>device_read</strong> in that
+the returned bytes are returned
+"inband" in the reply IPC message.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_read.html"><strong>device_read</strong></a>,
+<a href="device_read_overwrite.html"><strong>device_read_overwrite</strong></a>,
+<a href="device_reply_server.html"><strong>device_reply_server</strong></a>.
-<h2>device_read_overwrite</h2>
\r<hr>
\r<p><strong>System Trap</strong> -- Read a sequence of bytes from a specific device into my address space.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r\r<strong>kern_return_t device_read_overwrite</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>recnum_t</strong> <var>recnum</var>,
\r <strong>io_buf_len_t</strong> <var>bytes_wanted</var>,
\r <strong>io_buf_pointer_t</strong> <var>data</var>,
\r <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong>
\r\r\r\r<strong>kern_return_t device_read_overwrite_request</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>mach_port_t</strong> <var>reply_port</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>recnum_t</strong> <var>recnum</var>,
\r <strong>io_buf_len_t</strong> <var>bytes_wanted</var>,
\r <strong>io_buf_pointer_t</strong> <var>data</var><strong>);</strong>
\r\r\r\r<strong>kern_return_t ds_device_read_reply_overwrite</strong>
\r <strong>(mach_port_t</strong> <var>reply_port</var>,
\r <strong>kern_return_t</strong> <var>return_code</var>,
\r <strong>io_buf_len_t</strong> <var>data_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right]
\rA device port to the device to be read.
\r<p>
\r<dt> <var>reply_port</var>
\r<dd>
\r[in reply receive (to be converted to send-once) right]
\rThe port to
\rwhich the reply message is to be sent.
\r<p>
\r<dt> <var>mode</var>
\r<dd>
\r[in scalar]
\rI/O mode value. Meaningful options are:
\r<dl>
\r<p>
\r<dt> <strong>D_NOWAIT</strong>
\r<dd>
\rDo not wait if data is unavailable.
\r</dl>
\r<p>
\r<dt> <var>recnum</var>
\r<dd>
\r[in scalar]
\rRecord number to be read.
\r<p>
\r<dt> <var>bytes_wanted</var>
\r<dd>
\r[in scalar]
\rSize of data transfer.
\r<p>
\r<dt> <var>return_code</var>
\r<dd>
\r[in scalar]
\rThe return status code from the read.
\r<p>
\r<dt> <var>data</var>
\r<dd>
\r[pointer to in array of bytes]
\rData buffer to be overwritten.
\r<p>
\r<dt> <var>data_count</var>
\r<dd>
\r[out scalar, in for asynchronous form]
\rNumber of returned data bytes.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_read_overwrite</strong> system trap reads a sequence
\rof bytes from a
\rdevice object directly into the caller's address space. The
\rmeaning of <var>recnum</var> as
\rwell as the specific operation performed is device dependent.
\r<h3>NOTES</h3>
\r<p>
\rThe <strong>device_read_overwrite_request</strong> and <strong>device_read_reply_overwrite</strong>
\rcalls may be removed from the interface in favor of new asynchronous support.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_read.html"><strong>device_read</strong></a>,
\r<a href="device_read_inband.html"><strong>device_read_inband</strong></a>,
\r<a href="device_reply_server.html"><strong>device_reply_server</strong></a>.
\r\ No newline at end of file
+<h2>device_read_overwrite</h2>
+<hr>
+<p><strong>System Trap</strong> -- Read a sequence of bytes from a specific device into my address space.
+<h3>SYNOPSIS</h3>
+<pre>
+
+<strong>kern_return_t device_read_overwrite</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>recnum_t</strong> <var>recnum</var>,
+ <strong>io_buf_len_t</strong> <var>bytes_wanted</var>,
+ <strong>io_buf_pointer_t</strong> <var>data</var>,
+ <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong>
+
+
+
+<strong>kern_return_t device_read_overwrite_request</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>mach_port_t</strong> <var>reply_port</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>recnum_t</strong> <var>recnum</var>,
+ <strong>io_buf_len_t</strong> <var>bytes_wanted</var>,
+ <strong>io_buf_pointer_t</strong> <var>data</var><strong>);</strong>
+
+
+
+<strong>kern_return_t ds_device_read_reply_overwrite</strong>
+ <strong>(mach_port_t</strong> <var>reply_port</var>,
+ <strong>kern_return_t</strong> <var>return_code</var>,
+ <strong>io_buf_len_t</strong> <var>data_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right]
+A device port to the device to be read.
+<p>
+<dt> <var>reply_port</var>
+<dd>
+[in reply receive (to be converted to send-once) right]
+The port to
+which the reply message is to be sent.
+<p>
+<dt> <var>mode</var>
+<dd>
+[in scalar]
+I/O mode value. Meaningful options are:
+<dl>
+<p>
+<dt> <strong>D_NOWAIT</strong>
+<dd>
+Do not wait if data is unavailable.
+</dl>
+<p>
+<dt> <var>recnum</var>
+<dd>
+[in scalar]
+Record number to be read.
+<p>
+<dt> <var>bytes_wanted</var>
+<dd>
+[in scalar]
+Size of data transfer.
+<p>
+<dt> <var>return_code</var>
+<dd>
+[in scalar]
+The return status code from the read.
+<p>
+<dt> <var>data</var>
+<dd>
+[pointer to in array of bytes]
+Data buffer to be overwritten.
+<p>
+<dt> <var>data_count</var>
+<dd>
+[out scalar, in for asynchronous form]
+Number of returned data bytes.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_read_overwrite</strong> system trap reads a sequence
+of bytes from a
+device object directly into the caller's address space. The
+meaning of <var>recnum</var> as
+well as the specific operation performed is device dependent.
+<h3>NOTES</h3>
+<p>
+The <strong>device_read_overwrite_request</strong> and <strong>device_read_reply_overwrite</strong>
+calls may be removed from the interface in favor of new asynchronous support.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_read.html"><strong>device_read</strong></a>,
+<a href="device_read_inband.html"><strong>device_read_inband</strong></a>,
+<a href="device_reply_server.html"><strong>device_reply_server</strong></a>.
-<h2>device_reply_server</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Handle incoming data from kernel device driver.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>boolean_t device_reply_server</strong>
\r <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
\r <strong>mach_msg_header_t</strong> <var>reply_msg</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>request_msg</var>
\r<dd>
\r[pointer to in structure]
\rThe device driver message received from the
\rkernel.
\r<p>
\r<dt> <var>reply_msg</var>
\r<dd>
\r[out structure]
\rA reply message. No messages from a device driver
\rexpect a direct reply, so this field is not used.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_reply_server</strong> function is the MIG generated server handling
\rfunction to handle messages from kernel device drivers. Such
\rmessages were sent in response to the various
\r<strong>device_</strong>...<strong>_request</strong>...
\rcalls. It is assumed when using
\rthose calls that some task is listening for reply messages on the port named as a
\rreply port to those calls. The <strong>device_reply_server</strong>
\rfunction performs all
\rnecessary argument handling for a kernel message and calls one
\rof the device server functions to interpret the message.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>TRUE</strong>
\r<dd>
\rThe message was handled and the appropriate function was called.
\r<p>
\r<dt> <strong>FALSE</strong>
\r<dd>
\rThe message did not apply to this device handler interface and no other
\raction was taken.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_open.html"><strong>ds_device_open_reply<strong></a>,
\r<a href="device_write.html"><strong>ds_device_write_reply<strong></a>,
\r<a href="device_write_inband.html"><strong>ds_device_write_reply_inband<strong></a>,
\r<a href="device_read.html"><strong>ds_device_read_reply<strong></a>,
\r<a href="device_read_inband.html"><strong>ds_device_read_reply_inband<strong></a>,
\r<a href="device_read_overwrite.html"><strong>ds_device_read_reply_overwrite<strong></a>.
\r\ No newline at end of file
+<h2>device_reply_server</h2>
+<hr>
+<p>
+<strong>Function</strong> - Handle incoming data from kernel device driver.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>boolean_t device_reply_server</strong>
+ <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
+ <strong>mach_msg_header_t</strong> <var>reply_msg</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>request_msg</var>
+<dd>
+[pointer to in structure]
+The device driver message received from the
+kernel.
+<p>
+<dt> <var>reply_msg</var>
+<dd>
+[out structure]
+A reply message. No messages from a device driver
+expect a direct reply, so this field is not used.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_reply_server</strong> function is the MIG generated server handling
+function to handle messages from kernel device drivers. Such
+messages were sent in response to the various
+<strong>device_</strong>...<strong>_request</strong>...
+calls. It is assumed when using
+those calls that some task is listening for reply messages on the port named as a
+reply port to those calls. The <strong>device_reply_server</strong>
+function performs all
+necessary argument handling for a kernel message and calls one
+of the device server functions to interpret the message.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>TRUE</strong>
+<dd>
+The message was handled and the appropriate function was called.
+<p>
+<dt> <strong>FALSE</strong>
+<dd>
+The message did not apply to this device handler interface and no other
+action was taken.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_open.html"><strong>ds_device_open_reply<strong></a>,
+<a href="device_write.html"><strong>ds_device_write_reply<strong></a>,
+<a href="device_write_inband.html"><strong>ds_device_write_reply_inband<strong></a>,
+<a href="device_read.html"><strong>ds_device_read_reply<strong></a>,
+<a href="device_read_inband.html"><strong>ds_device_read_reply_inband<strong></a>,
+<a href="device_read_overwrite.html"><strong>ds_device_read_reply_overwrite<strong></a>.
-<h2>device_set_filter</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Name an input filter for a device.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include< device/device.h></strong>
\r<strong>#include< device/net_status.h></strong>
\r\r<strong>kern_return_t device_set_filter</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>mach_port_t</strong> <var>receive_port</var>,
\r <strong>mach_msg_type_name_t</strong> <var>receive_port_type</var>,
\r <strong>int</strong> <var>priority</var>,
\r <strong>filter_array_t</strong> <var>filter</var>,
\r <strong>mach_msg_type_number_t</strong> <var>filter_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right]
\rA device port
\r<p>
\r<dt> <var>receive_port</var>
\r<dd>
\r[in filter send or receive (to be converted to send) right]
\rThe port to
\rreceive the input data that is selected by the filter.
\r<p>
\r<dt> <var>receive_port_type</var>
\r<dd>
\r[in scalar]
\rIPC type of the send right provided to the device; either
\r<strong>MACH_MSG_TYPE_MAKE_SEND</strong>, <strong>MACH_MSG_TYPE_MOVE_SEND</strong>,
\ror <strong>MACH_MSG_TYPE_COPY_SEND</strong>.
\r<p>
\r<dt> <var>priority</var>
\r<dd>
\r[in scalar]
\rUsed to order multiple receivers in an implementation
\rdependent way.
\r<p>
\r<dt> <var>filter</var>
\r<dd>
\r[pointer to in array of <var>filter_t</var>]
\rThe address of an array of filter values.
\r<p>
\r<dt> <var>filter_count</var>
\r<dd>
\r[in scalar]
\rThe size of the <var>filter</var> array (in 16-bit values).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_set_filter</strong> function provides a means by
\rwhich selected data
\rappearing at a device interface can be selected and routed to
\ra port. This service is
\rprovided in support of network devices.
\r<p>
\rThe filter command list consists of an array of up to <strong>NET_MAX_FILTER</strong>
\r(16-bit) values to be applied to incoming data "messages" to determine if
\rthat data should be given to a particular input filter.
\r<p>
\rEach filter command list specifies a sequence of actions which leave a boolean
\rvalue on the top of an internal stack. Each 16-bit value of the command list
\rspecifies a data (push) operation (high order <strong>NETF_NBPO</strong>
\rbits) as well as a binary operator (low order <strong>NETF_NBPA</strong> bits).
\r<p>
\rThe value to be pushed onto the stack is chosen as follows:
\r<dl>
\r<dt> <strong>NETF_PUSHLIT</strong>
\r<dd>
\rUse the next 16-bit value of the filter as the value.
\r<dt> <strong>NETF_PUSHZERO</strong>
\r<dd>
\rUse 0 as the value.
\r<dt> <strong>NETF_PUSHWORD+</strong><var>N</var>
\r<dd>
\rUse 16-bit value <var>N</var> of the "data" portion of the message as the value.
\r<dt> <strong>NETF_PUSHHDR+</strong><var>N</var>
\r<dd>
\rUse 16-bit value <var>N</var> of the "header" portion of the message as the value.
\r<dt> <strong>NETF_PUSHIND</strong>
\r<dd>
\rPops the top 32-bit value from the stack and then uses it to index the
\r16-bit value of the "data" portion of the message to be used as the
\rvalue.
\r<dt> <strong>NETF_PUSHHDRIND</strong>
\r<dd>
\rPops the top 32-bit value from the stack and then uses it to index the
\r16-bit value of the "header" portion of the message to be used as the
\rvalue.
\r<dt> <strong>NETF_PUSHSTK+</strong><var>N</var>
\r<dd>
\rUse 32-bit value <var>N</var> of the stack (where the top of stack is value 0) as
\rthe value.
\r<dt> <strong>NETF_NOPUSH</strong>
\r<dd>
\rDon't push a value.
\r</dl>
\rThe unsigned value so chosen is promoted to a 32-bit value before being pushed.
\r<p>
\rOnce a value is pushed (except for the case of <strong>NETF_NOPUSH</strong>), the top two
\r32-bit values of the stack are popped and a binary operator applied to them
\r(with the old top of stack as the second operand). The result
\rof the operator is
\rpushed on the stack. These operators are:
\r<dl>
\r<dt> <strong>NETF_NOP</strong>
\r<dd>
\rDon't pop off any values and do no operation.
\r<dt> <strong>NETF_EQ</strong>
\r<dd>
\rPerform an equal comparison.
\r<dt> <strong>NETF_LT</strong>
\r<dd>
\rPerform a less than comparison.
\r<dt> <strong>NETF_LE</strong>
\r<dd>
\rPerform a less than or equal comparison.
\r<dt> <strong>NETF_GT</strong>
\r<dd>
\rPerform a greater than comparison.
\r<dt> <strong>NETF_GE</strong>
\r<dd>
\rPerform a greater than or equal comparison.
\r<dt> <strong>NETF_AND</strong>
\r<dd>
\rPerform a bit-wise boolean AND operation.
\r<dt> <strong>NETF_OR</strong>
\r<dd>
\rPerform a bit-wise boolean inclusive OR operation.
\r<dt> <strong>NETF_XOR</strong>
\r<dd>
\rPerform a bit-wise boolean exclusive OR operation.
\r<dt> <strong>NETF_NEQ</strong>
\r<dd>
\rPerform a not equal comparison.
\r<dt> <strong>NETF_LSH</strong>
\r<dd>
\rPerform a left shift operation.
\r<dt> <strong>NETF_RSH</strong>
\r<dd>
\rPerform a right shift operation.
\r<dt> <strong>NETF_ADD</strong>
\r<dd>
\rPerform an addition.
\r<dt> <strong>NETF_SUB</strong>
\r<dd>
\rPerform a subtraction.
\r<dt> <strong>NETF_COR</strong>
\r<dd>
\rPerform an equal comparison. If the comparison is <strong>TRUE</strong>, terminate
\rthe filter list. Otherwise, pop the result of the comparison off the stack.
\r<dt> <strong>NETF_CAND</strong>
\r<dd>
\rPerform an equal comparison. If the comparison is <strong>FALSE</strong>, terminate
\rthe filter list. Otherwise, pop the result of the comparison off the stack.
\r<dt> <strong>NETF_CNOR</strong>
\r<dd>
\rPerform a not equal comparison. If the comparison is <strong>FALSE</strong>,
\rterminate the filter list. Otherwise, pop the result of the
\rcomparison off the
\rstack.
\r<dt> <strong>NETF_CNAND</strong>
\r<dd>
\rPerform a not equal comparison. If the comparison is <strong>TRUE</strong>, terminate
\rthe filter list. Otherwise, pop the result of the comparison off the stack.
\r</dl>
\rThe scan of the filter list terminates when the filter list is emptied, or a
\r<strong>NETF_C</strong> operation terminates the list. At this time, if the final
\rvalue of the top of the stack is <strong>TRUE</strong>, then the message is accepted
\rfor the filter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>D_DEVICE_DOWN</strong>
\r<dd>
\rDevice has been shut down
\r<p>
\r<dt> <strong>D_INVALID_OPERATION</strong>
\r<dd>
\rNo filter port was supplied.
\r<p>
\r<dt> <strong>D_NO_SUCH_DEVICE</strong>
\r<dd>
\rNo device with that name, or the device is not operational.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rCurrently no references.
\r\ No newline at end of file
+<h2>device_set_filter</h2>
+<hr>
+<p>
+<strong>Function</strong> - Name an input filter for a device.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include< device/device.h></strong>
+<strong>#include< device/net_status.h></strong>
+
+<strong>kern_return_t device_set_filter</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>mach_port_t</strong> <var>receive_port</var>,
+ <strong>mach_msg_type_name_t</strong> <var>receive_port_type</var>,
+ <strong>int</strong> <var>priority</var>,
+ <strong>filter_array_t</strong> <var>filter</var>,
+ <strong>mach_msg_type_number_t</strong> <var>filter_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right]
+A device port
+<p>
+<dt> <var>receive_port</var>
+<dd>
+[in filter send or receive (to be converted to send) right]
+The port to
+receive the input data that is selected by the filter.
+<p>
+<dt> <var>receive_port_type</var>
+<dd>
+[in scalar]
+IPC type of the send right provided to the device; either
+<strong>MACH_MSG_TYPE_MAKE_SEND</strong>, <strong>MACH_MSG_TYPE_MOVE_SEND</strong>,
+or <strong>MACH_MSG_TYPE_COPY_SEND</strong>.
+<p>
+<dt> <var>priority</var>
+<dd>
+[in scalar]
+Used to order multiple receivers in an implementation
+dependent way.
+<p>
+<dt> <var>filter</var>
+<dd>
+[pointer to in array of <var>filter_t</var>]
+The address of an array of filter values.
+<p>
+<dt> <var>filter_count</var>
+<dd>
+[in scalar]
+The size of the <var>filter</var> array (in 16-bit values).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_set_filter</strong> function provides a means by
+which selected data
+appearing at a device interface can be selected and routed to
+a port. This service is
+provided in support of network devices.
+<p>
+The filter command list consists of an array of up to <strong>NET_MAX_FILTER</strong>
+(16-bit) values to be applied to incoming data "messages" to determine if
+that data should be given to a particular input filter.
+<p>
+Each filter command list specifies a sequence of actions which leave a boolean
+value on the top of an internal stack. Each 16-bit value of the command list
+specifies a data (push) operation (high order <strong>NETF_NBPO</strong>
+bits) as well as a binary operator (low order <strong>NETF_NBPA</strong> bits).
+<p>
+The value to be pushed onto the stack is chosen as follows:
+<dl>
+<dt> <strong>NETF_PUSHLIT</strong>
+<dd>
+Use the next 16-bit value of the filter as the value.
+<dt> <strong>NETF_PUSHZERO</strong>
+<dd>
+Use 0 as the value.
+<dt> <strong>NETF_PUSHWORD+</strong><var>N</var>
+<dd>
+Use 16-bit value <var>N</var> of the "data" portion of the message as the value.
+<dt> <strong>NETF_PUSHHDR+</strong><var>N</var>
+<dd>
+Use 16-bit value <var>N</var> of the "header" portion of the message as the value.
+<dt> <strong>NETF_PUSHIND</strong>
+<dd>
+Pops the top 32-bit value from the stack and then uses it to index the
+16-bit value of the "data" portion of the message to be used as the
+value.
+<dt> <strong>NETF_PUSHHDRIND</strong>
+<dd>
+Pops the top 32-bit value from the stack and then uses it to index the
+16-bit value of the "header" portion of the message to be used as the
+value.
+<dt> <strong>NETF_PUSHSTK+</strong><var>N</var>
+<dd>
+Use 32-bit value <var>N</var> of the stack (where the top of stack is value 0) as
+the value.
+<dt> <strong>NETF_NOPUSH</strong>
+<dd>
+Don't push a value.
+</dl>
+The unsigned value so chosen is promoted to a 32-bit value before being pushed.
+<p>
+Once a value is pushed (except for the case of <strong>NETF_NOPUSH</strong>), the top two
+32-bit values of the stack are popped and a binary operator applied to them
+(with the old top of stack as the second operand). The result
+of the operator is
+pushed on the stack. These operators are:
+<dl>
+<dt> <strong>NETF_NOP</strong>
+<dd>
+Don't pop off any values and do no operation.
+<dt> <strong>NETF_EQ</strong>
+<dd>
+Perform an equal comparison.
+<dt> <strong>NETF_LT</strong>
+<dd>
+Perform a less than comparison.
+<dt> <strong>NETF_LE</strong>
+<dd>
+Perform a less than or equal comparison.
+<dt> <strong>NETF_GT</strong>
+<dd>
+Perform a greater than comparison.
+<dt> <strong>NETF_GE</strong>
+<dd>
+Perform a greater than or equal comparison.
+<dt> <strong>NETF_AND</strong>
+<dd>
+Perform a bit-wise boolean AND operation.
+<dt> <strong>NETF_OR</strong>
+<dd>
+Perform a bit-wise boolean inclusive OR operation.
+<dt> <strong>NETF_XOR</strong>
+<dd>
+Perform a bit-wise boolean exclusive OR operation.
+<dt> <strong>NETF_NEQ</strong>
+<dd>
+Perform a not equal comparison.
+<dt> <strong>NETF_LSH</strong>
+<dd>
+Perform a left shift operation.
+<dt> <strong>NETF_RSH</strong>
+<dd>
+Perform a right shift operation.
+<dt> <strong>NETF_ADD</strong>
+<dd>
+Perform an addition.
+<dt> <strong>NETF_SUB</strong>
+<dd>
+Perform a subtraction.
+<dt> <strong>NETF_COR</strong>
+<dd>
+Perform an equal comparison. If the comparison is <strong>TRUE</strong>, terminate
+the filter list. Otherwise, pop the result of the comparison off the stack.
+<dt> <strong>NETF_CAND</strong>
+<dd>
+Perform an equal comparison. If the comparison is <strong>FALSE</strong>, terminate
+the filter list. Otherwise, pop the result of the comparison off the stack.
+<dt> <strong>NETF_CNOR</strong>
+<dd>
+Perform a not equal comparison. If the comparison is <strong>FALSE</strong>,
+terminate the filter list. Otherwise, pop the result of the
+comparison off the
+stack.
+<dt> <strong>NETF_CNAND</strong>
+<dd>
+Perform a not equal comparison. If the comparison is <strong>TRUE</strong>, terminate
+the filter list. Otherwise, pop the result of the comparison off the stack.
+</dl>
+The scan of the filter list terminates when the filter list is emptied, or a
+<strong>NETF_C</strong> operation terminates the list. At this time, if the final
+value of the top of the stack is <strong>TRUE</strong>, then the message is accepted
+for the filter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>D_DEVICE_DOWN</strong>
+<dd>
+Device has been shut down
+<p>
+<dt> <strong>D_INVALID_OPERATION</strong>
+<dd>
+No filter port was supplied.
+<p>
+<dt> <strong>D_NO_SUCH_DEVICE</strong>
+<dd>
+No device with that name, or the device is not operational.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Currently no references.
-<h2>device_set_status</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set device status.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include< device/device.h></strong>
\r\r<strong>kern_return_t device_set_status</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>dev_flavor_t</strong> <var>flavor</var>,
\r <strong>dev_status_t</strong> <var>status</var>,
\r <strong>mach_msg_type_number_t</strong> <var>status_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right]
\rA device port to the device to be manipulated.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of status information to set.
\r<p>
\r<dt> <var>status</var>
\r<dd>
\r[pointer to in array of natural-sized units]
\rThe status information to set.
\r<p>
\r<dt> <var>status_count</var>
\r<dd>
\r[in scalar]
\rThe size of the status information (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_set_status</strong> function sets device status.
\rThe possible values of <var>flavor</var>
\ras well as the corresponding meanings are device dependent.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>D_DEVICE_DOWN</strong>
\r<dd>
\rDevice has been shut down
\r<p>
\r<dt> <strong>D_IO_ERROR</strong>
\r<dd>
\rHardware I/O error
\r<p>
\r<dt> <strong>D_NO_SUCH_DEVICE</strong>
\r<dd>
\rNo device with that name, or the device is not operational.
\r<p>
\r<dt> <strong>D_OUT_OF_BAND</strong>
\r<dd>
\rOut-of-band condition occurred on device (such as typing
\r <strong><Ctrl>-C</strong>).
\r<p>
\r<dt> <strong>D_READ_ONLY</strong>
\r<dd>
\rData cannot be written to this device.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_get_status.html"><strong>device_get_status</strong></a>.
\r\ No newline at end of file
+<h2>device_set_status</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set device status.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include< device/device.h></strong>
+
+<strong>kern_return_t device_set_status</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>dev_flavor_t</strong> <var>flavor</var>,
+ <strong>dev_status_t</strong> <var>status</var>,
+ <strong>mach_msg_type_number_t</strong> <var>status_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right]
+A device port to the device to be manipulated.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of status information to set.
+<p>
+<dt> <var>status</var>
+<dd>
+[pointer to in array of natural-sized units]
+The status information to set.
+<p>
+<dt> <var>status_count</var>
+<dd>
+[in scalar]
+The size of the status information (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_set_status</strong> function sets device status.
+The possible values of <var>flavor</var>
+as well as the corresponding meanings are device dependent.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>D_DEVICE_DOWN</strong>
+<dd>
+Device has been shut down
+<p>
+<dt> <strong>D_IO_ERROR</strong>
+<dd>
+Hardware I/O error
+<p>
+<dt> <strong>D_NO_SUCH_DEVICE</strong>
+<dd>
+No device with that name, or the device is not operational.
+<p>
+<dt> <strong>D_OUT_OF_BAND</strong>
+<dd>
+Out-of-band condition occurred on device (such as typing
+ <strong><Ctrl>-C</strong>).
+<p>
+<dt> <strong>D_READ_ONLY</strong>
+<dd>
+Data cannot be written to this device.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_get_status.html"><strong>device_get_status</strong></a>.
-<h2>device_write</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Write a sequence of bytes to a specific device.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<device/device.h></strong>
\r\r<strong>kern_return_t device_write</strong>
\r <strong>(device_t</strong> <var>device</var>,
\r <strong>mach_port_t</strong> <var>reply_port</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>recnum_t</strong> <var>recnum</var>,
\r <strong>io_buf_ptr_t</strong> <var>data</var>,
\r <strong>mach_msg_type_number_t</strong> <var>data_count</var>,
\r <strong>io_buf_len_t</strong> <var>io_buf_len_t</var><strong>);</strong>
\r\r\r<strong>#include<device/device_request.h></strong>
\r\r<strong>kern_return_t device_write_request</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>mach_port_t</strong> <var>reply_port</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>recnum_t</strong> <var>recnum</var>,
\r <strong>io_buf_ptr_t</strong> <var>data</var>,
\r <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong>
\r\r\r<strong>kern_return_t ds_device_write_reply</strong>
\r <strong>(mach_port_t</strong> <var>reply_port</var>,
\r <strong>kern_return_t</strong> <var>return_code</var>,
\r <strong>io_buf_len_t</strong> <var>bytes_written</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right]
\rA device port to the device to be written.
\r<p>
\r<dt> <var>reply_port</var>
\r<dd>
\r[in reply receive (to be converted to send-once) right]
\rThe port to
\rwhich the reply message is to be sent.
\r<p>
\r<dt> <var>mode</var>
\r<dd>
\r[in scalar]
\rI/O mode value. Meaningful options are:
\r<dl>
\r<p>
\r<dt> <strong>D_NOWAIT</strong>
\r<dd>
\rDo not wait for I/O completion.
\r</dl>
\r<p>
\r<dt> <var>recnum</var>
\r<dd>
\r[in scalar]
\rRecord number to be written.
\r<p>
\r<dt> <var>data</var>
\r<dd>
\r[pointer to in array of bytes]
\rData bytes to be written.
\r<p>
\r<dt> <var>data_count</var>
\r<dd>
\r[in scalar]
\rNumber of data bytes to be written.
\r<p>
\r<dt> <var>return_code</var>
\r<dd>
\r[in scalar]
\rThe return status code from the write.
\r<p>
\r<dt> <var>bytes_written</var>
\r<dd>
\r[out scalar, in for asynchronous form]
\rSize of data transfer.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_write</strong> function writes a sequence of bytes
\rto a device object. The
\rmeaning of <var>recnum</var> as well as the specific operation performed is device
\rdependent.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_write_inband.html"><strong>device_write_inband</strong></a>,
\r<a href="device_reply_server.html"><strong>device_reply_server</strong></a>.
\r\ No newline at end of file
+<h2>device_write</h2>
+<hr>
+<p>
+<strong>Function</strong> - Write a sequence of bytes to a specific device.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<device/device.h></strong>
+
+<strong>kern_return_t device_write</strong>
+ <strong>(device_t</strong> <var>device</var>,
+ <strong>mach_port_t</strong> <var>reply_port</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>recnum_t</strong> <var>recnum</var>,
+ <strong>io_buf_ptr_t</strong> <var>data</var>,
+ <strong>mach_msg_type_number_t</strong> <var>data_count</var>,
+ <strong>io_buf_len_t</strong> <var>io_buf_len_t</var><strong>);</strong>
+
+
+<strong>#include<device/device_request.h></strong>
+
+<strong>kern_return_t device_write_request</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>mach_port_t</strong> <var>reply_port</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>recnum_t</strong> <var>recnum</var>,
+ <strong>io_buf_ptr_t</strong> <var>data</var>,
+ <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong>
+
+
+<strong>kern_return_t ds_device_write_reply</strong>
+ <strong>(mach_port_t</strong> <var>reply_port</var>,
+ <strong>kern_return_t</strong> <var>return_code</var>,
+ <strong>io_buf_len_t</strong> <var>bytes_written</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right]
+A device port to the device to be written.
+<p>
+<dt> <var>reply_port</var>
+<dd>
+[in reply receive (to be converted to send-once) right]
+The port to
+which the reply message is to be sent.
+<p>
+<dt> <var>mode</var>
+<dd>
+[in scalar]
+I/O mode value. Meaningful options are:
+<dl>
+<p>
+<dt> <strong>D_NOWAIT</strong>
+<dd>
+Do not wait for I/O completion.
+</dl>
+<p>
+<dt> <var>recnum</var>
+<dd>
+[in scalar]
+Record number to be written.
+<p>
+<dt> <var>data</var>
+<dd>
+[pointer to in array of bytes]
+Data bytes to be written.
+<p>
+<dt> <var>data_count</var>
+<dd>
+[in scalar]
+Number of data bytes to be written.
+<p>
+<dt> <var>return_code</var>
+<dd>
+[in scalar]
+The return status code from the write.
+<p>
+<dt> <var>bytes_written</var>
+<dd>
+[out scalar, in for asynchronous form]
+Size of data transfer.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_write</strong> function writes a sequence of bytes
+to a device object. The
+meaning of <var>recnum</var> as well as the specific operation performed is device
+dependent.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_write_inband.html"><strong>device_write_inband</strong></a>,
+<a href="device_reply_server.html"><strong>device_reply_server</strong></a>.
-<h2>device_write_async</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> - Write a sequence of bytes to a device object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t device_write_async</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>mach_port_t</strong> <var>queue</var>,
\r <strong>mach_port_t</strong> <var>request_id</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>recnum_t</strong> <var>recnum</var>,
\r <strong>io_buf_ptr_t</strong> <var>data</var>,
\r <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right] A device port to the device to be read.
\r<p>
\r<dt> <var>queue</var>
\r<dd>
\r[in io_done queue send right] The port returned from
\rio_done_queue_create.
\r<p>
\r<dt> <var>request_id</var>
\r<dd>
\r[in send right] An unique request identifier that will be passed back as
\rpart of the io_done_result structure.
\r<p>
\r<dt> <var>mode</var>
\r<dd>
\r[in scalar] I/O mode value. Meaningful options are:
\r<p>
\r <dl>
\r<dt> <strong>D_NOWAIT</strong>
\r<dd>
\rDo not wait if data is unavailable.
\r </dl>
\r<p>
\r<dt> <var>recnum</var>
\r<dd>
\r[in scalar] Record number to be read.
\r<p>
\r<dt> <var>data</var>
\r<dd>
\r[pointer to in array of bytes] Data bytes to be written.
\r<p>
\r<dt> <var>bytes_wanted</var>
\r<dd>
\r[in scalar] Size of data transfer.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_write_async</strong> function enqueues a write operation for a
\rsequence of bytes to a device object. The meaning of recnum as well as
\rthe specific operation performed is device dependent.
\r<h3>RETURN VALUES</h3>
\r<p>
\r<strong>device_write_async</strong> returns only invalid parameter errors.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>,
\r<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>,
\r<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>,
\r<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>.
\r\ No newline at end of file
+<h2>device_write_async</h2>
+<hr>
+<p>
+<strong>System Trap</strong> - Write a sequence of bytes to a device object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t device_write_async</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>mach_port_t</strong> <var>queue</var>,
+ <strong>mach_port_t</strong> <var>request_id</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>recnum_t</strong> <var>recnum</var>,
+ <strong>io_buf_ptr_t</strong> <var>data</var>,
+ <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right] A device port to the device to be read.
+<p>
+<dt> <var>queue</var>
+<dd>
+[in io_done queue send right] The port returned from
+io_done_queue_create.
+<p>
+<dt> <var>request_id</var>
+<dd>
+[in send right] An unique request identifier that will be passed back as
+part of the io_done_result structure.
+<p>
+<dt> <var>mode</var>
+<dd>
+[in scalar] I/O mode value. Meaningful options are:
+<p>
+ <dl>
+<dt> <strong>D_NOWAIT</strong>
+<dd>
+Do not wait if data is unavailable.
+ </dl>
+<p>
+<dt> <var>recnum</var>
+<dd>
+[in scalar] Record number to be read.
+<p>
+<dt> <var>data</var>
+<dd>
+[pointer to in array of bytes] Data bytes to be written.
+<p>
+<dt> <var>bytes_wanted</var>
+<dd>
+[in scalar] Size of data transfer.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_write_async</strong> function enqueues a write operation for a
+sequence of bytes to a device object. The meaning of recnum as well as
+the specific operation performed is device dependent.
+<h3>RETURN VALUES</h3>
+<p>
+<strong>device_write_async</strong> returns only invalid parameter errors.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>,
+<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>,
+<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>,
+<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>.
-<h2>device_write_async_inband</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> - Write a sequence of bytes "inband" to a device object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t device_write_async_inband</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>mach_port_t</strong> <var>queue</var>,
\r <strong>mach_port_t</strong> <var>request_id</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>recnum_t</strong> <var>recnum</var>,
\r <strong>io_buf_ptr_t</strong> <var>data</var>,
\r <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right] A device port to the device to be read.
\r<p>
\r<dt> <var>queue</var>
\r<dd>
\r[in io_done queue send right] The port returned from
\rio_done_queue_create.
\r<p>
\r<dt> <var>request_id</var>
\r<dd>
\r[in send right] An unique request identifier that will be passed back as
\rpart of the io_done_result structure.
\r<p>
\r<dt> <var>mode</var>
\r<dd>
\r[in scalar] I/O mode value. Meaningful options are:
\r<p>
\r <dl>
\r<dt> <strong>D_NOWAIT</strong>
\r<dd>
\rDo not wait if data is unavailable.
\r </dl>
\r<p>
\r<dt> <var>recnum</var>
\r<dd>
\r[in scalar] Record number to be read.
\r<p>
\r<dt> <var>data</var>
\r<dd>
\r[pointer to in array of bytes] Data bytes to be written.
\r<p>
\r<dt> <var>bytes_wanted</var>
\r<dd>
\r[in scalar] Size of data transfer.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_write_async_inband</strong> function enqueues a write operation for
\ra sequence of bytes to a device object. The meaning of recnum as
\rwell as the specific operation performed is device dependent. This
\rcall differs from <strong>device_write_async</strong> in that the bytes to be written
\rare sent "inband" in the request IPC message.
\r<h3>RETURN VALUES</h3>
\r<p>
\r<strong>device_write_async_inband</strong> returns only invalid parameter errors.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>,
\r<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>,
\r<a href="device_write_async.html"><strong>device_write_async</strong></a>,
\r<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>.
\r\ No newline at end of file
+<h2>device_write_async_inband</h2>
+<hr>
+<p>
+<strong>System Trap</strong> - Write a sequence of bytes "inband" to a device object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t device_write_async_inband</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>mach_port_t</strong> <var>queue</var>,
+ <strong>mach_port_t</strong> <var>request_id</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>recnum_t</strong> <var>recnum</var>,
+ <strong>io_buf_ptr_t</strong> <var>data</var>,
+ <strong>io_buf_len_t</strong> <var>bytes_wanted</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right] A device port to the device to be read.
+<p>
+<dt> <var>queue</var>
+<dd>
+[in io_done queue send right] The port returned from
+io_done_queue_create.
+<p>
+<dt> <var>request_id</var>
+<dd>
+[in send right] An unique request identifier that will be passed back as
+part of the io_done_result structure.
+<p>
+<dt> <var>mode</var>
+<dd>
+[in scalar] I/O mode value. Meaningful options are:
+<p>
+ <dl>
+<dt> <strong>D_NOWAIT</strong>
+<dd>
+Do not wait if data is unavailable.
+ </dl>
+<p>
+<dt> <var>recnum</var>
+<dd>
+[in scalar] Record number to be read.
+<p>
+<dt> <var>data</var>
+<dd>
+[pointer to in array of bytes] Data bytes to be written.
+<p>
+<dt> <var>bytes_wanted</var>
+<dd>
+[in scalar] Size of data transfer.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_write_async_inband</strong> function enqueues a write operation for
+a sequence of bytes to a device object. The meaning of recnum as
+well as the specific operation performed is device dependent. This
+call differs from <strong>device_write_async</strong> in that the bytes to be written
+are sent "inband" in the request IPC message.
+<h3>RETURN VALUES</h3>
+<p>
+<strong>device_write_async_inband</strong> returns only invalid parameter errors.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>,
+<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>,
+<a href="device_write_async.html"><strong>device_write_async</strong></a>,
+<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>.
-<h2>device_write_inband</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Write a sequence of bytes "inband" to a device object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<device/device.h (device_write_inband)></strong>
\r\r<strong>kern_return_t device_write_inband</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>recnum_t</strong> <var>recnum</var>,
\r <strong>io_buf_ptr_inband_t</strong> <var>data</var>,
\r <strong>mach_msg_type_number_t</strong> <var>data_count</var>,
\r <strong>io_buf_len_t</strong> <var>io_buf_len_t</var><strong>);</strong>
\r\r\r<strong>#include<device/device_request.h></strong>
\r\r<strong>kern_return_t device_write_request_inband</strong>
\r <strong>(mach_port_t</strong> <var>device</var>,
\r <strong>mach_port_t</strong> <var>reply_port</var>,
\r <strong>dev_mode_t</strong> <var>mode</var>,
\r <strong>recnum_t</strong> <var>recnum</var>,
\r <strong>io_buf_ptr_inband_t</strong> <var>data</var>,
\r <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong>
\r\r\r<strong>kern_return_t ds_device_write_reply_inband</strong>
\r <strong>(mach_port_t</strong> <var>reply_port</var>,
\r <strong>kern_return_t</strong> <var>return_code</var>,
\r <strong>io_buf_len_t</strong> <var>bytes_writte</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right]
\rA device port to the device to be written.
\r<p>
\r<dt> <var>reply_port</var>
\r<dd>
\r[in reply receive (to be converted to send-once) right]
\rThe port to
\rwhich the reply message is to be sent.
\r<p>
\r<dt> <var>mode</var>
\r<dd>
\r[in scalar]
\rI/O mode value. Meaningful options are:
\r<dl>
\r<p>
\r<dt> <strong>D_NOWAIT</strong>
\r<dd>
\rDo not wait for I/O completion.
\r</dl>
\r<p>
\r<dt> <var>recnum</var>
\r<dd>
\r[in scalar]
\rRecord number to be written.
\r<p>
\r<dt> <var>data</var>
\r<dd>
\r[pointer to in array of bytes]
\rData bytes to be written.
\r<p>
\r<dt> <var>data_count</var>
\r<dd>
\r[in scalar]
\rNumber of data bytes to be written.
\r<p>
\r<dt> <var>return_code</var>
\r<dd>
\r[in scalar]
\rThe return status code from the write.
\r<p>
\r<dt> <var>bytes_written</var>
\r<dd>
\r[out scalar, in for asynchronous form]
\rSize of data transfer.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>device_write_inband</strong> function writes a sequence of bytes to a device
\robject. The meaning of <var>recnum</var> as well as the specific operation
\rperformed is device dependent. This call differs from <strong>device_write</strong>
\rin that the bytes to be written are sent "inband" in the request IPC message.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_write.html"><strong>device_write</strong></a>,
\r<a href="device_reply_server.html"><strong>device_reply_server</strong></a>.
\r\ No newline at end of file
+<h2>device_write_inband</h2>
+<hr>
+<p>
+<strong>Function</strong> - Write a sequence of bytes "inband" to a device object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<device/device.h (device_write_inband)></strong>
+
+<strong>kern_return_t device_write_inband</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>recnum_t</strong> <var>recnum</var>,
+ <strong>io_buf_ptr_inband_t</strong> <var>data</var>,
+ <strong>mach_msg_type_number_t</strong> <var>data_count</var>,
+ <strong>io_buf_len_t</strong> <var>io_buf_len_t</var><strong>);</strong>
+
+
+<strong>#include<device/device_request.h></strong>
+
+<strong>kern_return_t device_write_request_inband</strong>
+ <strong>(mach_port_t</strong> <var>device</var>,
+ <strong>mach_port_t</strong> <var>reply_port</var>,
+ <strong>dev_mode_t</strong> <var>mode</var>,
+ <strong>recnum_t</strong> <var>recnum</var>,
+ <strong>io_buf_ptr_inband_t</strong> <var>data</var>,
+ <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong>
+
+
+<strong>kern_return_t ds_device_write_reply_inband</strong>
+ <strong>(mach_port_t</strong> <var>reply_port</var>,
+ <strong>kern_return_t</strong> <var>return_code</var>,
+ <strong>io_buf_len_t</strong> <var>bytes_writte</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right]
+A device port to the device to be written.
+<p>
+<dt> <var>reply_port</var>
+<dd>
+[in reply receive (to be converted to send-once) right]
+The port to
+which the reply message is to be sent.
+<p>
+<dt> <var>mode</var>
+<dd>
+[in scalar]
+I/O mode value. Meaningful options are:
+<dl>
+<p>
+<dt> <strong>D_NOWAIT</strong>
+<dd>
+Do not wait for I/O completion.
+</dl>
+<p>
+<dt> <var>recnum</var>
+<dd>
+[in scalar]
+Record number to be written.
+<p>
+<dt> <var>data</var>
+<dd>
+[pointer to in array of bytes]
+Data bytes to be written.
+<p>
+<dt> <var>data_count</var>
+<dd>
+[in scalar]
+Number of data bytes to be written.
+<p>
+<dt> <var>return_code</var>
+<dd>
+[in scalar]
+The return status code from the write.
+<p>
+<dt> <var>bytes_written</var>
+<dd>
+[out scalar, in for asynchronous form]
+Size of data transfer.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>device_write_inband</strong> function writes a sequence of bytes to a device
+object. The meaning of <var>recnum</var> as well as the specific operation
+performed is device dependent. This call differs from <strong>device_write</strong>
+in that the bytes to be written are sent "inband" in the request IPC message.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_write.html"><strong>device_write</strong></a>,
+<a href="device_reply_server.html"><strong>device_reply_server</strong></a>.
-<h2>do_mach_notify_dead_name</h2>
\r<hr>
\r<strong>Server Interface</strong> - Handle the current instance of a dead-name notification.
\r<p>
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t do_mach_notify_dead_name</strong>
\r <strong>(notify_port_t</strong> <var>notify</var>,
\r <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong>
\r\r\r<strong>kern_return_t do_seqnos_mach_notify_dead_name</strong>
\r <strong>(notify_port_t</strong> <var>notify</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>notify</var>
\r<dd>
\r[in notify (receive) right]
\rThe port to which the notification was sent.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the
\rnotification port.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\rThe dead name.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>do_mach_notify_dead_name</strong> function is called by <strong>notify_server</strong>
\ras the
\rresult of a kernel message indicating that the port name is now
\rdead as the result
\rof the associated receive right having died. In contrast, a port-deleted
\rnotification indicates that the port name is no longer usable
\r(that is, it no longer names
\ra valid right), typically as a result of the right so named being consumed or
\rmoved. <var>notify</var> is the port named via <strong>mach_port_request_notification</strong>
\ror
\r<strong>mach_msg</strong>.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="notify_server.html"><strong>notify_server</strong></a>,
\r<a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>,
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>,
\r<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>,
\r<a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders</strong></a>,
\r<a href="DMN_port_deleted.html"><strong>do_mach_notify_port_deleted</strong></a>,
\r<a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once</strong></a>.
\r\ No newline at end of file
+<h2>do_mach_notify_dead_name</h2>
+<hr>
+<strong>Server Interface</strong> - Handle the current instance of a dead-name notification.
+<p>
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t do_mach_notify_dead_name</strong>
+ <strong>(notify_port_t</strong> <var>notify</var>,
+ <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong>
+
+
+<strong>kern_return_t do_seqnos_mach_notify_dead_name</strong>
+ <strong>(notify_port_t</strong> <var>notify</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>notify</var>
+<dd>
+[in notify (receive) right]
+The port to which the notification was sent.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the
+notification port.
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+The dead name.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>do_mach_notify_dead_name</strong> function is called by <strong>notify_server</strong>
+as the
+result of a kernel message indicating that the port name is now
+dead as the result
+of the associated receive right having died. In contrast, a port-deleted
+notification indicates that the port name is no longer usable
+(that is, it no longer names
+a valid right), typically as a result of the right so named being consumed or
+moved. <var>notify</var> is the port named via <strong>mach_port_request_notification</strong>
+or
+<strong>mach_msg</strong>.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="notify_server.html"><strong>notify_server</strong></a>,
+<a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>,
+<a href="mach_msg.html"><strong>mach_msg</strong></a>,
+<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>,
+<a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders</strong></a>,
+<a href="DMN_port_deleted.html"><strong>do_mach_notify_port_deleted</strong></a>,
+<a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once</strong></a>.
-<h2>do_mach_notify_no_senders</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Handle the current instance of a no-more-senders notification.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t do_mach_notify_no_senders</strong>
\r <strong>(notify_port_t</strong> <var>notify</var>,
\r <strong>mach_port_mscount_t</strong> <var>mscount</var><strong>);</strong>
\r\r\r<strong>kern_return_t do_seqnos_mach_notify_no_senders</strong>
\r <strong>(notify_port_t</strong> <var>notify</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>mach_port_mscount_t</strong> <var>mscount</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>notify</var>
\r<dd>
\r[in notify (receive) right]
\rThe port to which the notification was sent.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the
\rnotification port.
\r<p>
\r<dt> <var>mscount</var>
\r<dd>
\r[in scalar]
\rThe value the port's make-send count had when the
\rnotification was generated.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>do_mach_notify_no_senders</strong> function is called by
\r<strong>notify_server</strong> as the
\rresult of a kernel message indicating that a receive right has no more senders.
\r<var>notify</var> is the port named via <strong>mach_port_request_notification</strong>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="notify_server.html"><strong>notify_server</strong></a>,
\r<a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>,
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>,
\r<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>,
\r<a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name</strong></a>,
\r<a href="DMN_port_deleted.html"><strong>do_mach_notify_port_deleted</strong></a>,
\r<a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once</strong></a>.
\r\ No newline at end of file
+<h2>do_mach_notify_no_senders</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Handle the current instance of a no-more-senders notification.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t do_mach_notify_no_senders</strong>
+ <strong>(notify_port_t</strong> <var>notify</var>,
+ <strong>mach_port_mscount_t</strong> <var>mscount</var><strong>);</strong>
+
+
+<strong>kern_return_t do_seqnos_mach_notify_no_senders</strong>
+ <strong>(notify_port_t</strong> <var>notify</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>mach_port_mscount_t</strong> <var>mscount</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>notify</var>
+<dd>
+[in notify (receive) right]
+The port to which the notification was sent.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the
+notification port.
+<p>
+<dt> <var>mscount</var>
+<dd>
+[in scalar]
+The value the port's make-send count had when the
+notification was generated.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>do_mach_notify_no_senders</strong> function is called by
+<strong>notify_server</strong> as the
+result of a kernel message indicating that a receive right has no more senders.
+<var>notify</var> is the port named via <strong>mach_port_request_notification</strong>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="notify_server.html"><strong>notify_server</strong></a>,
+<a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>,
+<a href="mach_msg.html"><strong>mach_msg</strong></a>,
+<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>,
+<a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name</strong></a>,
+<a href="DMN_port_deleted.html"><strong>do_mach_notify_port_deleted</strong></a>,
+<a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once</strong></a>.
-<h2>do_mach_notify_send_once</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Handle the current instance of a send-once notification.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t do_mach_notify_send_once</strong>
\r <strong>(notify_port_t</strong> <var>notify</var><strong>)</strong>
\r\r\r<strong>kern_return_t do_seqnos_mach_notify_send_once</strong>
\r <strong>(notify_port_t</strong> <var>notify</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>notify</var>
\r<dd>
\r[in notify (receive) right]
\rThe port to which the notification was sent.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the
\rnotification port.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>do_mach_notify_send_once</strong> function is called by <strong>notify_server</strong>
\ras the result
\rof a kernel message indicating that a send-once right was in
\rany way destroyed.
\r<var>notify</var> is the port for which a send-once right was destroyed.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="notify_server.html"><strong>notify_server</strong></a>,
\r<a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>,
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>,
\r<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>,
\r<a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders</strong></a>,
\r<a href="DMN_port_deleted.html"><strong>do_mach_notify_port_deleted</strong></a>,
\r<a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name</strong></a>.
\r\ No newline at end of file
+<h2>do_mach_notify_send_once</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Handle the current instance of a send-once notification.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t do_mach_notify_send_once</strong>
+ <strong>(notify_port_t</strong> <var>notify</var><strong>)</strong>
+
+
+<strong>kern_return_t do_seqnos_mach_notify_send_once</strong>
+ <strong>(notify_port_t</strong> <var>notify</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>notify</var>
+<dd>
+[in notify (receive) right]
+The port to which the notification was sent.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the
+notification port.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>do_mach_notify_send_once</strong> function is called by <strong>notify_server</strong>
+as the result
+of a kernel message indicating that a send-once right was in
+any way destroyed.
+<var>notify</var> is the port for which a send-once right was destroyed.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="notify_server.html"><strong>notify_server</strong></a>,
+<a href="seqnos_notify_server.html"><strong>seqnos_notify_server</strong></a>,
+<a href="mach_msg.html"><strong>mach_msg</strong></a>,
+<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>,
+<a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders</strong></a>,
+<a href="DMN_port_deleted.html"><strong>do_mach_notify_port_deleted</strong></a>,
+<a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name</strong></a>.
-<h2>etap_get_info</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Map ETAP buffers and tables into server's address space.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<mach/etap.h></strong>
\r\r<strong>kern_return_t etap_get_info</strong>
\r <strong>(host_priv_t</strong> <var>priv_port</var>,
\r <strong>int</strong> <var>int</var>,
\r <strong>int</strong> <var>int</var>,
\r <strong>vm_offset_t</strong> <var>vm_offset_t</var>,
\r <strong>vm_offset_t</strong> <var>vm_offset_t</var>,
\r <strong>int</strong> <var>int</var>,
\r <strong>int</strong> <var>int</var>,
\r <strong>int</strong> <var>int</var>,
\r <strong>int</strong> <var>int</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>priv_port</var>
\r<dd>
\rthe name of the Server's privileged device port (server_device_port),
\r granting the Server access to this service.
\r<p>
\r<dt> <var>et_entries</var>
\r<dd>
\rused to return number of entries in the event table.
\r<p>
\r<dt> <var>st_entries</var>
\r<dd>
\rused to return number of entries in the subsystem table.
\r<p>
\r<dt> <var>et_offset</var>
\r<dd>
\rused to return the event table's page offset.
\r<p>
\r<dt> <var>st_offset</var>
\r<dd>
\rused to return the subsystem table's page offset.
\r<p>
\r<dt> <var>cb_width</var>
\r<dd>
\rreturns the current cumulative buffer interval width.
\r<p>
\r<dt> <var>mb_size</var>
\r<dd>
\rreturns the size of the monitored buffers,
\r<p>
\r<dt> <var>mb_entries</var>
\r<dd>
\rreturns the maximum number of entries in a monitored buffer.
\r<p>
\r<dt> <var>mb_cpus</var>
\r<dd>
\rreturns the number of allocated monitored buffers (or supported CPUs).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>etap_get_info</strong> interface provides the user space
\retap server or daemon with configuration and location information pertaining
\rto the kernel's internal ETAP buffers; this information enables the caller
\rto properly map the ETAP buffers and tables into its address
\rspace. When mapping is successfully completed, the Server displays the
\rETAP configuration on the console. The configuration output will
\rresemble the following:
\r<pre>
\r ETAP configuration [ee:108 se:8 eo:a60 so:acc cw:0 ms:1008008 me:36 mc:1]
\r ETAP event table mapped
\r ETAP subsystem table mapped
\r ETAP monitored buffer #0 mapped
\r</pre>
\r<p>
\rThe values between the brackets correspond with the arguments returned
\rby the <strong>etap_get_info</strong> call (listed
\rabove). For example, "ee:108" indicates that the event table contains
\r108 ETAP event types and "mc:1" indicates that one monitored buffer
\rhas been allocated.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r <dt> <strong>KERN_SUCCESS</strong>
\r <dd>
\r The call was performed successfully.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="etap_probe.html"><strong>etap_probe</strong></a>,
\r<a href="etap_trace_thread.html"><strong>etap_trace_thread</strong></a>,
\r<a href="etap_trace_event.html"><strong>etap_trace_event</strong></a>,
\r<a href="etap_trace_event.html"><strong>etap_get_info</strong></a>.
\r\ No newline at end of file
+<h2>etap_get_info</h2>
+<hr>
+<p>
+<strong>Function</strong> - Map ETAP buffers and tables into server's address space.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<mach/etap.h></strong>
+
+<strong>kern_return_t etap_get_info</strong>
+ <strong>(host_priv_t</strong> <var>priv_port</var>,
+ <strong>int</strong> <var>int</var>,
+ <strong>int</strong> <var>int</var>,
+ <strong>vm_offset_t</strong> <var>vm_offset_t</var>,
+ <strong>vm_offset_t</strong> <var>vm_offset_t</var>,
+ <strong>int</strong> <var>int</var>,
+ <strong>int</strong> <var>int</var>,
+ <strong>int</strong> <var>int</var>,
+ <strong>int</strong> <var>int</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>priv_port</var>
+<dd>
+the name of the Server's privileged device port (server_device_port),
+ granting the Server access to this service.
+<p>
+<dt> <var>et_entries</var>
+<dd>
+used to return number of entries in the event table.
+<p>
+<dt> <var>st_entries</var>
+<dd>
+used to return number of entries in the subsystem table.
+<p>
+<dt> <var>et_offset</var>
+<dd>
+used to return the event table's page offset.
+<p>
+<dt> <var>st_offset</var>
+<dd>
+used to return the subsystem table's page offset.
+<p>
+<dt> <var>cb_width</var>
+<dd>
+returns the current cumulative buffer interval width.
+<p>
+<dt> <var>mb_size</var>
+<dd>
+returns the size of the monitored buffers,
+<p>
+<dt> <var>mb_entries</var>
+<dd>
+returns the maximum number of entries in a monitored buffer.
+<p>
+<dt> <var>mb_cpus</var>
+<dd>
+returns the number of allocated monitored buffers (or supported CPUs).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>etap_get_info</strong> interface provides the user space
+etap server or daemon with configuration and location information pertaining
+to the kernel's internal ETAP buffers; this information enables the caller
+to properly map the ETAP buffers and tables into its address
+space. When mapping is successfully completed, the Server displays the
+ETAP configuration on the console. The configuration output will
+resemble the following:
+<pre>
+ ETAP configuration [ee:108 se:8 eo:a60 so:acc cw:0 ms:1008008 me:36 mc:1]
+ ETAP event table mapped
+ ETAP subsystem table mapped
+ ETAP monitored buffer #0 mapped
+</pre>
+<p>
+The values between the brackets correspond with the arguments returned
+by the <strong>etap_get_info</strong> call (listed
+above). For example, "ee:108" indicates that the event table contains
+108 ETAP event types and "mc:1" indicates that one monitored buffer
+has been allocated.
+<h3>RETURN VALUES</h3>
+<dl>
+ <dt> <strong>KERN_SUCCESS</strong>
+ <dd>
+ The call was performed successfully.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="etap_probe.html"><strong>etap_probe</strong></a>,
+<a href="etap_trace_thread.html"><strong>etap_trace_thread</strong></a>,
+<a href="etap_trace_event.html"><strong>etap_trace_event</strong></a>,
+<a href="etap_trace_event.html"><strong>etap_get_info</strong></a>.
-<h2>etap_probe</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> - Record event data in the kernel's
\rETAP buffer(s).
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<mach/etap.h></strong>
\r\r<strong>kern_return_t etap_probe</strong>
\r <strong>(int</strong> <var>event_id</var>,
\r <strong>event_id</strong> <var>data_size</var>,
\r <strong>etap_data_t</strong> <var>etap_data_t</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>event_id</var>
\r<dd>
\rA user defined value used to identify the event.
\r<p>
\r<dt> <var>data_size</var>
\r<dd>
\rThe size (in bytes) of the data being passed.
\rNote: The data size is limited to ETAP_DATA_SIZE,
\r(defined in <strong>mach/etap.h</strong>).
\r<p>
\r<dt> <var>data</var>
\r<dd>
\rA pointer to the event data being passed.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rApplication programmers may instrument their applications with
\ruser-level probes, using the
\r<strong>etap_probe</strong> system call. All
\revent data passed to the kernel via
\r<strong>etap_probe</strong> is recorded in the
\rkernel's ETAP monitored buffer(s). Each record includes a time stamp.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r <dt> <strong>KERN_SUCCESS</strong>
\r <dd>
\r The call was performed successfully.
\r<p>
\r <dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r <dd>
\r The specified data size exceeds ETAP_DATA_SIZE.
\r<p>
\r <dt> <strong>KERN_NO_ACCESS</strong>
\r <dd>
\r The tracing of user events is currently enabled.
\r<p>
\r <dt> <strong>KERN_FAILURE</strong>
\r <dd>
\r ETAP is not configured in the kernel.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="etap_trace_thread.html"><strong>etap_trace_thread</strong></a>,
\r<a href="etap_trace_event.html"><strong>etap_trace_event</strong></a>,
\r<a href="etap_get_info.html"><strong>etap_get_info</strong></a>.
\r\ No newline at end of file
+<h2>etap_probe</h2>
+<hr>
+<p>
+<strong>System Trap</strong> - Record event data in the kernel's
+ETAP buffer(s).
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<mach/etap.h></strong>
+
+<strong>kern_return_t etap_probe</strong>
+ <strong>(int</strong> <var>event_id</var>,
+ <strong>event_id</strong> <var>data_size</var>,
+ <strong>etap_data_t</strong> <var>etap_data_t</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>event_id</var>
+<dd>
+A user defined value used to identify the event.
+<p>
+<dt> <var>data_size</var>
+<dd>
+The size (in bytes) of the data being passed.
+Note: The data size is limited to ETAP_DATA_SIZE,
+(defined in <strong>mach/etap.h</strong>).
+<p>
+<dt> <var>data</var>
+<dd>
+A pointer to the event data being passed.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+Application programmers may instrument their applications with
+user-level probes, using the
+<strong>etap_probe</strong> system call. All
+event data passed to the kernel via
+<strong>etap_probe</strong> is recorded in the
+kernel's ETAP monitored buffer(s). Each record includes a time stamp.
+<h3>RETURN VALUES</h3>
+<dl>
+ <dt> <strong>KERN_SUCCESS</strong>
+ <dd>
+ The call was performed successfully.
+<p>
+ <dt> <strong>KERN_INVALID_ARGUMENT</strong>
+ <dd>
+ The specified data size exceeds ETAP_DATA_SIZE.
+<p>
+ <dt> <strong>KERN_NO_ACCESS</strong>
+ <dd>
+ The tracing of user events is currently enabled.
+<p>
+ <dt> <strong>KERN_FAILURE</strong>
+ <dd>
+ ETAP is not configured in the kernel.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="etap_trace_thread.html"><strong>etap_trace_thread</strong></a>,
+<a href="etap_trace_event.html"><strong>etap_trace_event</strong></a>,
+<a href="etap_get_info.html"><strong>etap_get_info</strong></a>.
-<h2>etap_trace_event</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> -
\rmanipulate event probes and lock event tracing.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<mach/etap.h></strong>
\r\r<strong>kern_return_t etap_trace_event</strong>
\r <strong>(etap_data_t</strong> <var>mode</var>,
\r <strong>mode</strong> <var>type</var>,
\r <strong>boolean_t</strong> <var>enable</var>,
\r <strong>enable</strong> <var>nargs</var>,
\r <strong>mode</strong> <var>mode</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>mode</var>
\r<dd>
\rindicates the desired trace flavor or reset option and may be one,
\ror more, of the following:
\r<ul>
\r<p>
\r <li>
\rETAP_CUMULATIVE: cumulative lock event trace mode.
\r <p>
\r<li>
\rETAP_MONITORED: monitored event trace mode (for probes or locks)
\r<p>
\r<li>
\rETAP_RESET: reset mode, clears all trace status and cumulative buffer entries
\r</ul>
\r<p>
\r<dt> <var>type</var>
\r<dd>
\rused when measuring lock event contention or durations
\rand may be one, or more, of the following:
\r<ul>
\r<p>
\r <li>
\rETAP_CONTENT
\r<p>
\r <li>
\rETAP_DURATION
\r</ul>
\r<p>
\r<dt> <var>enable</var>
\r<dd>
\ra boolean value indicattin whether the event trace operation is
\rto be enabled (TRUE) or disabled (FALSE).
\r<p>
\r<dt> <var>nargs</var>
\r<dd>
\rspecifies how many arguments are passed in the args array.
\r<p>
\r<dt> <var>args</var>
\r<dd>
\ran array, each element of which is a character string
\rrepresenting a specific subsystem or event type. These values must
\rcorrespond to the ones the kernel uses to represent the same
\rsubsystems and event types. The maximum length of a character string
\ris EVENT_NAME_LENGTH (defined in <strong>mach/etap.h</strong>).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>etap_trace_event</strong> system call is used to enable
\rand disable kernel event probes (of a specified type) and all modes of lock event
\rtracing. The call also supports a reset option, where the cumulative
\rbuffer data and all event type tracing is reset to zero. When the
\rreset option is used, a new interval width can also be defined, using
\rthe <var>nargs</var> parameter.
\r<p>
\rTo reset the ETAP instrumentation,
\rthe system call would utilize the mode parameter, passing the value of
\rETAP_RESET (All other parameters may equal NULL). If, at the time of
\rreset, the <var>nargs</var> parameter is assigned a value, then the
\rcumulative buffer interval width will be adjusted to be the size of
\rthat value. For example, the following system call would reset the
\rETAP instrumentation and adjust the cumulative buffer's interval width
\rto 100ms:
\r<pre>
\r etap_trace_event(ETAP_RESET, 0, 0, 100, 0);
\r\r</pre>
\r<h3>RETURN VALUES</h3>
\r<dl>
\r <dt> <strong>KERN_SUCCESS</strong>
\r <dd>
\r The call was performed successfully.
\r<p>
\r <dt> <strong>KERN_NO_SPACE</strong>
\r <dd>
\r A shortage of kernel resources prevented the operation from completing;
\r the kernel has cleaned up all residual state (the error indicates a "clean"
\r failure).
\r<p>
\r <dt> <strong>KERN_FAILURE</strong>
\r <dd>
\r ETAP is not configured in the kernel.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="etap_probe.html"><strong>etap_probe</strong></a>,
\r<a href="etap_trace_thread.html"><strong>etap_trace_thread</strong></a>,
\r<a href="etap_get_info.html"><strong>etap_get_info</strong></a>.
\r\ No newline at end of file
+<h2>etap_trace_event</h2>
+<hr>
+<p>
+<strong>System Trap</strong> -
+manipulate event probes and lock event tracing.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<mach/etap.h></strong>
+
+<strong>kern_return_t etap_trace_event</strong>
+ <strong>(etap_data_t</strong> <var>mode</var>,
+ <strong>mode</strong> <var>type</var>,
+ <strong>boolean_t</strong> <var>enable</var>,
+ <strong>enable</strong> <var>nargs</var>,
+ <strong>mode</strong> <var>mode</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>mode</var>
+<dd>
+indicates the desired trace flavor or reset option and may be one,
+or more, of the following:
+<ul>
+<p>
+ <li>
+ETAP_CUMULATIVE: cumulative lock event trace mode.
+ <p>
+<li>
+ETAP_MONITORED: monitored event trace mode (for probes or locks)
+<p>
+<li>
+ETAP_RESET: reset mode, clears all trace status and cumulative buffer entries
+</ul>
+<p>
+<dt> <var>type</var>
+<dd>
+used when measuring lock event contention or durations
+and may be one, or more, of the following:
+<ul>
+<p>
+ <li>
+ETAP_CONTENT
+<p>
+ <li>
+ETAP_DURATION
+</ul>
+<p>
+<dt> <var>enable</var>
+<dd>
+a boolean value indicattin whether the event trace operation is
+to be enabled (TRUE) or disabled (FALSE).
+<p>
+<dt> <var>nargs</var>
+<dd>
+specifies how many arguments are passed in the args array.
+<p>
+<dt> <var>args</var>
+<dd>
+an array, each element of which is a character string
+representing a specific subsystem or event type. These values must
+correspond to the ones the kernel uses to represent the same
+subsystems and event types. The maximum length of a character string
+is EVENT_NAME_LENGTH (defined in <strong>mach/etap.h</strong>).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>etap_trace_event</strong> system call is used to enable
+and disable kernel event probes (of a specified type) and all modes of lock event
+tracing. The call also supports a reset option, where the cumulative
+buffer data and all event type tracing is reset to zero. When the
+reset option is used, a new interval width can also be defined, using
+the <var>nargs</var> parameter.
+<p>
+To reset the ETAP instrumentation,
+the system call would utilize the mode parameter, passing the value of
+ETAP_RESET (All other parameters may equal NULL). If, at the time of
+reset, the <var>nargs</var> parameter is assigned a value, then the
+cumulative buffer interval width will be adjusted to be the size of
+that value. For example, the following system call would reset the
+ETAP instrumentation and adjust the cumulative buffer's interval width
+to 100ms:
+<pre>
+ etap_trace_event(ETAP_RESET, 0, 0, 100, 0);
+
+</pre>
+<h3>RETURN VALUES</h3>
+<dl>
+ <dt> <strong>KERN_SUCCESS</strong>
+ <dd>
+ The call was performed successfully.
+<p>
+ <dt> <strong>KERN_NO_SPACE</strong>
+ <dd>
+ A shortage of kernel resources prevented the operation from completing;
+ the kernel has cleaned up all residual state (the error indicates a "clean"
+ failure).
+<p>
+ <dt> <strong>KERN_FAILURE</strong>
+ <dd>
+ ETAP is not configured in the kernel.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="etap_probe.html"><strong>etap_probe</strong></a>,
+<a href="etap_trace_thread.html"><strong>etap_trace_thread</strong></a>,
+<a href="etap_get_info.html"><strong>etap_get_info</strong></a>.
-<h2>etap_trace_thread</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set a thread's ETAP trace status.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<mach/etap.h></strong>
\r\r<strong>kern_return_t etap_trace_thread</strong>
\r <strong>(thread_act_t</strong> <var>target_thread</var>,
\r <strong>boolean_t</strong> <var>active</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_thread</var>
\r<dd>
\rThe port of the thread who's ETAP trace status will be toggled.
\r<p>
\r<dt> <var>active</var>
\r<dd>
\rThe boolean value (either TRUE or FALSE) stating whether the thread's
\rETAP trace status will be activated or not. Passing TRUE will enable
\rthe thread's trace status and FALSE will deactivate it.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>etap_trace_thread</strong> system call is used to
\rtoggle the ETAP trace status of a thread.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r <dt> <strong>KERN_SUCCESS</strong>
\r <dd>
\r The call was performed successfully.
\r<p>
\r <dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r <dd>
\r The value of <var>target_thread</var> does not name a valid thread.
\r<p>
\r <dt> <strong>KERN_FAILURE</strong>
\r <dd>
\r ETAP is not configured in the kernel.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="etap_probe.html"><strong>etap_probe</strong></a>,
\r<a href="etap_trace_event.html"><strong>etap_trace_event</strong></a>,
\r<a href="etap_get_info.html"><strong>etap_get_info</strong></a>.
\r\ No newline at end of file
+<h2>etap_trace_thread</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set a thread's ETAP trace status.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<mach/etap.h></strong>
+
+<strong>kern_return_t etap_trace_thread</strong>
+ <strong>(thread_act_t</strong> <var>target_thread</var>,
+ <strong>boolean_t</strong> <var>active</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_thread</var>
+<dd>
+The port of the thread who's ETAP trace status will be toggled.
+<p>
+<dt> <var>active</var>
+<dd>
+The boolean value (either TRUE or FALSE) stating whether the thread's
+ETAP trace status will be activated or not. Passing TRUE will enable
+the thread's trace status and FALSE will deactivate it.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>etap_trace_thread</strong> system call is used to
+toggle the ETAP trace status of a thread.
+<h3>RETURN VALUES</h3>
+<dl>
+ <dt> <strong>KERN_SUCCESS</strong>
+ <dd>
+ The call was performed successfully.
+<p>
+ <dt> <strong>KERN_INVALID_ARGUMENT</strong>
+ <dd>
+ The value of <var>target_thread</var> does not name a valid thread.
+<p>
+ <dt> <strong>KERN_FAILURE</strong>
+ <dd>
+ ETAP is not configured in the kernel.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="etap_probe.html"><strong>etap_probe</strong></a>,
+<a href="etap_trace_event.html"><strong>etap_trace_event</strong></a>,
+<a href="etap_get_info.html"><strong>etap_get_info</strong></a>.
-<h2>evc_wait</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> - Wait for a kernel (device) signalled event.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t evc_wait</strong>
\r <strong>(unsigned int</strong> <var>event</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>event</var>
\r<dd>
\r[in scalar] The task local event ID of the kernel event object.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>evc_wait</strong> function causes the invoking thread to wait until the
\rspecified kernel (device) generated <var>event</var> occurs. Device drivers
\r(typically mapped devices intended to be supported by user space
\rdrivers) may supply an <var>event</var> service. The <var>event</var> service defines one
\ror more <var>event</var> objects, named by task local <var>event</var> IDs. Each of these
\r<var>event</var> objects has an associated <var>event</var> count, initially zero. Whenever
\rthe associated <var>event</var> occurs (typically a device interrupt), the <var>event</var>
\rcount is incremented. If this count is zero when <strong>evc_wait</strong> is called,
\rthe calling thread waits for the next <var>event</var> to occur. Only one thread
\rmay be waiting for the <var>event</var> to occur. If the count is non-zero when
\r<strong>evc_wait</strong> is called, the count is simply decremented without causing
\rthe thread to wait. The <var>event</var> count guarantees that no <var>event</var>s are
\rlost.
\r<h3>NOTES</h3>
\r<p>
\rThe typical use of this service is within user space device
\rdrivers. When a device interrupt occurs, the (in this case, simple)
\rkernel device driver would place device status in a shared (with the
\ruser device driver) memory window (established by <strong>device_map</strong>) and
\rsignal the associated <var>event</var>. The user space device driver would
\rnormally be waiting with <strong>evc_wait</strong>. The user thread then wakes,
\rprocesses the device status, typically interacting with the device via
\rits shared memory window, then waits for the next interrupt.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<dt> <strong>KERN_NO_SPACE</strong>
\r<dd>
\rThere is already a thread waiting for this event.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="device_map.html"><strong>device_map</strong></a>.
\r\ No newline at end of file
+<h2>evc_wait</h2>
+<hr>
+<p>
+<strong>System Trap</strong> - Wait for a kernel (device) signalled event.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t evc_wait</strong>
+ <strong>(unsigned int</strong> <var>event</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>event</var>
+<dd>
+[in scalar] The task local event ID of the kernel event object.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>evc_wait</strong> function causes the invoking thread to wait until the
+specified kernel (device) generated <var>event</var> occurs. Device drivers
+(typically mapped devices intended to be supported by user space
+drivers) may supply an <var>event</var> service. The <var>event</var> service defines one
+or more <var>event</var> objects, named by task local <var>event</var> IDs. Each of these
+<var>event</var> objects has an associated <var>event</var> count, initially zero. Whenever
+the associated <var>event</var> occurs (typically a device interrupt), the <var>event</var>
+count is incremented. If this count is zero when <strong>evc_wait</strong> is called,
+the calling thread waits for the next <var>event</var> to occur. Only one thread
+may be waiting for the <var>event</var> to occur. If the count is non-zero when
+<strong>evc_wait</strong> is called, the count is simply decremented without causing
+the thread to wait. The <var>event</var> count guarantees that no <var>event</var>s are
+lost.
+<h3>NOTES</h3>
+<p>
+The typical use of this service is within user space device
+drivers. When a device interrupt occurs, the (in this case, simple)
+kernel device driver would place device status in a shared (with the
+user device driver) memory window (established by <strong>device_map</strong>) and
+signal the associated <var>event</var>. The user space device driver would
+normally be waiting with <strong>evc_wait</strong>. The user thread then wakes,
+processes the device status, typically interacting with the device via
+its shared memory window, then waits for the next interrupt.
+<h3>RETURN VALUES</h3>
+<dl>
+<dt> <strong>KERN_NO_SPACE</strong>
+<dd>
+There is already a thread waiting for this event.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="device_map.html"><strong>device_map</strong></a>.
-<h2>exc_server</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Handle kernel-reported thread exception.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>boolean_t exc_server</strong>
\r <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
\r <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>in_msg</var>
\r<dd>
\r[pointer to in structure]
\rThe exception message received from the
\rkernel.
\r<p>
\r<dt> <var>out_msg</var>
\r<dd>
\r[out structure]
\rA reply message.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>exc_server</strong> function is the MIG generated server
\rhandling function to
\rhandle messages from the kernel relating to the occurrence of
\ran exception in a
\rthread. Such messages are delivered to the exception port set via
\r<strong>thread_set_exception_ports</strong> or <strong>task_set_exception_ports</strong>.
\rWhen an exception occurs in a
\rthread, the thread sends an exception message to its exception port, blocking in
\rthe kernel waiting for the receipt of a reply. The <strong>exc_server</strong>
\rfunction performs
\rall necessary argument handling for this kernel message and calls
\r<strong>catch_exception_raise</strong>, <strong>catch_exception_raise_state</strong> or
\r<strong>catch_exception_raise_state_identity</strong>, which should handle the
\rexception. If the called routine
\rreturns <strong>KERN_SUCCESS</strong>, a reply message will be sent, allowing
\rthe thread to
\rcontinue from the point of the exception; otherwise, no reply message is sent
\rand the called routine must have dealt with the exception thread directly.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>TRUE</strong>
\r<dd>
\rThe message was handled and the appropriate function was called.
\r<p>
\r<dt> <strong>FALSE</strong>
\r<dd>
\rThe message did not apply to the exception mechanism and no other
\raction was taken.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="catch_exception_raise.html"><strong>catch_exception_raise<strong></a>.
\r\ No newline at end of file
+<h2>exc_server</h2>
+<hr>
+<p>
+<strong>Function</strong> - Handle kernel-reported thread exception.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>boolean_t exc_server</strong>
+ <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
+ <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>in_msg</var>
+<dd>
+[pointer to in structure]
+The exception message received from the
+kernel.
+<p>
+<dt> <var>out_msg</var>
+<dd>
+[out structure]
+A reply message.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>exc_server</strong> function is the MIG generated server
+handling function to
+handle messages from the kernel relating to the occurrence of
+an exception in a
+thread. Such messages are delivered to the exception port set via
+<strong>thread_set_exception_ports</strong> or <strong>task_set_exception_ports</strong>.
+When an exception occurs in a
+thread, the thread sends an exception message to its exception port, blocking in
+the kernel waiting for the receipt of a reply. The <strong>exc_server</strong>
+function performs
+all necessary argument handling for this kernel message and calls
+<strong>catch_exception_raise</strong>, <strong>catch_exception_raise_state</strong> or
+<strong>catch_exception_raise_state_identity</strong>, which should handle the
+exception. If the called routine
+returns <strong>KERN_SUCCESS</strong>, a reply message will be sent, allowing
+the thread to
+continue from the point of the exception; otherwise, no reply message is sent
+and the called routine must have dealt with the exception thread directly.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>TRUE</strong>
+<dd>
+The message was handled and the appropriate function was called.
+<p>
+<dt> <strong>FALSE</strong>
+<dd>
+The message did not apply to the exception mechanism and no other
+action was taken.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="catch_exception_raise.html"><strong>catch_exception_raise<strong></a>.
-<h2>host_adjust_time</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Gradually change the time.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include< mach/mach_host.h></strong>
\r\r<strong>kern_return_t host_adjust_time</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>time_value_t</strong> <var>new_adjustment</var>,
\r <strong>time_value_t</strong> <var>old_adjustment</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host_priv</var>
\r<dd>
\r[in host-control port] The control port the host for which the time is to be set.
\r<p>
\r<dt> <var>new_adjustment</var>
\r<dd>
\r[in structure] New adjustment value.
\r<p>
\r<dt> <var>old_adjustment</var>
\r<dd>
\r[out structure] Old adjustment value.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_adjust_time</strong> function arranges for the time on a specified host to be gradually changed by an adjustment value.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_get_time.html"><strong>host_get_time</strong></a>,
\r<a href="host_set_time.html"><strong>host_set_time</strong></a>.
\r<p>
\rData Structures:
\rtime_value.
\r\ No newline at end of file
+<h2>host_adjust_time</h2>
+<hr>
+<p>
+<strong>Function</strong> - Gradually change the time.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include< mach/mach_host.h></strong>
+
+<strong>kern_return_t host_adjust_time</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>time_value_t</strong> <var>new_adjustment</var>,
+ <strong>time_value_t</strong> <var>old_adjustment</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host_priv</var>
+<dd>
+[in host-control port] The control port the host for which the time is to be set.
+<p>
+<dt> <var>new_adjustment</var>
+<dd>
+[in structure] New adjustment value.
+<p>
+<dt> <var>old_adjustment</var>
+<dd>
+[out structure] Old adjustment value.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_adjust_time</strong> function arranges for the time on a specified host to be gradually changed by an adjustment value.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_get_time.html"><strong>host_get_time</strong></a>,
+<a href="host_set_time.html"><strong>host_set_time</strong></a>.
+<p>
+Data Structures:
+time_value.
-<h2>host_basic_info</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Used to present basic information about a host.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct host_basic_info</strong>
\r<strong>{</strong>
\r <strong>integer_t</strong> <var>max_cpus</var><strong>;</strong>
\r <strong>integer_t</strong> <var>avail_cpus</var><strong>;</strong>
\r <strong>vm_size_t</strong> <var>memory_size</var><strong>;</strong>
\r <strong>cpu_type_t</strong> <var>cpu_type</var><strong>;</strong>
\r <strong>cpu_subtype_t</strong> <var>cpu_subtype</var><strong>;</strong>
\r <strong>cpu_threadtype_t</strong> <var>cpu_threadtype</var><strong>;</strong>
\r <strong>integer_t</strong> <var>physical_cpu</var><strong>;</strong>
\r <strong>integer_t</strong> <var>physical_cpu_max</var><strong>;</strong>
\r <strong>integer_t</strong> <var>logical_cpu</var><strong>;</strong>
\r <strong>integer_t</strong> <var>logical_cpu_max</var><strong>;</strong>
\r <strong>uint64_t</strong> <var>max_mem</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct host_basic_info* host_basic_info_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>max_cpus</var>
\r<dd>
\rMaximum number of CPUs possible
\r<p>
\r<dt> <var>avail_cpus</var>
\r<dd>
\rNumber of CPUs now available
\r<p>
\r<dt> <var>memory_size</var>
\r<dd>
\rSize of memory in bytes, capped at 2 GB
\r<p>
\r<dt> <var>cpu_type</var>
\r<dd>
\rCPU type
\r<p>
\r<dt> <var>cpu_subtype</var>
\r<dd>
\rCPU sub-type
\r<p>
\r<dt> <var>cpu_threadtype</var>
\r<dd>
\rCPU thread-type
\r<p>
\r<dt> <var>physical_cpu</var>
\r<dd>
\rNumber of physical CPUs now available
\r<p>
\r<dt> <var>physical_cpu_max</var>
\r<dd>
\rMaximum number of physical CPUs possible
\r<p>
\r<dt> <var>logical_cpu</var>
\r<dd>
\rNumber of logical CPUs now available
\r<p>
\r<dt> <var>logical_cpu_max</var>
\r<dd>
\rMaximum number of logical CPUs possible
\r<p>
\r<dt> <var>max_mem</var>
\r<dd>
\rActual size of physical memory in bytes
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_basic_info</strong> structure defines the basic information
\ravailable about a
\rhost.
\r<h3>NOTES</h3>
\r<p>
\rThis structure is machine word length specific because of the memory size
\rreturned.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_info.html"><strong>host_info</strong></a>.
\r<p>
\rData Structures:
\r<a href="host_load_info.html"><strong>host_load_info</strong></a>,
\r<a href="host_sched_info.html"><strong>host_sched_info</strong></a>.
\r\ No newline at end of file
+<h2>host_basic_info</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Used to present basic information about a host.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct host_basic_info</strong>
+<strong>{</strong>
+ <strong>integer_t</strong> <var>max_cpus</var><strong>;</strong>
+ <strong>integer_t</strong> <var>avail_cpus</var><strong>;</strong>
+ <strong>vm_size_t</strong> <var>memory_size</var><strong>;</strong>
+ <strong>cpu_type_t</strong> <var>cpu_type</var><strong>;</strong>
+ <strong>cpu_subtype_t</strong> <var>cpu_subtype</var><strong>;</strong>
+ <strong>cpu_threadtype_t</strong> <var>cpu_threadtype</var><strong>;</strong>
+ <strong>integer_t</strong> <var>physical_cpu</var><strong>;</strong>
+ <strong>integer_t</strong> <var>physical_cpu_max</var><strong>;</strong>
+ <strong>integer_t</strong> <var>logical_cpu</var><strong>;</strong>
+ <strong>integer_t</strong> <var>logical_cpu_max</var><strong>;</strong>
+ <strong>uint64_t</strong> <var>max_mem</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct host_basic_info* host_basic_info_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>max_cpus</var>
+<dd>
+Maximum number of CPUs possible
+<p>
+<dt> <var>avail_cpus</var>
+<dd>
+Number of CPUs now available
+<p>
+<dt> <var>memory_size</var>
+<dd>
+Size of memory in bytes, capped at 2 GB
+<p>
+<dt> <var>cpu_type</var>
+<dd>
+CPU type
+<p>
+<dt> <var>cpu_subtype</var>
+<dd>
+CPU sub-type
+<p>
+<dt> <var>cpu_threadtype</var>
+<dd>
+CPU thread-type
+<p>
+<dt> <var>physical_cpu</var>
+<dd>
+Number of physical CPUs now available
+<p>
+<dt> <var>physical_cpu_max</var>
+<dd>
+Maximum number of physical CPUs possible
+<p>
+<dt> <var>logical_cpu</var>
+<dd>
+Number of logical CPUs now available
+<p>
+<dt> <var>logical_cpu_max</var>
+<dd>
+Maximum number of logical CPUs possible
+<p>
+<dt> <var>max_mem</var>
+<dd>
+Actual size of physical memory in bytes
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_basic_info</strong> structure defines the basic information
+available about a
+host.
+<h3>NOTES</h3>
+<p>
+This structure is machine word length specific because of the memory size
+returned.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_info.html"><strong>host_info</strong></a>.
+<p>
+Data Structures:
+<a href="host_load_info.html"><strong>host_load_info</strong></a>,
+<a href="host_sched_info.html"><strong>host_sched_info</strong></a>.
-<h2>host_get_boot_info</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return operator boot information.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t host_get_boot_info</strong>
\r <strong>(host_priv_t</strong> <var>priv_host</var>,
\r <strong>kernel_boot_info_t</strong> <var>boot_info</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>priv_host</var>
\r<dd>
\r[in host-control send right]
\rThe control port for the host for which
\rinformation is to be obtained.
\r<p>
\r<dt> <var>boot_info</var>
\r<dd>
\r[out array of char]
\rCharacter string providing the operator boot info
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_get_boot_info</strong> function returns the boot-time information
\rstring supplied by the operator when <var>priv_host</var> was initialized.
\rThe constant <strong>KERNEL_BOOT_INFO_MAX</strong> (in \*L<mach/host_info.h>\*O)
\rshould be used to dimension storage for the returned string.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_info.html"><strong>host_info</strong></a>.
\r\ No newline at end of file
+<h2>host_get_boot_info</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return operator boot information.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t host_get_boot_info</strong>
+ <strong>(host_priv_t</strong> <var>priv_host</var>,
+ <strong>kernel_boot_info_t</strong> <var>boot_info</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>priv_host</var>
+<dd>
+[in host-control send right]
+The control port for the host for which
+information is to be obtained.
+<p>
+<dt> <var>boot_info</var>
+<dd>
+[out array of char]
+Character string providing the operator boot info
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_get_boot_info</strong> function returns the boot-time information
+string supplied by the operator when <var>priv_host</var> was initialized.
+The constant <strong>KERNEL_BOOT_INFO_MAX</strong> (in \*L<mach/host_info.h>\*O)
+should be used to dimension storage for the returned string.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_info.html"><strong>host_info</strong></a>.
-<h2>host_get_clock_control</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return a send right to a kernel clock's control port.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t host_get_clock_control</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>clock_id_t</strong> <var>id</var>,
\r <strong>clock_ctrl_t</strong> <var>clock_control</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host_priv</var>
\r<dd>
\r[in host-control send right]
\rThe control port for the host owning the
\rclock.
\r<p>
\r<dt> <var>id</var>
\r<dd>
\r[in scalar]
\rThe identification of the desired kernel clock. These values
\rare defined in \*L<mach/clock_types.h>\*O. Although an implementation
\rmay define additional values, the following values are always defined
\r(although only the REALTIME clock is required to be implemented):
\r<dl>
\r<p>
\r<dt> <strong>REALTIME_CLOCK</strong>
\r<dd>
\rA moderate resolution clock service that (typically) tracks
\rtime since the system last boot.
\r<p>
\r<dt> <strong>BATTERY_CLOCK</strong>
\r<dd>
\rA (typically) low resolution clock (to the second) that
\rsurvives power failures or service outages.
\r<p>
\r<dt> <strong>HIGHRES_CLOCK</strong>
\r<dd>
\rA high resolution clock.
\r</dl>
\r<p>
\r<dt> <var>clock_control</var>
\r<dd>
\r[out clock-control send right]
\rControl port for the clock.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_get_clock_control</strong> function returns a send
\rright to the control port for
\ra kernel clock object. This right is used to set the clock's
\rresolution and time.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="clock_set_time.html"><strong>clock_set_time</strong></a>,
\r<a href="clock_set_attributes.html"><strong>clock_set_attributes</strong></a>,
\r<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>.
\r\ No newline at end of file
+<h2>host_get_clock_control</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return a send right to a kernel clock's control port.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t host_get_clock_control</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>clock_id_t</strong> <var>id</var>,
+ <strong>clock_ctrl_t</strong> <var>clock_control</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host_priv</var>
+<dd>
+[in host-control send right]
+The control port for the host owning the
+clock.
+<p>
+<dt> <var>id</var>
+<dd>
+[in scalar]
+The identification of the desired kernel clock. These values
+are defined in \*L<mach/clock_types.h>\*O. Although an implementation
+may define additional values, the following values are always defined
+(although only the REALTIME clock is required to be implemented):
+<dl>
+<p>
+<dt> <strong>REALTIME_CLOCK</strong>
+<dd>
+A moderate resolution clock service that (typically) tracks
+time since the system last boot.
+<p>
+<dt> <strong>BATTERY_CLOCK</strong>
+<dd>
+A (typically) low resolution clock (to the second) that
+survives power failures or service outages.
+<p>
+<dt> <strong>HIGHRES_CLOCK</strong>
+<dd>
+A high resolution clock.
+</dl>
+<p>
+<dt> <var>clock_control</var>
+<dd>
+[out clock-control send right]
+Control port for the clock.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_get_clock_control</strong> function returns a send
+right to the control port for
+a kernel clock object. This right is used to set the clock's
+resolution and time.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="clock_set_time.html"><strong>clock_set_time</strong></a>,
+<a href="clock_set_attributes.html"><strong>clock_set_attributes</strong></a>,
+<a href="host_get_clock_service.html"><strong>host_get_clock_service</strong></a>.
-<h2>host_get_clock_service</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return a send right to a kernel clock's service port.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t host_get_clock_service</strong>
\r <strong>(host_t</strong> <var>host</var>,
\r <strong>clock_id_t</strong> <var>id</var>,
\r <strong>clock_t</strong> <var>clock_name</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host</var>
\r<dd>
\r[in host-name send right]
\rThe name (or control) port for the host
\rowning the clock.
\r<p>
\r<dt> <var>id</var>
\r<dd>
\r[in scalar]
\rThe identification of the desired kernel clock. These values
\rare defined in \*L<mach/clock_types.h>\*O. Although an implementation
\rmay define additional values, the following values are always defined
\r(although only the REALTIME clock is required to be implemented):
\r<dl>
\r<p>
\r<dt> <strong>REALTIME_CLOCK</strong>
\r<dd>
\rA moderate resolution clock service that (typically) tracks
\rtime since the system last boot.
\r<p>
\r<dt> <strong>BATTERY_CLOCK</strong>
\r<dd>
\rA (typically) low resolution clock (to the second) that
\rsurvives power failures or service outages.
\r<p>
\r<dt> <strong>HIGHRES_CLOCK</strong>
\r<dd>
\rA high resolution clock.
\r</dl>
\r<p>
\r<dt> <var>clock_name</var>
\r<dd>
\r[out clock-name send right]
\rName port for the clock.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_get_clock_service</strong> function returns a send
\rright to the name port for a
\rkernel clock object. This right is used to get the time and
\rresolutions of the
\rclock and to set clock alarms.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="clock_get_time.html"><strong>clock_get_time</strong></a>,
\r<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>,
\r<a href="clock_map_time.html"><strong>clock_map_time</strong></a>,
\r<a href="clock_sleep.html"><strong>clock_sleep</strong></a>,
\r<a href="clock_alarm.html"><strong>clock_alarm</strong></a>,
\r<a href="host_get_clock_control.html"><strong>host_get_clock_control</strong></a>.
\r\ No newline at end of file
+<h2>host_get_clock_service</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return a send right to a kernel clock's service port.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t host_get_clock_service</strong>
+ <strong>(host_t</strong> <var>host</var>,
+ <strong>clock_id_t</strong> <var>id</var>,
+ <strong>clock_t</strong> <var>clock_name</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host</var>
+<dd>
+[in host-name send right]
+The name (or control) port for the host
+owning the clock.
+<p>
+<dt> <var>id</var>
+<dd>
+[in scalar]
+The identification of the desired kernel clock. These values
+are defined in \*L<mach/clock_types.h>\*O. Although an implementation
+may define additional values, the following values are always defined
+(although only the REALTIME clock is required to be implemented):
+<dl>
+<p>
+<dt> <strong>REALTIME_CLOCK</strong>
+<dd>
+A moderate resolution clock service that (typically) tracks
+time since the system last boot.
+<p>
+<dt> <strong>BATTERY_CLOCK</strong>
+<dd>
+A (typically) low resolution clock (to the second) that
+survives power failures or service outages.
+<p>
+<dt> <strong>HIGHRES_CLOCK</strong>
+<dd>
+A high resolution clock.
+</dl>
+<p>
+<dt> <var>clock_name</var>
+<dd>
+[out clock-name send right]
+Name port for the clock.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_get_clock_service</strong> function returns a send
+right to the name port for a
+kernel clock object. This right is used to get the time and
+resolutions of the
+clock and to set clock alarms.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="clock_get_time.html"><strong>clock_get_time</strong></a>,
+<a href="clock_get_attributes.html"><strong>clock_get_attributes</strong></a>,
+<a href="clock_map_time.html"><strong>clock_map_time</strong></a>,
+<a href="clock_sleep.html"><strong>clock_sleep</strong></a>,
+<a href="clock_alarm.html"><strong>clock_alarm</strong></a>,
+<a href="host_get_clock_control.html"><strong>host_get_clock_control</strong></a>.
-<h2>host_get_time</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return the current time.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include< mach/mach_host.h></strong>
\r\r<strong>kern_return_t host_get_time</strong>
\r <strong>(host_t</strong> <var>host</var>,
\r <strong>time_value_t</strong> <var>current_time</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host</var>
\r<dd>
\r[in host-name port] The name port the host for which the time is to be set.
\r<p>
\r<dt> <var>current_time</var>
\r<dd>
\r[out structure] Returned time value.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_get_time</strong> function returns the current time
\ras seen by that <var>host</var>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_adjust_time.html"><strong>host_adjust_time</strong></a>,
\r<a href="host_set_time.html"><strong>host_set_time</strong></a>.
\r<p>
\rData Structures:
\rtime_value.
\r\ No newline at end of file
+<h2>host_get_time</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return the current time.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include< mach/mach_host.h></strong>
+
+<strong>kern_return_t host_get_time</strong>
+ <strong>(host_t</strong> <var>host</var>,
+ <strong>time_value_t</strong> <var>current_time</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host</var>
+<dd>
+[in host-name port] The name port the host for which the time is to be set.
+<p>
+<dt> <var>current_time</var>
+<dd>
+[out structure] Returned time value.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_get_time</strong> function returns the current time
+as seen by that <var>host</var>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_adjust_time.html"><strong>host_adjust_time</strong></a>,
+<a href="host_set_time.html"><strong>host_set_time</strong></a>.
+<p>
+Data Structures:
+time_value.
-<h2>host_info</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return information about a host.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t host_info</strong>
\r <strong>(host_t</strong> <var>host</var>,
\r <strong>host_flavor_t</strong> <var>flavor</var>,
\r <strong>host_info_t</strong> <var>host_info</var>,
\r <strong>mach_msg_type_number_t</strong> <var>host_info_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host</var>
\r<dd>
\r[in host-name send right]
\rThe name (or control) port for the host for
\rwhich information is to be obtained.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of statistics desired:
\r<dl>
\r<p>
\r<dt> <strong>HOST_BASIC_INFO</strong>
\r<dd>
\rBasic information (number of processors, amount of
\rmemory). The returned structure is <strong>host_basic_info</strong>.
\r<p>
\r<dt> <strong>HOST_SCHED_INFO</strong>
\r<dd>
\rBasic restrictions of the kernel's scheduling, minimum
\rquantum and time-out value. The returned structure is
\r<strong>host_sched_info</strong>.
\r<p>
\r<dt> <strong>HOST_RESOURCE_SIZES</strong>
\r<dd>
\rThis interface feature is not implemented in OSF/1 R1.3.
\rSize of significant kernel structures, as a ledger would
\rconsider them when limiting kernel resource consumption. The
\rreturned structure is <strong>kernel_resource_sizes</strong>.
\r</dl>
\r<p>
\r<dt> <var>host_info</var>
\r<dd>
\r[out structure]
\rStatistics about the specified host.
\r<p>
\r<dt> <var>host_info_count</var>
\r<dd>
\r[in/out scalar]
\rOn input, the maximum size of the buffer; on output, the
\rsize returned (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_info</strong> function returns selected information
\rabout a host, as specified
\rby <var>flavor</var>.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the memory size
\rreturned by <strong>HOST_BASIC_INFO</strong>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_get_boot_info.html"><strong>host_get_boot_info</strong></a>,
\r<a href="host_kernel_version.html"><strong>host_kernel_version</strong></a>,
\r<a href="host_statistics.html"><strong>host_statistics</strong></a>.
\r<p>
\rData Structures:
\r<a href="host_basic_info.html"><strong>host_basic_info</strong></a>,
\r<a href="host_sched_info.html"><strong>host_sched_info</strong></a>,
\r<a href="kernel_resource_sizes.html"><strong>kernel_resource_sizes</strong></a>.
\r\ No newline at end of file
+<h2>host_info</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return information about a host.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t host_info</strong>
+ <strong>(host_t</strong> <var>host</var>,
+ <strong>host_flavor_t</strong> <var>flavor</var>,
+ <strong>host_info_t</strong> <var>host_info</var>,
+ <strong>mach_msg_type_number_t</strong> <var>host_info_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host</var>
+<dd>
+[in host-name send right]
+The name (or control) port for the host for
+which information is to be obtained.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of statistics desired:
+<dl>
+<p>
+<dt> <strong>HOST_BASIC_INFO</strong>
+<dd>
+Basic information (number of processors, amount of
+memory). The returned structure is <strong>host_basic_info</strong>.
+<p>
+<dt> <strong>HOST_SCHED_INFO</strong>
+<dd>
+Basic restrictions of the kernel's scheduling, minimum
+quantum and time-out value. The returned structure is
+<strong>host_sched_info</strong>.
+<p>
+<dt> <strong>HOST_RESOURCE_SIZES</strong>
+<dd>
+This interface feature is not implemented in OSF/1 R1.3.
+Size of significant kernel structures, as a ledger would
+consider them when limiting kernel resource consumption. The
+returned structure is <strong>kernel_resource_sizes</strong>.
+</dl>
+<p>
+<dt> <var>host_info</var>
+<dd>
+[out structure]
+Statistics about the specified host.
+<p>
+<dt> <var>host_info_count</var>
+<dd>
+[in/out scalar]
+On input, the maximum size of the buffer; on output, the
+size returned (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_info</strong> function returns selected information
+about a host, as specified
+by <var>flavor</var>.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the memory size
+returned by <strong>HOST_BASIC_INFO</strong>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_get_boot_info.html"><strong>host_get_boot_info</strong></a>,
+<a href="host_kernel_version.html"><strong>host_kernel_version</strong></a>,
+<a href="host_statistics.html"><strong>host_statistics</strong></a>.
+<p>
+Data Structures:
+<a href="host_basic_info.html"><strong>host_basic_info</strong></a>,
+<a href="host_sched_info.html"><strong>host_sched_info</strong></a>,
+<a href="kernel_resource_sizes.html"><strong>kernel_resource_sizes</strong></a>.
-<h2>host_kernel_version</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return kernel version information for a host.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t host_kernel_version</strong>
\r <strong>(host_t</strong> <var>host</var>,
\r <strong>kernel_version_t</strong> <var>version</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host</var>
\r<dd>
\r[in host-name send right]
\rThe name (or control) port for the host for
\rwhich information is to be obtained.
\r<p>
\r<dt> <var>version</var>
\r<dd>
\r[out array of <var>char</var>]
\rCharacter string describing the kernel version
\rexecuting on <var>host</var>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_kernel_version</strong> function returns the version
\rstring compiled into the
\rkernel executing on <var>host</var> at the time it was built. This describes
\rthe version of the kernel. The constant <strong>KERNEL_VERSION_MAX</strong> (in
\r\*L<mach/host_info.h>\*O)
\rshould be used to dimension storage for the returned string if the
\r<var>kernel_version_t</var> declaration is not used.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_info.html"><strong>host_info</strong></a>.
\r\ No newline at end of file
+<h2>host_kernel_version</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return kernel version information for a host.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t host_kernel_version</strong>
+ <strong>(host_t</strong> <var>host</var>,
+ <strong>kernel_version_t</strong> <var>version</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host</var>
+<dd>
+[in host-name send right]
+The name (or control) port for the host for
+which information is to be obtained.
+<p>
+<dt> <var>version</var>
+<dd>
+[out array of <var>char</var>]
+Character string describing the kernel version
+executing on <var>host</var>.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_kernel_version</strong> function returns the version
+string compiled into the
+kernel executing on <var>host</var> at the time it was built. This describes
+the version of the kernel. The constant <strong>KERNEL_VERSION_MAX</strong> (in
+\*L<mach/host_info.h>\*O)
+should be used to dimension storage for the returned string if the
+<var>kernel_version_t</var> declaration is not used.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_info.html"><strong>host_info</strong></a>.
-<h2>host_load_info</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Used to present a host's processor load information.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#define CPU_STATE_USER 0</strong>
\r\r<strong>#define CPU_STATE_SYSTEM 1</strong>
\r\r<strong>#define CPU_STATE_IDLE 2</strong>
\r\r<strong>struct host_load_info</strong>
\r<strong>{</strong>
\r <strong>integer_t</strong> <var>avenrun</var><strong>[3];</strong>
\r <strong>integer_t</strong> <var>mach_factor</var><strong>[3];</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct host_load_info* host_load_info_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>avenrun</var>
\r<dd>
\rload average--average number of runnable processes divided by
\rnumber of CPUs
\r<p>
\r<dt> <var>mach_factor</var>
\r<dd>
\rThe processing resources available to a new thread--the number of
\rCPUs divided by (1 + the number of threads)
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_load_info</strong> structure defines the loading information
\ravailable about a
\rhost. The information returned is exponential averages over three periods of
\rtime: 5, 30 and 60 seconds.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_statistics.html"><strong>host_statistics</strong></a>.
\r<p>
\rData Structures:
\r<a href="host_basic_info.html"><strong>host_basic_info</strong></a>,
\r<a href="host_sched_info.html"><strong>host_sched_info</strong></a>.
\r\r\ No newline at end of file
+<h2>host_load_info</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Used to present a host's processor load information.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#define CPU_STATE_USER 0</strong>
+
+<strong>#define CPU_STATE_SYSTEM 1</strong>
+
+<strong>#define CPU_STATE_IDLE 2</strong>
+
+<strong>struct host_load_info</strong>
+<strong>{</strong>
+ <strong>integer_t</strong> <var>avenrun</var><strong>[3];</strong>
+ <strong>integer_t</strong> <var>mach_factor</var><strong>[3];</strong>
+<strong>};</strong>
+
+<strong>typedef struct host_load_info* host_load_info_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>avenrun</var>
+<dd>
+load average--average number of runnable processes divided by
+number of CPUs
+<p>
+<dt> <var>mach_factor</var>
+<dd>
+The processing resources available to a new thread--the number of
+CPUs divided by (1 + the number of threads)
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_load_info</strong> structure defines the loading information
+available about a
+host. The information returned is exponential averages over three periods of
+time: 5, 30 and 60 seconds.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_statistics.html"><strong>host_statistics</strong></a>.
+<p>
+Data Structures:
+<a href="host_basic_info.html"><strong>host_basic_info</strong></a>,
+<a href="host_sched_info.html"><strong>host_sched_info</strong></a>.
+
-<h2>host_page_size</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Provide the system's virtual page size.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t host_page_size</strong>
\r <strong>(host_t</strong> <var>host</var>,
\r <strong>vm_size_t</strong> <var>page_size</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host</var>
\r<dd>
\r[in host-name send right]
\rThe name (or control) port for the host for
\rwhich the page size is desired.
\r<p>
\r<dt> <var>page_size</var>
\r<dd>
\r[out scalar]
\rThe host's page size (in bytes).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_page_size</strong> function returns the page size for the given host.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_host_self.html"><strong>mach_host_self</strong></a>.
\r\ No newline at end of file
+<h2>host_page_size</h2>
+<hr>
+<p>
+<strong>Function</strong> - Provide the system's virtual page size.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t host_page_size</strong>
+ <strong>(host_t</strong> <var>host</var>,
+ <strong>vm_size_t</strong> <var>page_size</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host</var>
+<dd>
+[in host-name send right]
+The name (or control) port for the host for
+which the page size is desired.
+<p>
+<dt> <var>page_size</var>
+<dd>
+[out scalar]
+The host's page size (in bytes).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_page_size</strong> function returns the page size for the given host.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_host_self.html"><strong>mach_host_self</strong></a>.
-<h2>host_processor_set_priv</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Translate a processor set name port
\r into a processor set control port.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t host_processor_set_priv</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>processor_set_name_t</strong> <var>set_name</var>,
\r <strong>processor_set_t</strong> <var>processor_set</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host_priv</var>
\r<dd>
\r[in host-control send right]
\rThe control port for the host for which the
\rprocessor set is desired.
\r<p>
\r<dt> <var>set_name</var>
\r<dd>
\r[in processor-set-name send right]
\rThe name port for the processor set
\rdesired.
\r<p>
\r<dt> <var>processor_set</var>
\r<dd>
\r[out processor-set-control send right]
\rThe returned processor set
\rcontrol port.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_processor_set_priv</strong> function returns send rights
\rfor the control port
\rfor a specified processor set currently existing on <var>host_priv</var>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_processor_sets.html"><strong>host_processor_sets</strong></a>,
\r<a href="processor_set_create.html"><strong>processor_set_create</strong></a>,
\r<a href="processor_set_tasks.html"><strong>processor_set_tasks</strong></a>,
\r<a href="processor_set_threads.html"><strong>processor_set_threads</strong></a>.
\r\ No newline at end of file
+<h2>host_processor_set_priv</h2>
+<hr>
+<p>
+<strong>Function</strong> - Translate a processor set name port
+ into a processor set control port.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t host_processor_set_priv</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>processor_set_name_t</strong> <var>set_name</var>,
+ <strong>processor_set_t</strong> <var>processor_set</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host_priv</var>
+<dd>
+[in host-control send right]
+The control port for the host for which the
+processor set is desired.
+<p>
+<dt> <var>set_name</var>
+<dd>
+[in processor-set-name send right]
+The name port for the processor set
+desired.
+<p>
+<dt> <var>processor_set</var>
+<dd>
+[out processor-set-control send right]
+The returned processor set
+control port.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_processor_set_priv</strong> function returns send rights
+for the control port
+for a specified processor set currently existing on <var>host_priv</var>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_processor_sets.html"><strong>host_processor_sets</strong></a>,
+<a href="processor_set_create.html"><strong>processor_set_create</strong></a>,
+<a href="processor_set_tasks.html"><strong>processor_set_tasks</strong></a>,
+<a href="processor_set_threads.html"><strong>processor_set_threads</strong></a>.
-<h2>host_processor_sets</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return a list of send rights representing all processor set name ports.
\r\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t host_processor_sets</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>processor_set_name_port_array_t</strong><var>processor_set_name_list</var>,
\r <strong>host_priv</strong> <var>processor_set_name_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host_priv</var>
\r<dd>
\r[in host-control send right]
\rThe control port for the host for which the
\rprocessor sets are desired.
\r<p>
\r<dt> <var>processor_set_name_list</var>
\r<dd>
\r[out pointer to dynamic array of processor-set-name send rights]
\rThe
\rset of processor set name ports for those currently existing on
\r<var>host_priv</var>; no particular order is guaranteed.
\r<p>
\r<dt> <var>processor_set_name_count</var>
\r<dd>
\r[out scalar]
\rThe number of processor set names returned.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_processor_sets</strong> function returns send rights
\rfor the name ports for
\reach processor set currently existing on host.
\r<h3>NOTES</h3>
\r<p>
\rIf control ports to the processor sets are needed, use
\r<strong>host_processor_set_priv</strong>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_processor_set_priv.html"><strong>host_processor_set_priv</strong></a>,
\r<a href="processor_set_create.html"><strong>processor_set_create</strong></a>,
\r<a href="processor_set_tasks.html"><strong>processor_set_tasks</strong></a>,
\r<a href="processor_set_threads.html"><strong>processor_set_threads</strong></a>.
\r\ No newline at end of file
+<h2>host_processor_sets</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return a list of send rights representing all processor set name ports.
+
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t host_processor_sets</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>processor_set_name_port_array_t</strong><var>processor_set_name_list</var>,
+ <strong>host_priv</strong> <var>processor_set_name_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host_priv</var>
+<dd>
+[in host-control send right]
+The control port for the host for which the
+processor sets are desired.
+<p>
+<dt> <var>processor_set_name_list</var>
+<dd>
+[out pointer to dynamic array of processor-set-name send rights]
+The
+set of processor set name ports for those currently existing on
+<var>host_priv</var>; no particular order is guaranteed.
+<p>
+<dt> <var>processor_set_name_count</var>
+<dd>
+[out scalar]
+The number of processor set names returned.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_processor_sets</strong> function returns send rights
+for the name ports for
+each processor set currently existing on host.
+<h3>NOTES</h3>
+<p>
+If control ports to the processor sets are needed, use
+<strong>host_processor_set_priv</strong>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_processor_set_priv.html"><strong>host_processor_set_priv</strong></a>,
+<a href="processor_set_create.html"><strong>processor_set_create</strong></a>,
+<a href="processor_set_tasks.html"><strong>processor_set_tasks</strong></a>,
+<a href="processor_set_threads.html"><strong>processor_set_threads</strong></a>.
-<h2>host_processor_slots</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return a list of numbers that map processor slots to active processors.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t host_processor_slots</strong>
\r <strong>(host_t</strong> <var>host</var>,
\r <strong>processor_slot_t</strong> <var>slots</var>,
\r <strong>host</strong> <var>count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host</var>
\r<dd>
\r[in host-name send right]
\rThe name (or control) port for the host for
\rwhich information is to be obtained.
\r<p>
\r<dt> <var>slots</var>
\r<dd>
\r[out array of <var>processor_slot_t</var>]
\rAn array of the processor slot numbers
\rfor active processors.
\r<p>
\r<dt> <var>count</var>
\r<dd>
\r[pointer to in/out scalar]
\rOn input, the maximum size of the slots
\rbuffer; on output, the number of returned slot numbers.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_processor_slots</strong> function returns an array
\rof the processor slots
\rdefined for the host.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_info.html"><strong>host_info</strong></a>,
\r<a href="host_processors.html"><strong>host_processors</strong></a>,
\r<a href="processor_info.html"><strong>processor_info</strong></a>.
\r\ No newline at end of file
+<h2>host_processor_slots</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return a list of numbers that map processor slots to active processors.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t host_processor_slots</strong>
+ <strong>(host_t</strong> <var>host</var>,
+ <strong>processor_slot_t</strong> <var>slots</var>,
+ <strong>host</strong> <var>count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host</var>
+<dd>
+[in host-name send right]
+The name (or control) port for the host for
+which information is to be obtained.
+<p>
+<dt> <var>slots</var>
+<dd>
+[out array of <var>processor_slot_t</var>]
+An array of the processor slot numbers
+for active processors.
+<p>
+<dt> <var>count</var>
+<dd>
+[pointer to in/out scalar]
+On input, the maximum size of the slots
+buffer; on output, the number of returned slot numbers.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_processor_slots</strong> function returns an array
+of the processor slots
+defined for the host.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_info.html"><strong>host_info</strong></a>,
+<a href="host_processors.html"><strong>host_processors</strong></a>,
+<a href="processor_info.html"><strong>processor_info</strong></a>.
-<h2>host_processors</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return a list of send rights representing all processor ports.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t host_processors</strong>
\r <strong>(host_t</strong> <var>host_priv</var>,
\r <strong>processor_port_array_t</strong> <var>processor_list</var>,
\r <strong>host_priv</strong> <var>processor_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host_priv</var>
\r<dd>
\r[in host-control send right]
\rThe control port for the desired host.
\r<p>
\r<dt> <var>processor_list</var>
\r<dd>
\r[out pointer to dynamic array of processor send rights]
\rThe set of
\rprocessors existing on <var>host_priv</var>; no particular order is guaranteed.
\r<p>
\r<dt> <var>processor_count</var>
\r<dd>
\r[out scalar]
\rThe number of ports returned in <var>processor_list</var>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_processors</strong> function returns an array of send
\rright ports for each
\rprocessor existing on <var>host_priv</var>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_start.html"><strong>processor_start</strong></a>,
\r<a href="processor_exit.html"><strong>processor_exit</strong></a>,
\r<a href="processor_info.html"><strong>processor_info</strong></a>,
\r<a href="processor_control.html"><strong>processor_control</strong></a>,
\r<a href="host_processor_slots.html"><strong>host_processor_slots</strong></a>.
\r\ No newline at end of file
+<h2>host_processors</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return a list of send rights representing all processor ports.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t host_processors</strong>
+ <strong>(host_t</strong> <var>host_priv</var>,
+ <strong>processor_port_array_t</strong> <var>processor_list</var>,
+ <strong>host_priv</strong> <var>processor_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host_priv</var>
+<dd>
+[in host-control send right]
+The control port for the desired host.
+<p>
+<dt> <var>processor_list</var>
+<dd>
+[out pointer to dynamic array of processor send rights]
+The set of
+processors existing on <var>host_priv</var>; no particular order is guaranteed.
+<p>
+<dt> <var>processor_count</var>
+<dd>
+[out scalar]
+The number of ports returned in <var>processor_list</var>.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_processors</strong> function returns an array of send
+right ports for each
+processor existing on <var>host_priv</var>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_start.html"><strong>processor_start</strong></a>,
+<a href="processor_exit.html"><strong>processor_exit</strong></a>,
+<a href="processor_info.html"><strong>processor_info</strong></a>,
+<a href="processor_control.html"><strong>processor_control</strong></a>,
+<a href="host_processor_slots.html"><strong>host_processor_slots</strong></a>.
-<h2>host_reboot</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Reboot this host.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t host_reboot</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>int</strong> <var>options</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host_priv</var>
\r<dd>
\r[in host-control send right]
\rThe control port the host to be re-booted.
\r<p>
\r<dt> <var>options</var>
\r<dd>
\r[in scalar]
\rReboot options. See \*L<mach/host_reboot.h>\*O for details.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_reboot</strong> function reboots the specified host.
\r<h3>NOTES</h3>
\r<p>
\rIf successful, this call will not return.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rNone.
\r\ No newline at end of file
+<h2>host_reboot</h2>
+<hr>
+<p>
+<strong>Function</strong> - Reboot this host.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t host_reboot</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>int</strong> <var>options</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host_priv</var>
+<dd>
+[in host-control send right]
+The control port the host to be re-booted.
+<p>
+<dt> <var>options</var>
+<dd>
+[in scalar]
+Reboot options. See \*L<mach/host_reboot.h>\*O for details.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_reboot</strong> function reboots the specified host.
+<h3>NOTES</h3>
+<p>
+If successful, this call will not return.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+None.
-<h2>host_sched_info</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Used to present the set of scheduler limits associated
\r with the host.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct host_sched_info</strong>
\r<strong>{</strong>
\r <strong>integer_t</strong> <var>min_timeout</var><strong>;</strong>
\r <strong>integer_t</strong> <var>min_quantum</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct host_sched_info* host_sched_info_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>min_timeout</var>
\r<dd>
\rMinimum time-out, in milliseconds
\r<p>
\r<dt> <var>min_quantum</var>
\r<dd>
\rMinimum quantum (period for which a thread can be scheduled if
\runinterrupted), in milliseconds
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_sched_info</strong> structure defines the limiting
\rscheduling information
\ravailable about a host.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_info.html"><strong>host_info</strong></a>.
\r<p>
\rData Structures:
\r<a href="host_basic_info.html"><strong>host_basic_info</strong></a>,
\r<a href="host_load_info.html"><strong>host_load_info</strong></a>.
\r\ No newline at end of file
+<h2>host_sched_info</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Used to present the set of scheduler limits associated
+ with the host.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct host_sched_info</strong>
+<strong>{</strong>
+ <strong>integer_t</strong> <var>min_timeout</var><strong>;</strong>
+ <strong>integer_t</strong> <var>min_quantum</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct host_sched_info* host_sched_info_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>min_timeout</var>
+<dd>
+Minimum time-out, in milliseconds
+<p>
+<dt> <var>min_quantum</var>
+<dd>
+Minimum quantum (period for which a thread can be scheduled if
+uninterrupted), in milliseconds
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_sched_info</strong> structure defines the limiting
+scheduling information
+available about a host.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_info.html"><strong>host_info</strong></a>.
+<p>
+Data Structures:
+<a href="host_basic_info.html"><strong>host_basic_info</strong></a>,
+<a href="host_load_info.html"><strong>host_load_info</strong></a>.
-<h2>host_security_create_task_token</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Create a new task with an explicit security token.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t host_security_create_task_token</strong>
\r <strong>(host_security_t</strong> <var>host_security</var>,
\r <strong>task_t</strong> <var>parent_task</var>,
\r <strong>security_token_t</strong> <var>security_token</var>,
\r <strong>audit_token_t</strong> <var>audit_token</var>,
\r <strong>ledger_port_array_t</strong> <var>ledgers</var>,
\r <strong>boolean_t</strong> <var>inherit_memory</var>,
\r <strong>task_t</strong> <var>child_task</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt><var>host_security</var>
\r<dd>
\r[in security send right] The host's security port.
\r<p>
\r<dt><var>parent_task</var>
\r<dd>
\r[in task send right] The port for the task from which to draw the child
\rtask's port rights and address space.
\r<p>
\r<dt><var>security_token</var>
\r<dd>
\r[in scalar] The task's security token.
\r<p>
\r<dt><var>audit_token</var>
\r<dd>
\r[in scalar] The task's audit token.
\r<p>
\r<dt><var>ledgers</var>
\r<dd>
\r[pointer to in array of ledger send rights] The set of ledgers from which the
\rtask will draw its resources.
\r<p>
\r<dt><var>inherit_memory</var>
\r<dd>
\r[in scalar] Address space inheritance indicator. If true, the child task in-
\rherits the address space of the parent task. If false, the kernel assigns
\rthe child task an empty address space.
\r<p>
\r<dt><var>child_task</var>
\r<dd>
\r[out task send right] The kernel-assigned port name for the new task.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong><strong>host_security_create_task_token</strong> function creates a new task from
\r<var>parent_task</var> with explicit security and audit token values, returning the name of the
\rnew task in the parameter specified by <var>child_task</var>. Other than the security and audit token values, the child task
\ris as if created by <strong>task_create</strong>.
\r<h3>NOTES</h3>
\r<p>
\rThe host security port is a privileged port given to the system
\rbootstrap task for the use of this call.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_SECURITY</strong>
\r<dd>
\rThe value of <var>host_security</var> does not specify the security port for the host on which task lies.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_create.html"><strong>task_create</strong></a>,
\r<a href="host_security_set_task_token.html"><strong>host_security_set_task_token</strong></a>,
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>.
\r\ No newline at end of file
+<h2>host_security_create_task_token</h2>
+<hr>
+<p>
+<strong>Function</strong> - Create a new task with an explicit security token.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t host_security_create_task_token</strong>
+ <strong>(host_security_t</strong> <var>host_security</var>,
+ <strong>task_t</strong> <var>parent_task</var>,
+ <strong>security_token_t</strong> <var>security_token</var>,
+ <strong>audit_token_t</strong> <var>audit_token</var>,
+ <strong>ledger_port_array_t</strong> <var>ledgers</var>,
+ <strong>boolean_t</strong> <var>inherit_memory</var>,
+ <strong>task_t</strong> <var>child_task</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt><var>host_security</var>
+<dd>
+[in security send right] The host's security port.
+<p>
+<dt><var>parent_task</var>
+<dd>
+[in task send right] The port for the task from which to draw the child
+task's port rights and address space.
+<p>
+<dt><var>security_token</var>
+<dd>
+[in scalar] The task's security token.
+<p>
+<dt><var>audit_token</var>
+<dd>
+[in scalar] The task's audit token.
+<p>
+<dt><var>ledgers</var>
+<dd>
+[pointer to in array of ledger send rights] The set of ledgers from which the
+task will draw its resources.
+<p>
+<dt><var>inherit_memory</var>
+<dd>
+[in scalar] Address space inheritance indicator. If true, the child task in-
+herits the address space of the parent task. If false, the kernel assigns
+the child task an empty address space.
+<p>
+<dt><var>child_task</var>
+<dd>
+[out task send right] The kernel-assigned port name for the new task.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong><strong>host_security_create_task_token</strong> function creates a new task from
+<var>parent_task</var> with explicit security and audit token values, returning the name of the
+new task in the parameter specified by <var>child_task</var>. Other than the security and audit token values, the child task
+is as if created by <strong>task_create</strong>.
+<h3>NOTES</h3>
+<p>
+The host security port is a privileged port given to the system
+bootstrap task for the use of this call.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_SECURITY</strong>
+<dd>
+The value of <var>host_security</var> does not specify the security port for the host on which task lies.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_create.html"><strong>task_create</strong></a>,
+<a href="host_security_set_task_token.html"><strong>host_security_set_task_token</strong></a>,
+<a href="mach_msg.html"><strong>mach_msg</strong></a>.
-<h2>host_security_set_task_token</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Change the target task's security token.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t host_security_set_task_token</strong>
\r <strong>(host_security_t</strong> <var>host_security</var>,
\r <strong>task_t</strong> <var>task</var>,
\r <strong>security_token_t</strong> <var>security_token</var>,
\r <strong>audit_token_t</strong> <var>audit_token</var>,
\r <strong>host_t</strong> <var>host</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt><var>host_security</var>
\r<dd>
\r[in security send right] The host's security port.
\r<p>
\r<dt><var>task</var>
\r<dd>
\r[in task send right] The port for the task for which the token is to be set.
\r<p>
\r<dt><var>security_token</var>
\r<dd>
\r[in scalar] The new security token.
\r<p>
\r<dt><var>audit_token</var>
\r<dd>
\r[in scalar] The new audit token.
\r<p>
\r<dt><var>host</var>
\r<dd>
\r[in host send right] The task's new host-self port.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_security_set_task_token</strong> function changes the
\rspecified task's security and audit tokens; the new tokens will be
\rincluded in all subsequent messages sent from the task. The
\rinitial value of a task's security and audit tokens is that of its
\rparent.
\r<h3>NOTES</h3>
\r<p>
\rThe host security port is a privileged port given to the system
\rbootstrap task for the use of this call.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_SECURITY</strong>
\r<dd>
\rThe value of <var>host_security</var> does not specify the security port for the host on which task lies.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_create.html"><strong>task_create</strong></a>,
\r<a href="task_info.html"><strong>task_info</strong></a>,
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>.
\r\ No newline at end of file
+<h2>host_security_set_task_token</h2>
+<hr>
+<p>
+<strong>Function</strong> - Change the target task's security token.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t host_security_set_task_token</strong>
+ <strong>(host_security_t</strong> <var>host_security</var>,
+ <strong>task_t</strong> <var>task</var>,
+ <strong>security_token_t</strong> <var>security_token</var>,
+ <strong>audit_token_t</strong> <var>audit_token</var>,
+ <strong>host_t</strong> <var>host</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt><var>host_security</var>
+<dd>
+[in security send right] The host's security port.
+<p>
+<dt><var>task</var>
+<dd>
+[in task send right] The port for the task for which the token is to be set.
+<p>
+<dt><var>security_token</var>
+<dd>
+[in scalar] The new security token.
+<p>
+<dt><var>audit_token</var>
+<dd>
+[in scalar] The new audit token.
+<p>
+<dt><var>host</var>
+<dd>
+[in host send right] The task's new host-self port.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_security_set_task_token</strong> function changes the
+specified task's security and audit tokens; the new tokens will be
+included in all subsequent messages sent from the task. The
+initial value of a task's security and audit tokens is that of its
+parent.
+<h3>NOTES</h3>
+<p>
+The host security port is a privileged port given to the system
+bootstrap task for the use of this call.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_SECURITY</strong>
+<dd>
+The value of <var>host_security</var> does not specify the security port for the host on which task lies.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_create.html"><strong>task_create</strong></a>,
+<a href="task_info.html"><strong>task_info</strong></a>,
+<a href="mach_msg.html"><strong>mach_msg</strong></a>.
-<h2>host_set_time</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Sets the time.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include< mach/mach_host.h></strong>
\r\r<strong>kern_return_t host_set_time</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>time_value_t</strong> <var>new_time</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host_priv</var>
\r<dd>
\r[in host-control port] The control port for the host for which the time is to be set.
\r<p>
\r<dt> <var>new_time</var>
\r<dd>
\r[in structure] Time to be set.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_set_time</strong> function establishes the time on the specified host.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_adjust_time.html"><strong>host_adjust_time</strong></a>,
\r<a href="host_get_time.html"><strong>host_get_time</strong></a>.
\r<p>
\rData Structures:
\rtime_value.
\r\ No newline at end of file
+<h2>host_set_time</h2>
+<hr>
+<p>
+<strong>Function</strong> - Sets the time.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include< mach/mach_host.h></strong>
+
+<strong>kern_return_t host_set_time</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>time_value_t</strong> <var>new_time</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host_priv</var>
+<dd>
+[in host-control port] The control port for the host for which the time is to be set.
+<p>
+<dt> <var>new_time</var>
+<dd>
+[in structure] Time to be set.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_set_time</strong> function establishes the time on the specified host.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_adjust_time.html"><strong>host_adjust_time</strong></a>,
+<a href="host_get_time.html"><strong>host_get_time</strong></a>.
+<p>
+Data Structures:
+time_value.
-<h2>host_statistics</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return statistics for a host.<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t host_statistics</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>host_flavor_t</strong> <var>flavor</var>,
\r <strong>host_info_t</strong> <var>host_info</var>,
\r <strong>mach_msg_type_number_t</strong> <var>host_info_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host_priv</var>
\r<dd>
\r[in host-control send right]
\rThe control port for the host for which
\rinformation is to be obtained.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of statistics desired.
\r<dl>
\r<p>
\r<dt> <strong>HOST_LOAD_INFO</strong>
\r<dd>
\rSystem loading statistics. The returned structure is
\r<strong>host_load_info</strong>.
\r<p>
\r<dt> <strong>HOST_VM_INFO</strong>
\r<dd>
\rVirtual memory statistics. The returned structure is
\r<strong>vm_statistics</strong>.
\r</dl>
\r<p>
\r<dt> <var>host_info</var>
\r<dd>
\r[out structure]
\rStatistics about the specified host.
\r<p>
\r<dt> <var>host_info_count</var>
\r<dd>
\r[in/out scalar]
\rOn input, the maximum size of the buffer; on output, the
\rsize returned (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>host_statistics</strong> function returns scheduling and
\rvirtual memory statistics
\rconcerning the host as specified by <var>flavor</var>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_info.html"><strong>host_info</strong></a>,
\r<a href="processor_set_statistics.html"><strong>processor_set_statistics</strong></a>.
\r<p>
\rData Structures:
\r<a href="host_load_info.html"><strong>host_load_info</strong></a>,
\r<a href="vm_statistics.html"><strong>vm_statistics</strong></a>.
\r\ No newline at end of file
+<h2>host_statistics</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return statistics for a host.<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t host_statistics</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>host_flavor_t</strong> <var>flavor</var>,
+ <strong>host_info_t</strong> <var>host_info</var>,
+ <strong>mach_msg_type_number_t</strong> <var>host_info_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host_priv</var>
+<dd>
+[in host-control send right]
+The control port for the host for which
+information is to be obtained.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of statistics desired.
+<dl>
+<p>
+<dt> <strong>HOST_LOAD_INFO</strong>
+<dd>
+System loading statistics. The returned structure is
+<strong>host_load_info</strong>.
+<p>
+<dt> <strong>HOST_VM_INFO</strong>
+<dd>
+Virtual memory statistics. The returned structure is
+<strong>vm_statistics</strong>.
+</dl>
+<p>
+<dt> <var>host_info</var>
+<dd>
+[out structure]
+Statistics about the specified host.
+<p>
+<dt> <var>host_info_count</var>
+<dd>
+[in/out scalar]
+On input, the maximum size of the buffer; on output, the
+size returned (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>host_statistics</strong> function returns scheduling and
+virtual memory statistics
+concerning the host as specified by <var>flavor</var>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_info.html"><strong>host_info</strong></a>,
+<a href="processor_set_statistics.html"><strong>processor_set_statistics</strong></a>.
+<p>
+Data Structures:
+<a href="host_load_info.html"><strong>host_load_info</strong></a>,
+<a href="vm_statistics.html"><strong>vm_statistics</strong></a>.
-<h2>i386_get_ldt</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return per-thread segment descriptors.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t i386_get_ldt</strong>
\r <strong>(thread_act_t</strong> <var>target_act</var>,
\r <strong>int</strong> <var>first_selector</var>,
\r <strong>int</strong> <var>desired_count</var>,
\r <strong>descriptor_list_t</strong> <var>desc_list</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_act</var>
\r<dd>
\r[in thread send right]
\rThread whose segment descriptors are to be
\rreturned.
\r<p>
\r<dt> <var>first_selector</var>
\r<dd>
\r[in scalar] Selector value (segment register value) corresponding to the
\rfirst segment whose descriptor is to be returned.
\r<p>
\r<dt> <var>desired_count</var>
\r<dd>
\r[in scalar]
\rNumber of returned descriptors desired.
\r<p>
\r<dt> <var>desc_list</var>
\r<dd>
\r[out pointer to dynamic array of <strong>descriptor_t</strong>]
\rArray of segment
\rdescriptors.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>i386_get_ldt</strong> function returns per-thread segment
\rdescriptors from the
\rthread's local descriptor table (LDT).
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="i386_set_ldt.html"><strong>i386_set_ldt<strong></a>.
\r\ No newline at end of file
+<h2>i386_get_ldt</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return per-thread segment descriptors.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t i386_get_ldt</strong>
+ <strong>(thread_act_t</strong> <var>target_act</var>,
+ <strong>int</strong> <var>first_selector</var>,
+ <strong>int</strong> <var>desired_count</var>,
+ <strong>descriptor_list_t</strong> <var>desc_list</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_act</var>
+<dd>
+[in thread send right]
+Thread whose segment descriptors are to be
+returned.
+<p>
+<dt> <var>first_selector</var>
+<dd>
+[in scalar] Selector value (segment register value) corresponding to the
+first segment whose descriptor is to be returned.
+<p>
+<dt> <var>desired_count</var>
+<dd>
+[in scalar]
+Number of returned descriptors desired.
+<p>
+<dt> <var>desc_list</var>
+<dd>
+[out pointer to dynamic array of <strong>descriptor_t</strong>]
+Array of segment
+descriptors.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>i386_get_ldt</strong> function returns per-thread segment
+descriptors from the
+thread's local descriptor table (LDT).
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="i386_set_ldt.html"><strong>i386_set_ldt<strong></a>.
-<h2>i386_io_port_add</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Permit target thread to invoke operations on the specified device.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t i386_io_port_add</strong>
\r <strong>(thread_act_t</strong> <var>target_act</var>,
\r <strong>device_t</strong> <var>device</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_act</var>
\r<dd>
\r[in thread send right]
\rThread whose permission bitmap is to be set.
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right]
\rThe device to which I/O instructions are to be
\rpermitted.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>i386_io_port_add</strong> function adds a device to the
\rI/O permission bitmap for a
\rthread, thereby permitting the thread to execute I/O instructions against the
\rdevice.
\r<h3>NOTES</h3>
\r<p>
\rNormally, the thread must have called <strong>i386_io_port_add</strong>
\rfor all devices to which it will execute I/O instructions. However, possessing
\rsend rights to the <var>iopl</var> device port will cause the
\r<var>iopl</var> device to be automatically added to the
\rthread's I/O map upon first attempted access. This is a backward
\rcompatibility feature for the DOS emulator.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="i386_io_port_list.html"><strong>i386_io_port_list<strong></a>,
\r<a href="i386_io_port_remove.html"><strong>i386_io_port_remove<strong></a>.
\r\ No newline at end of file
+<h2>i386_io_port_add</h2>
+<hr>
+<p>
+<strong>Function</strong> - Permit target thread to invoke operations on the specified device.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t i386_io_port_add</strong>
+ <strong>(thread_act_t</strong> <var>target_act</var>,
+ <strong>device_t</strong> <var>device</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_act</var>
+<dd>
+[in thread send right]
+Thread whose permission bitmap is to be set.
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right]
+The device to which I/O instructions are to be
+permitted.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>i386_io_port_add</strong> function adds a device to the
+I/O permission bitmap for a
+thread, thereby permitting the thread to execute I/O instructions against the
+device.
+<h3>NOTES</h3>
+<p>
+Normally, the thread must have called <strong>i386_io_port_add</strong>
+for all devices to which it will execute I/O instructions. However, possessing
+send rights to the <var>iopl</var> device port will cause the
+<var>iopl</var> device to be automatically added to the
+thread's I/O map upon first attempted access. This is a backward
+compatibility feature for the DOS emulator.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="i386_io_port_list.html"><strong>i386_io_port_list<strong></a>,
+<a href="i386_io_port_remove.html"><strong>i386_io_port_remove<strong></a>.
-<h2>i386_io_port_list</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - List the devices that permit target thread to invoke operations.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t i386_io_port_list</strong>
\r <strong>(thread_act_t</strong> <var>target_act</var>,
\r <strong>device_list_t</strong> <var>device_list</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_act</var>
\r<dd>
\r[in thread send right]
\rThread whose permission list is to be returned.
\r<p>
\r<dt> <var>device_list</var>
\r<dd>
\r[out pointer to dynamic array of device send rights]
\rDevice ports
\rpermitting I/O.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>i386_io_port_list</strong> function returns a list of the
\rdevices named in the
\rthread's I/O permission bitmap, namely those permitting I/O instructions to be
\rexecuted against them.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="i386_io_port_add.html"><strong>i386_io_port_add<strong></a>,
\r<a href="i386_io_port_remove.html"><strong>i386_io_port_remove<strong></a>.
\r\ No newline at end of file
+<h2>i386_io_port_list</h2>
+<hr>
+<p>
+<strong>Function</strong> - List the devices that permit target thread to invoke operations.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t i386_io_port_list</strong>
+ <strong>(thread_act_t</strong> <var>target_act</var>,
+ <strong>device_list_t</strong> <var>device_list</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_act</var>
+<dd>
+[in thread send right]
+Thread whose permission list is to be returned.
+<p>
+<dt> <var>device_list</var>
+<dd>
+[out pointer to dynamic array of device send rights]
+Device ports
+permitting I/O.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>i386_io_port_list</strong> function returns a list of the
+devices named in the
+thread's I/O permission bitmap, namely those permitting I/O instructions to be
+executed against them.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="i386_io_port_add.html"><strong>i386_io_port_add<strong></a>,
+<a href="i386_io_port_remove.html"><strong>i386_io_port_remove<strong></a>.
-<h2>i386_io_port_remove</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Disable target thread's ability to invoke operations on the
\rspecified device.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t i386_io_port_remove</strong>
\r <strong>(thread_act_t</strong> <var>target_act</var>,
\r <strong>device_t</strong> <var>device</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_act</var>
\r<dd>
\r[in thread send right]
\rThread whose permission bitmap is to be cleared
\r<p>
\r<dt> <var>device</var>
\r<dd>
\r[in device send right]
\rDevice whose permission is to be revoked
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>i386_io_port_remove</strong> function removes the specified
\rdevice from the
\rthread's I/O permission bitmap, thereby prohibiting I/O instructions being
\rexecuted against the device.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="i386_io_port_add.html"><strong>i386_io_port_add<strong></a>,
\r<a href="i386_io_port_list.html"><strong>i386_io_port_list<strong></a>.
\r\ No newline at end of file
+<h2>i386_io_port_remove</h2>
+<hr>
+<p>
+<strong>Function</strong> - Disable target thread's ability to invoke operations on the
+specified device.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t i386_io_port_remove</strong>
+ <strong>(thread_act_t</strong> <var>target_act</var>,
+ <strong>device_t</strong> <var>device</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_act</var>
+<dd>
+[in thread send right]
+Thread whose permission bitmap is to be cleared
+<p>
+<dt> <var>device</var>
+<dd>
+[in device send right]
+Device whose permission is to be revoked
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>i386_io_port_remove</strong> function removes the specified
+device from the
+thread's I/O permission bitmap, thereby prohibiting I/O instructions being
+executed against the device.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="i386_io_port_add.html"><strong>i386_io_port_add<strong></a>,
+<a href="i386_io_port_list.html"><strong>i386_io_port_list<strong></a>.
-<h2>i386_set_ldt</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set per-thread segment descriptors.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t i386_set_ldt</strong>
\r <strong>(thread_act_t</strong> <var>target_act</var>,
\r <strong>int</strong> <var>first_selector</var>,
\r <strong>descriptor_list_t</strong> <var>desc_list</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_act</var>
\r<dd>
\r[in thread send right]
\rThread whose segment descriptors are to be set.
\r<p>
\r<dt> <var>first_selector</var>
\r<dd>
\r[in scalar]
\rSelector value (segment register value) corresponding to the
\rfirst segment whose descriptor is to be set.
\r<p>
\r<dt> <var>desc_list</var>
\r<dd>
\r[pointer to in array of <strong>descriptor_t</strong>]
\rArray of segment descriptors. The
\rfollowing forms are permitted:
\r<ul>
\r<p>
\r<li>
\rEmpty descriptor. The <strong>ACC_P</strong> flag (segment present) may or may
\rnot be set.
\r<p>
\r<li>
\r<strong>ACC_CALL_GATE</strong>--Converted into a system call gate. The
\r<strong>ACC_P</strong> flag must be set.
\r</ul>
\r<p>
\rAll other descriptors must have both the <strong>ACC_P</strong> flag set and specify
\ruser mode access (<strong>ACC_PL_U</strong>).
\r<ul>
\r<p>
\r<li>
\r<strong>ACC_DATA</strong>.
\r<p>
\r<li>
\r<strong>ACC_DATA_W</strong>.
\r<p>
\r<li>
\r<strong>ACC_DATA_E</strong>.
\r<p>
\r<li>
\r<strong>ACC_DATA_EW</strong>.
\r<p>
\r<li>
\r<strong>ACC_CODE</strong>.
\r<p>
\r<li>
\r<strong>ACC_CODE_R</strong>.
\r<p>
\r<li>
\r<strong>ACC_CODE_C</strong>.
\r<p>
\r<li>
\r<strong>ACC_CODE_CR</strong>.
\r<p>
\r<li>
\r<strong>ACC_CALL_GATE_16</strong>.
\r<p>
\r<li>
\r<strong>ACC_CALL_GATE</strong>.
\r</ul>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>i386_set_ldt</strong> function allows a thread to have a
\rprivate local descriptor
\rtable (LDT) which allows its local segments to map various ranges
\rof its address
\rspace.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="i386_get_ldt.html"><strong>i386_get_ldt<strong></a>.
\r\ No newline at end of file
+<h2>i386_set_ldt</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set per-thread segment descriptors.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t i386_set_ldt</strong>
+ <strong>(thread_act_t</strong> <var>target_act</var>,
+ <strong>int</strong> <var>first_selector</var>,
+ <strong>descriptor_list_t</strong> <var>desc_list</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_act</var>
+<dd>
+[in thread send right]
+Thread whose segment descriptors are to be set.
+<p>
+<dt> <var>first_selector</var>
+<dd>
+[in scalar]
+Selector value (segment register value) corresponding to the
+first segment whose descriptor is to be set.
+<p>
+<dt> <var>desc_list</var>
+<dd>
+[pointer to in array of <strong>descriptor_t</strong>]
+Array of segment descriptors. The
+following forms are permitted:
+<ul>
+<p>
+<li>
+Empty descriptor. The <strong>ACC_P</strong> flag (segment present) may or may
+not be set.
+<p>
+<li>
+<strong>ACC_CALL_GATE</strong>--Converted into a system call gate. The
+<strong>ACC_P</strong> flag must be set.
+</ul>
+<p>
+All other descriptors must have both the <strong>ACC_P</strong> flag set and specify
+user mode access (<strong>ACC_PL_U</strong>).
+<ul>
+<p>
+<li>
+<strong>ACC_DATA</strong>.
+<p>
+<li>
+<strong>ACC_DATA_W</strong>.
+<p>
+<li>
+<strong>ACC_DATA_E</strong>.
+<p>
+<li>
+<strong>ACC_DATA_EW</strong>.
+<p>
+<li>
+<strong>ACC_CODE</strong>.
+<p>
+<li>
+<strong>ACC_CODE_R</strong>.
+<p>
+<li>
+<strong>ACC_CODE_C</strong>.
+<p>
+<li>
+<strong>ACC_CODE_CR</strong>.
+<p>
+<li>
+<strong>ACC_CALL_GATE_16</strong>.
+<p>
+<li>
+<strong>ACC_CALL_GATE</strong>.
+</ul>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>i386_set_ldt</strong> function allows a thread to have a
+private local descriptor
+table (LDT) which allows its local segments to map various ranges
+of its address
+space.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="i386_get_ldt.html"><strong>i386_get_ldt<strong></a>.
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
\r<html>
\r<head>
\r <title>Mach Kernel Interface Reference Manual</title>
\r</head>
\r<body>
\r<h3>Mach IPC Interface</h3>
\r<blockquote>
\r<p>
\rMach IPC presents itself in a few forms: message queues, lock-sets,
\rand semaphores (more may be added in the future). All share one common
\rcharateristic: the capabilities presented by each are represented through
\ra handle known as a Mach port. Specific rights represented in these
\rMach port capability handles allow the underlying IPC object to be used and
\rmanipulated in consistent ways.</p>
\r\r<h4>Mach Message Queue Interface</h4>
\r<blockquote>
\r<p>
\r<a href="mach_msg.html">mach_msg</a> - Send and/or receive a message from the target port.<br>
\r<a href="mach_msg.html">mach_msg_overwrite</a> - Send and/or receive messages with possible overwrite.<br>
\r</p>
\rMach Message Queue Data Structures
\r<p>
\r<a href="mach_msg_descriptor.html">mach_msg_descriptor</a> - Specifies an element of a complex IPC message.<br>
\r<a href="mach_msg_header.html">mach_msg_header</a> - Specifies the content of an IPC message header.<br>
\r</p>
\r</blockquote>
\r\r<h4>Mach Lock-Set Interface</h4>
\r<blockquote>
\r<p>
\r<a href="lock_acquire.html">lock_acquire</a> - Acquire ownership a lock<br>
\r<a href="lock_handoff.html">lock_handoff</a> - Hand-off ownership of a lock.<br>
\r<a href="lock_handoff_accept.html">lock_handoff_accept</a> - Accept lock ownership from a handoff.<br>
\r<a href="lock_make_stable.html">lock_make_stable</a> - Stabilize the state of the specified lock.<br>
\r<a href="lock_release.html">lock_release</a> - Release ownership of a lock.<br>
\r<a href="lock_set_create.html">lock_set_create</a> - Create a new lock set.<br>
\r<a href="lock_set_destroy.html">lock_set_destroy</a> - Destroy a lock set and its associated locks.<br>
\r<a href="lock_try.html">lock_try</a> - Attempt to acquire access rights to a lock.<br>
\r</p>
\r</blockquote>
\r\r<h4>Mach Semaphore Interface</h4>
\r<blockquote>
\r<p>
\r<a href="semaphore_create.html">semaphore_create</a> - Create a new semaphore.<br>
\r<a href="semaphore_destroy.html">semaphore_destroy</a> - Destroy a semaphore.<br>
\r<a href="semaphore_signal.html">semaphore_signal</a> - Increments the semaphore count.<br>
\r<a href="semaphore_signal_all.html">semaphore_signal_all</a> - Wake up all threads blocked on a semaphore.<br>
\r<a href="semaphore_wait.html">semaphore_wait</a> - Wait on the specified semaphore.<br>
\r</p>
\r</blockquote>
\r\r<h4>Mach Port Management Interface</h4>
\r<blockquote>
\r<p>
\r<a href="mach_port_allocate.html">mach_port_allocate</a> - Create caller-specified type of port right.<br>
\r<a href="mach_port_allocate_full.html">mach_port_allocate_full</a> - Create a port right with full Mach port semantics.<br>
\r<a href="mach_port_allocate_name.html">mach_port_allocate_name</a> - Create a port right with the caller-specified name.<br>
\r<a href="mach_port_allocate_qos.html">mach_port_allocate_qos</a> - Allocate a port with specified "quality of service".<br>
\r<a href="MP_allocate_subsystem.html">mach_port_allocate_subsystem</a> - Create a port right associated with the caller-specified subsystem.<br>
\r<a href="mach_port_deallocate.html">mach_port_deallocate</a> - Decrement the target port right's user reference count.<br>
\r<a href="mach_port_destroy.html">mach_port_destroy</a> - Deallocate all port rights associated with specified name.<br>
\r<a href="mach_port_extract_right.html">mach_port_extract_right</a> - Remove the specified right from the target task and return it to the caller.<br>
\r<a href="mach_port_get_attributes.html">mach_port_get_attributes</a> - Return information about target port as specified by the caller.<br>
\r<a href="mach_port_get_refs.html">mach_port_get_refs</a> - Return the current count of user references on the target port right.<br>
\r<a href="mach_port_get_set_status.html">mach_port_get_set_status</a> - Return the port right names contained in the target port set.<br>
\r<a href="mach_port_insert_right.html">mach_port_insert_right</a> - Insert the specified port right into the target task.<br>
\r<a href="mach_port_mod_refs.html">mach_port_mod_refs</a> - Modify the specified port right's count of user references.<br>
\r<a href="mach_port_move_member.html">mach_port_move_member</a> - Move the specified receive right into or out of the specified port set.<br>
\r<a href="mach_port_names.html">mach_port_names</a> - Return information about a task's port name space.<br>
\r<a href="MP_request_notification.html">mach_port_request_notification</a> - Request notification of the specified port event type.<br>
\r<a href="mach_port_set_attributes.html">mach_port_set_attributes</a> - Set the target port's attributes.<br>
\r<a href="mach_port_set_mscount.html">mach_port_set_mscount</a> - Change the target port's make-send count.<br>
\r<a href="mach_port_set_seqno.html">mach_port_set_seqno</a> - Change the current value of the target port's sequence number.<br>
\r<a href="mach_port_type.html">mach_port_type</a> - Return the characteristics of the target port name.<br>
\r<a href="mach_reply_port.html">mach_reply_port</a> - Allocate a new port and insert corresponding receive right in the calling task.<br>
\r<a href="mach_subsystem_create.html"> mach_subsystem_create</a> - Used by a server to register information about an RPC subsystem with the kernel.<br>
\r</p>
\rMach Port Data Structures
\r<p>
\r<a href="mach_port_limits.html">mach_port_limits</a> - Specifies a port's resource and message queue limits.<br>
\r<a href="mach_port_qos.html">mach_port_qos</a> - Specifies a port's attributes with respect to "Quality Of Service."<br>
\r<a href="mach_port_status.html">mach_port_status</a> - Used to present a port's current status with respect to various important attributes.<br>
\r</p>
\rMach Port Notification Callbacks
\r<p>
\r<a href="do_mach_notify_dead_name.html">do_mach_notify_dead_name</a> - Handle the current instance of a dead-name notification.<br>
\r<a href="do_mach_notify_no_senders.html">do_mach_notify_no_senders</a> - Handle the current instance of a no-more-senders notification.<br>
\r<a href="DMN_port_deleted.html">do_mach_notify_port_deleted</a> - Handle the current instance of a port-deleted notification.<br>
\r<a href="DMN_port_destroyed.html">do_mach_notify_port_destroyed</a> - Handle the current instance of a port-destroyed notification.<br>
\r<a href="do_mach_notify_send_once.html">do_mach_notify_send_once</a> - Handle the current instance of a send-once notification.<br>
\r</p>
\rMach Port Notification Callback Server Helpers
\r<p>
\r<a href="notify_server.html">notify_server</a> - Detect and handle a kernel-generated IPC notification.<br>
\r</p>
\r</blockquote>
\r\r</blockquote>
\r\r<h3>Mach Virtual Memory Interface</h3>
\r<blockquote>
\r<h4>Mach Virtual Memory Address Space Manipulation Interface</h4>
\r<blockquote>
\r<p>
\r<a href="host_page_size.html">host_page_size</a> - Provide the system's virtual page size.<br>
\r<a href="vm_allocate.html">vm_allocate</a> - Allocate a region of virtual memory.<br>
\r<a href="vm_behavior_set.html">vm_behavior_set</a> - Specify expected access patterns for the target VM region.<br>
\r<a href="vm_copy.html">vm_copy</a> - Copy a region of virtual memory.<br>
\r<a href="vm_deallocate.html">vm_deallocate</a> - Deallocate a region of virtual memory.<br>
\r<a href="vm_inherit.html">vm_inherit</a> - Set a VM region's inheritance attribute.<br>
\r<a href="vm_machine_attribute.html">vm_machine_attribute</a> - Get/set the target memory region's special attributes.<br>
\r<a href="vm_map.html">vm_map</a> - Map the specified memory object to a region of virtual memory.<br>
\r<a href="vm_msync.html">vm_msync</a> - Synchronize the specified region of virtual memory.<br>
\r<a href="vm_protect.html">vm_protect</a> - Set access privilege attribute for a region of virtual memory.<br>
\r<a href="vm_read.html">vm_read</a> - Read the specified range of target task's address space.<br>
\r<a href="vm_region.html">vm_region</a> - Return description of a virtual memory region.<br>
\r<a href="vm_remap.html">vm_remap</a> - Map memory objects in one address space to that of another's.<br>
\r<a href="vm_wire.html"> vm_wire</a> - Modify the target region's paging characteristics.<br>
\r<a href="vm_write.html">vm_write</a> - Write data to the specified address in the target address space.<br>
\r</p>
\rData Structures
\r<p>
\r<a href="vm_region_basic_info.html">vm_region_basic_info</a> - Defines the attributes of a task's memory region.<br>
\r<a href="vm_statistics.html">vm_statistics</a> - Defines statistics for the kernel's use of virtual memory.<br>
\r</p>
\r</blockquote>
\r\r<h4>External Memory Management Interface</h4>
\r<blockquote>
\rThe External Memory Management Interface (EMMI) is undergoing significant change in the Darwin system.
\rFor this reason, the interface is not currently available to user-level programs. Even for kernel
\rextensions, use of these interfaces in not supported. Instead, the BSD filesystem's Universal Buffer Cache (UBC)
\rmechanism should be used.<br>
\r<p>
\r<a href="MO_change_attributes.html">memory_object_change_attributes</a> - Modify subset of memory object attributes.<br>
\r<a href="memory_object_destroy.html">memory_object_destroy</a> - Shut down a memory object.<br>
\r<a href="MO_get_attributes.html">memory_object_get_attributes</a> - Return current attributes for a memory object.<br>
\r<a href="memory_object_lock_request.html">memory_object_lock_request</a> - Restrict access to memory object data.<br>
\r<a href="MO_SY_completed.html">memory_object_synchronize_completed</a> - Synchronized data has been processed.<br>
\r</p>
\rData Structures
\r<p>
\r<a href="memory_object_attr_info.html">memory_object_attr_info</a> - Defines memory object attributes.<br>
\r<a href="memory_object_perf_info.html">memory_object_perf_info</a>- Specifies performance-related memory object attributes.<br>
\r</p>
\rExternal Memory Manager Interface Callbacks
\r<p>
\r<a href="memory_object_create.html">memory_object_create</a> - Assign a new memory object to the default memory manager.<br>
\r<a href="MO_data_initialize.html">memory_object_data_initialize</a> - Provide initial data for a new memory object.<br>
\r<a href="memory_object_data_request.html">memory_object_data_request</a> - Request that memory manager page-in specified data.<br>
\r<a href="memory_object_data_return.html">memory_object_data_return</a> - Return memory object data to the appropriate memory manager.<br>
\r<a href="memory_object_data_unlock.html">memory_object_data_unlock</a> - Request a memory manager release the lock on specific data.<br>
\r<a href="memory_object_init.html">memory_object_init</a> - Inform a memory manager on first use of a memory object.<br>
\r<a href="memory_object_synchronize.html">memory_object_synchronize</a> - Request synchronization of data with backing store.<br>
\r<a href="memory_object_terminate.html">memory_object_terminate</a> - Relinquish access to a memory object.<br>
\r</p>
\rEMMI Callback Server Helpers
\r<p>
\r<a href="MO_default_server.html">memory_object_default_server</a> - Handle kernel operation request targeted for the default pager.<br>
\r<a href="memory_object_server.html">memory_object_server</a> - Handle kernel operation request aimed at a given memory manager.<br>
\r</p>
\r</blockquote>
\r\r<h4>Default Memory Management Interface</h4>
\r<blockquote>
\r<p>
\r<a href="default_pager_add_segment.html">default_pager_add_segment</a> - Add additional backing storage for a default pager.<br>
\r<a href="DP_backing_store_create.html">default_pager_backing_store_create</a> - Create a backing storage object.<br>
\r<a href="DP_backing_store_delete.html"> default_pager_backing_store_delete</a> - Delete a backing storage object.<br>
\r<a href="DP_backing_store_info.html">default_pager_backing_store_info</a> - Return information about a backing storage object.<br>
\r<a href="default_pager_info.html">default_pager_info</a> - Furnish caller with information about the default pager.<br>
\r<a href="DP_object_create.html">default_pager_object_create</a> - Initialize a non-persistent memory object.<br>
\r<a href="HD_memory_manager.html">host_default_memory_manager</a> - Register/Lookup the host's default pager.<br>
\r</p>
\r</blockquote>
\r\r</blockquote>
\r\r<h3>Process Management Interface</h3>
\r<blockquote>
\r\r<h4>Task Interface</h4>
\r<blockquote>
\r<p>
\r<a href="mach_ports_lookup.html">mach_ports_lookup</a> - Provide caller with an array of the target task's well-known ports.<br>
\r<a href="mach_ports_register.html">mach_ports_register</a> - Register an array of well-known ports on behalf of the target task.<br>
\r<a href="mach_task_self.html">mach_task_self</a> - Return a send right to the caller's task_self port.<br>
\r<a href="task_create.html">task_create</a> - Create a new task.<br>
\r<a href="task_get_emulation_vector.html">task_get_emulation_vector</a> - Return an array identifying the target task's user-level system call handlers.<br>
\r<a href="task_get_exception_ports.html">task_get_exception_ports</a> - Return send rights to the target task's exception ports.<br>
\r<a href="task_get_special_port.html">task_get_special_port</a> - Return a send write to the indicated special port.<br>
\r<a href="task_info.html">task_info</a> - Return per-task information according to specified flavor.<br>
\r<a href="task_resume.html">task_resume</a> - Decrement the target task's suspend count.<br>
\r<a href="task_sample.html">task_sample</a> - Sample the target task's thread program counters periodically.<br>
\r<a href="task_set_emulation.html">task_set_emulation</a> - Establish a user-level handler for a system call.<br>
\r<a href="task_set_emulation_vector.html">task_set_emulation_vector</a> - Establish the target task's user-level system call handlers.<br>
\r<a href="task_set_exception_ports.html">task_set_exception_ports</a> - Set target task's exception ports.<br>
\r<a href="task_set_info.html">task_set_info</a> - Set task-specific information state.<br>
\r<a href="task_set_port_space.html">task_set_port_space</a> - Set the size of the target task's port name space table.<br>
\r<a href="task_set_special_port.html">task_set_special_port</a> - Set the indicated special port.<br>
\r<a href="task_suspend.html">task_suspend</a> - Suspend the target task.<br>
\r<a href="task_swap_exception_ports.html">task_swap_exception_ports</a> - Set target task's exception ports, returning the previous exception ports.<br>
\r<a href="task_terminate.html">task_terminate</a> - Terminate the target task and deallocate its resources.<br>
\r<a href="task_threads.html">task_threads</a> - Return the target task's list of threads.<br>
\r</p>
\rTask Data Structures
\r<p>
\r<a href="task_basic_info.html">task_basic_info</a> - Defines basic information for a task.<br>
\r<a href="task_thread_times_info.html">task_thread_times_info</a> - Defines thread execution times information for tasks.<br>
\r</p>
\r</blockquote>
\r\r<h4>Thread Interface</h4>
\r<blockquote>
\r<p>
\r<a href="mach_thread_self.html">mach_thread_self</a> - Returns the thread self port.<br>
\r<a href="thread_abort.html">thread_abort</a> - Abort a thread.<br>
\r<a href="thread_abort_safely.html">thread_abort_safely</a> - Abort a thread, restartably.<br>
\r<a href="thread_create.html">thread_create</a> - Create a thread within a task.<br>
\r<a href="thread_create_running.html">thread_create_running</a> - Optimized creation of a running thread.<br>
\r<a href="thread_depress_abort.html">thread_depress_abort</a> - Cancel thread scheduling depression.<br>
\r<a href="thread_get_exception_ports.html">thread_get_exception_ports</a> - Return a send right to an exception port.<br>
\r<a href="thread_get_special_port.html">thread_get_special_port</a> - Return a send right to the caller-specified special port.<br>
\r<a href="thread_get_state.html">thread_get_state</a> - Return the execution state for a thread.<br>
\r<a href="thread_info.html">thread_info</a> - Return information about a thread.<br>
\r<a href="thread_resume.html">thread_resume</a> - Resume a thread.<br>
\r<a href="thread_sample.html">thread_sample</a> - Perform periodic PC sampling for a thread.<br>
\r<a href="thread_set_exception_ports.html">thread_set_exception_ports</a> - Set exception ports for a thread.<br>
\r<a href="thread_set_special_port.html">thread_set_special_port</a> - Set caller-specified special port belonging to the target thread.<br>
\r<a href="thread_set_state.html">thread_set_state</a> - Set the target thread's user-mode execution state.<br>
\r<a href="thread_suspend.html">thread_suspend</a> - Suspend a thread.<br>
\r<a href="TS_exception_ports.html">thread_swap_exception_ports</a> - Swap exception ports for a thread.<br>
\r<a href="thread_terminate.html">thread_terminate</a> - Destroy a thread.<br>
\r<a href="thread_wire.html">thread_wire</a> - Mark the thread as privileged with respect to kernel resources.<br>
\r</p>
\rThread Data Structures
\r<p>
\r<a href="thread_basic_info.html">thread_basic_info</a> - Defines basic information for a thread.<br>
\r</p>
\rThread Exception Callbacks
\r<p>
\r<a href="catch_exception_raise.html">catch_exception_raise</a> - Handles the occurrence of an exception within a thread.<br>
\r</p>
\rThread Exception Callback Server Helpers
\r<p>
\r<a href="exc_server.html">exc_server</a> - Handle kernel-reported thread exception.<br>
\r</p>
\r</blockquote>
\r\r<h4>Scheduling Interface</h4>
\r<blockquote>
\r<p>
\r<a href="task_policy.html">task_policy</a> - Set target task's default scheduling policy state.<br>
\r<a href="task_set_policy.html">task_set_policy</a> - Set target task's default scheduling policy state.<br>
\r<a href="thread_policy.html">thread_policy</a> - Set target thread's scheduling policy state.<br>
\r<a href="thread_set_policy.html">thread_set_policy</a> - Set target thread's scheduling policy state.<br>
\r<a href="thread_switch.html">thread_switch</a> - Cause context switch with options.<br>
\r</p>
\rScheduling Data Structures
\r<p>
\r<a href="policy_fifo_info.html">policy_fifo_info</a> - Specifies information associated with the system's First-In-First-Out scheduling policy.<br>
\r<a href="policy_rr_info.html">policy_rr_info</a> - Specifies information associated with the system's Round Robin scheduling policy.<br>
\r<a href="policy_timeshare_info.html">policy_timeshare_info</a> - Specifies information associated with the system's Timeshare scheduling policy.<br>
\r</p>
\r</blockquote>
\r</blockquote>
\r\r<h3>System Management Interface</h3>
\r<blockquote>
\r\r<h4>Host Interface</h4>
\r<blockquote>
\r<p>
\r<a href="host_get_clock_service.html">host_get_clock_service</a> - Return a send right to a kernel clock's service port.<br>
\r<a href="host_get_time.html">host_get_time</a> - Returns the current time as seen by that host.<br>
\r<a href="host_info.html">host_info</a> - Return information about a host.<br>
\r<a href="host_kernel_version.html">host_kernel_version</a> - Return kernel version information for a host.<br>
\r<a href="host_statistics.html">host_statistics</a> - Return statistics for a host.<br>
\r<a href="mach_host_self.html">mach_host_self</a> - Returns send rights to the task's host self port.<br>
\r</p>
\rData Structures
\r<p>
\r<a href="host_basic_info.html">host_basic_info</a> - Used to present basic information about a host.<br>
\r<a href="host_load_info.html">host_load_info</a> - Used to present a host's processor load information.<br>
\r<a href="host_sched_info.html">host_sched_info</a> - - Used to present the set of scheduler limits associated with the host.<br>
\r<a href="kernel_resource_sizes.html">kernel_resource_sizes</a> - Used to present the sizes of kernel's major structures.<br>
\r</p>
\r</blockquote>
\r\r<h4>Host Control Interface</h4>
\r<blockquote>
\r<p>
\r<a href="host_adjust_time.html">host_adjust_time</a> - Arranges for the time on a specified host to be gradually changed by an adjustment value.<br>
\r<a href="HD_memory_manager.html">host_default_memory_manager</a> - Set the default memory manager.<br>
\r<a href="host_get_boot_info.html">host_get_boot_info</a> - Return operator boot information.<br>
\r<a href="host_get_clock_control.html">host_get_clock_control</a> - Return a send right to a kernel clock's control port.<br>
\r<a href="host_processor_slots.html">host_processor_slots</a> - Return a list of numbers that map processor slots to active processors.<br>
\r<a href="host_processors.html">host_processors</a> - Return a list of send rights representing all processor ports.<br>
\r<a href="host_reboot.html">host_reboot</a> - Reboot this host.<br>
\r<a href="host_set_time.html">host_set_time</a> - Establishes the time on the specified host.<br>
\r</p>
\r</blockquote>
\r\r<h4>Host Security Interface</h4>
\r<blockquote>
\r<p>
\r<a href="host_security_create_task_token.html">host_security_create_task_token</a> - Create a new task with an explicit security token.<br>
\r<a href="host_security_set_task_token.html">host_security_set_task_token</a> - Change the target task's security token.<br>
\r</p>
\r</blockquote>
\r\r<h4>Resource Accounting Interface</h4>
\r<blockquote>
\r<i>
\rThe Mach resource accounting mechanism is not functional in the current Mac OS X/Darwin system. It will become functional in a future release.
\r</i>
\r<p>
\r<a href="ledger_create.html">ledger_create</a> - Create a subordinate ledger.<br>
\r<a href="ledger_read.html">ledger_read</a> - Return the ledger limit and balance.<br>
\r<a href="ledger_terminate.html">ledger_terminate</a> - Destroy a ledger.<br>
\r<a href="ledger_transfer.html">ledger_transfer</a> - Transfer resources from a parent ledger to a child.<br>
\r</p>
\r</blockquote>
\r\r<h4>Processor Management Interface</h4>
\r<blockquote>
\r<p>
\r<a href="processor_control.html">processor_control</a> - Perform caller-specified operation on target processor.<br>
\r<a href="processor_exit.html">processor_exit</a> - Exit a processor.<br>
\r<a href="processor_info.html">processor_info</a> - Return information about a processor.<br>
\r<a href="processor_start.html">processor_start</a> - Start a processor.<br>
\r</p>
\rProcessor Data Structures
\r<p>
\r<a href="processor_basic_info.html">processor_basic_info</a> - Defines the basic information about a processor.<br>
\r</p>
\r</blockquote>
\r\r<h4>Processor Set Interface</h4>
\r<blockquote>
\r<i>
\rThe processor set interface allows for the grouping of tasks and
\rprocessors for the purpose of exclusive scheduling. These interface
\rare <b>deprecated</b> and should not be used in code that isn't tied
\rto a particular release of Mac OS X/Darwin. These will likely change
\ror disappear in a future release.
\r</i>
\r<p>
\r<a href="host_processor_sets.html">host_processor_sets</a> - Return a list of send rights representing all processor set name ports.<br>
\r<a href="host_processor_set_priv.html">host_processor_set_priv</a> - Translate a processor set name port into a processor set control port.<br>
\r<a href="processor_assign.html">processor_assign</a> - Assign a processor to a processor set.<br>
\r<a href="processor_get_assignment.html">processor_get_assignment</a> - Get current assignment for a processor.<br>
\r<a href="processor_set_create.html">processor_set_create</a> - Create a new processor set.<br>
\r<a href="processor_set_default.html">processor_set_default</a> - Return the default processor set.<br>
\r<a href="processor_set_destroy.html">processor_set_destroy</a> - Destroy the target processor set.<br>
\r<a href="processor_set_info.html">processor_set_info</a> - Return processor set state according to caller-specified flavor.<br>
\r<a href="processor_set_max_priority.html">processor_set_max_priority</a> - Sets the maximum scheduling priority for a processor set.<br>
\r<a href="P_set_policy_control.html">processor_set_policy_control</a> - Set target processor set's scheduling policy state.<br>
\r<a href="P_set_policy_disable.html">processor_set_policy_disable</a> - Enables a scheduling policy for a processor set.<br>
\r<a href="P_set_policy_enable.html">processor_set_policy_enable</a> - Enables a scheduling policy for a processor set.<br>
\r<a href="processor_set_statistics.html">processor_set_statistics</a> - Return scheduling statistics for a processor set.<br>
\r<a href="processor_set_tasks.html">processor_set_tasks</a> - Return all tasks currently assigned to the target processor set.<br>
\r<a href="processor_set_threads.html">processor_set_threads</a> - Return all threads currently assigned to the target processor set.<br>
\r<a href="task_assign.html">task_assign</a> - Assign a task to a processor set.<br>
\r<a href="task_assign_default.html">task_assign_default</a> - Assign a task to the default processor set.<br>
\r<a href="task_get_assignment.html">task_get_assignment</a> - Create a new task with an explicit security token.<br>
\r<a href="thread_assign.html">thread_assign</a> - Assign a thread to a processor set.<br>
\r<a href="thread_assign_default.html">thread_assign_default</a> - Assign a thread to the default processor set.<br>
\r<a href="thread_get_assignment.html">thread_get_assignment</a> - Return the processor set to which a thread is assigned.<br>
\r</p>
\rProcessor Set Data Structures
\r<p>
\r<a href="processor_set_basic_info.html">processor_set_basic_info</a> - Defines the basic information about a processor set.<br>
\r<a href="processor_set_load_info.html">processor_set_load_info</a> - Defines the scheduling statistics for a processor set.<br>
\r</p>
\r</blockquote>
\r\r<h4>Clock Interface</h4>
\r<blockquote>
\r<p>
\r<a href="clock_alarm.html">clock_alarm</a> - Set up an alarm.<br>
\r<a href="clock_get_attributes.html">clock_get_attributes</a> - Return attributes of a clock.<br>
\r<a href="clock_get_time.html">clock_get_time</a> - Return the current time.<br>
\r<a href="clock_map_time.html">clock_map_time</a> - Return a memory object that maps a clock.<br>
\r<a href="clock_set_attributes.html">clock_set_attributes</a> - Set a particular clock's attributes.<br>
\r<a href="clock_set_time.html">clock_set_time</a> - Set the current time.<br>
\r<a href="clock_sleep.html">clock_sleep</a> - Delay the invoking thread until a specified time.<br>
\r</p>
\rClock Data Structures
\r<p>
\r<a href="mapped_tvalspec.html">mapped_tvalspec</a> - Specifies the format the kernel uses to maintain a mapped clock's time.<br>
\r<a href="tvalspec.html">tvalspec</a> - Defines format of system time values.<br>
\r</p>
\rClock Interface Callbacks
\r<p>
\r<a href="clock_alarm_reply.html">clock_alarm_reply</a> - Ring a preset alarm.<br>
\r</p>
\rClock Callback Server Helpers
\r<p>
\r<a href="clock_reply_server.html"> clock_reply_server</a> - Handle kernel-generated alarm.<br>
\r</p>
\r</blockquote>
\r\r<h4>Multi-Computer Support Interface</h4>
\r<blockquote>
\r<i>
\rThese multi-computer support interfaces are no longer supported by
\rthe Mac OS X/Darwin kernel. If and when multi-computer support is
\radded back in, something like these will likely be added.
\r</i>
\r<p>
\r<a href="host_page_size.html">host_page_size</a> - Returns the page size for the given host.<br>
\r<a href="ledger_get_remote.html">ledger_get_remote</a> - Return send right to specified host's remote ledger port.<br>
\r<a href="ledger_set_remote.html">ledger_set_remote</a> - Set this host's remote ledger port.<br>
\r<a href="norma_get_special_port.html">norma_get_special_port</a> - Returns a send right for a specified node-specific special port.<br>
\r<a href="norma_node_self.html">norma_node_self</a> - Return the node index of the current host.<br>
\r<a href="norma_port_location_hint.html">norma_port_location_hint</a> - Guess a port's current location.<br>
\r<a href="norma_set_special_port.html">norma_set_special_port</a> - Set node-specific special port.<br>
\r<a href="norma_task_clone.html">norma_task_clone</a> - Create a remote task that shares access to parent task's memory.<br>
\r<a href="norma_task_create.html">norma_task_create</a> - Create a remote task using task_create semantics.<br>
\r<a href="norma_task_teleport.html">norma_task_teleport</a> - "Clone" a task on a specified node.<br>
\r</p>
\r</blockquote>
\r\r</blockquote>
\r\r<h3>Machine Specific Interface</h3>
\r<blockquote>
\r\r<h4>Intel 386 Support</h4>
\r<blockquote>
\r<p>
\r<a href="i386_get_ldt.html">i386_get_ldt</a> - Returns per-thread segment descriptors from the local descriptor table (LDT).<br>
\r<a href="i386_io_port_add.html">i386_io_port_add</a> - Adds a device to the I/O permission bitmap for a thread. <br>
\r<a href="i386_io_port_list.html">i386_io_port_list</a> - Returns a list of the devices named in the thread's I/O permission bitmap.<br>
\r<a href="i386_io_port_remove.html">i386_io_port_remove</a> - Removes the specified device from the thread's I/O permission bitmap.<br>
\r<a href="i386_set_ldt.html">i386_set_ldt</a> - Allows a thread to have a private local descriptor table (LDT).<br>
\r</p>
\r</blockquote>
\r\r<h4>PowerPC Support</h4>
\r<blockquote>
\r<p>
\r</p>
\r</blockquote>
\r\r</blockquote>
\r\r</BODY>
\r\r</HTML>
\r\r\ No newline at end of file
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+ <title>Mach Kernel Interface Reference Manual</title>
+</head>
+<body>
+<h3>Mach IPC Interface</h3>
+<blockquote>
+<p>
+Mach IPC presents itself in a few forms: message queues, lock-sets,
+and semaphores (more may be added in the future). All share one common
+charateristic: the capabilities presented by each are represented through
+a handle known as a Mach port. Specific rights represented in these
+Mach port capability handles allow the underlying IPC object to be used and
+manipulated in consistent ways.</p>
+
+<h4>Mach Message Queue Interface</h4>
+<blockquote>
+<p>
+<a href="mach_msg.html">mach_msg</a> - Send and/or receive a message from the target port.<br>
+<a href="mach_msg.html">mach_msg_overwrite</a> - Send and/or receive messages with possible overwrite.<br>
+</p>
+Mach Message Queue Data Structures
+<p>
+<a href="mach_msg_descriptor.html">mach_msg_descriptor</a> - Specifies an element of a complex IPC message.<br>
+<a href="mach_msg_header.html">mach_msg_header</a> - Specifies the content of an IPC message header.<br>
+</p>
+</blockquote>
+
+<h4>Mach Lock-Set Interface</h4>
+<blockquote>
+<p>
+<a href="lock_acquire.html">lock_acquire</a> - Acquire ownership a lock<br>
+<a href="lock_handoff.html">lock_handoff</a> - Hand-off ownership of a lock.<br>
+<a href="lock_handoff_accept.html">lock_handoff_accept</a> - Accept lock ownership from a handoff.<br>
+<a href="lock_make_stable.html">lock_make_stable</a> - Stabilize the state of the specified lock.<br>
+<a href="lock_release.html">lock_release</a> - Release ownership of a lock.<br>
+<a href="lock_set_create.html">lock_set_create</a> - Create a new lock set.<br>
+<a href="lock_set_destroy.html">lock_set_destroy</a> - Destroy a lock set and its associated locks.<br>
+<a href="lock_try.html">lock_try</a> - Attempt to acquire access rights to a lock.<br>
+</p>
+</blockquote>
+
+<h4>Mach Semaphore Interface</h4>
+<blockquote>
+<p>
+<a href="semaphore_create.html">semaphore_create</a> - Create a new semaphore.<br>
+<a href="semaphore_destroy.html">semaphore_destroy</a> - Destroy a semaphore.<br>
+<a href="semaphore_signal.html">semaphore_signal</a> - Increments the semaphore count.<br>
+<a href="semaphore_signal_all.html">semaphore_signal_all</a> - Wake up all threads blocked on a semaphore.<br>
+<a href="semaphore_wait.html">semaphore_wait</a> - Wait on the specified semaphore.<br>
+</p>
+</blockquote>
+
+<h4>Mach Port Management Interface</h4>
+<blockquote>
+<p>
+<a href="mach_port_allocate.html">mach_port_allocate</a> - Create caller-specified type of port right.<br>
+<a href="mach_port_allocate_full.html">mach_port_allocate_full</a> - Create a port right with full Mach port semantics.<br>
+<a href="mach_port_allocate_name.html">mach_port_allocate_name</a> - Create a port right with the caller-specified name.<br>
+<a href="mach_port_allocate_qos.html">mach_port_allocate_qos</a> - Allocate a port with specified "quality of service".<br>
+<a href="MP_allocate_subsystem.html">mach_port_allocate_subsystem</a> - Create a port right associated with the caller-specified subsystem.<br>
+<a href="mach_port_deallocate.html">mach_port_deallocate</a> - Decrement the target port right's user reference count.<br>
+<a href="mach_port_destroy.html">mach_port_destroy</a> - Deallocate all port rights associated with specified name.<br>
+<a href="mach_port_extract_right.html">mach_port_extract_right</a> - Remove the specified right from the target task and return it to the caller.<br>
+<a href="mach_port_get_attributes.html">mach_port_get_attributes</a> - Return information about target port as specified by the caller.<br>
+<a href="mach_port_get_refs.html">mach_port_get_refs</a> - Return the current count of user references on the target port right.<br>
+<a href="mach_port_get_set_status.html">mach_port_get_set_status</a> - Return the port right names contained in the target port set.<br>
+<a href="mach_port_insert_right.html">mach_port_insert_right</a> - Insert the specified port right into the target task.<br>
+<a href="mach_port_mod_refs.html">mach_port_mod_refs</a> - Modify the specified port right's count of user references.<br>
+<a href="mach_port_move_member.html">mach_port_move_member</a> - Move the specified receive right into or out of the specified port set.<br>
+<a href="mach_port_names.html">mach_port_names</a> - Return information about a task's port name space.<br>
+<a href="MP_request_notification.html">mach_port_request_notification</a> - Request notification of the specified port event type.<br>
+<a href="mach_port_set_attributes.html">mach_port_set_attributes</a> - Set the target port's attributes.<br>
+<a href="mach_port_set_mscount.html">mach_port_set_mscount</a> - Change the target port's make-send count.<br>
+<a href="mach_port_set_seqno.html">mach_port_set_seqno</a> - Change the current value of the target port's sequence number.<br>
+<a href="mach_port_type.html">mach_port_type</a> - Return the characteristics of the target port name.<br>
+<a href="mach_reply_port.html">mach_reply_port</a> - Allocate a new port and insert corresponding receive right in the calling task.<br>
+<a href="mach_subsystem_create.html"> mach_subsystem_create</a> - Used by a server to register information about an RPC subsystem with the kernel.<br>
+</p>
+Mach Port Data Structures
+<p>
+<a href="mach_port_limits.html">mach_port_limits</a> - Specifies a port's resource and message queue limits.<br>
+<a href="mach_port_qos.html">mach_port_qos</a> - Specifies a port's attributes with respect to "Quality Of Service."<br>
+<a href="mach_port_status.html">mach_port_status</a> - Used to present a port's current status with respect to various important attributes.<br>
+</p>
+Mach Port Notification Callbacks
+<p>
+<a href="do_mach_notify_dead_name.html">do_mach_notify_dead_name</a> - Handle the current instance of a dead-name notification.<br>
+<a href="do_mach_notify_no_senders.html">do_mach_notify_no_senders</a> - Handle the current instance of a no-more-senders notification.<br>
+<a href="DMN_port_deleted.html">do_mach_notify_port_deleted</a> - Handle the current instance of a port-deleted notification.<br>
+<a href="DMN_port_destroyed.html">do_mach_notify_port_destroyed</a> - Handle the current instance of a port-destroyed notification.<br>
+<a href="do_mach_notify_send_once.html">do_mach_notify_send_once</a> - Handle the current instance of a send-once notification.<br>
+</p>
+Mach Port Notification Callback Server Helpers
+<p>
+<a href="notify_server.html">notify_server</a> - Detect and handle a kernel-generated IPC notification.<br>
+</p>
+</blockquote>
+
+</blockquote>
+
+<h3>Mach Virtual Memory Interface</h3>
+<blockquote>
+<h4>Mach Virtual Memory Address Space Manipulation Interface</h4>
+<blockquote>
+<p>
+<a href="host_page_size.html">host_page_size</a> - Provide the system's virtual page size.<br>
+<a href="vm_allocate.html">vm_allocate</a> - Allocate a region of virtual memory.<br>
+<a href="vm_behavior_set.html">vm_behavior_set</a> - Specify expected access patterns for the target VM region.<br>
+<a href="vm_copy.html">vm_copy</a> - Copy a region of virtual memory.<br>
+<a href="vm_deallocate.html">vm_deallocate</a> - Deallocate a region of virtual memory.<br>
+<a href="vm_inherit.html">vm_inherit</a> - Set a VM region's inheritance attribute.<br>
+<a href="vm_machine_attribute.html">vm_machine_attribute</a> - Get/set the target memory region's special attributes.<br>
+<a href="vm_map.html">vm_map</a> - Map the specified memory object to a region of virtual memory.<br>
+<a href="vm_msync.html">vm_msync</a> - Synchronize the specified region of virtual memory.<br>
+<a href="vm_protect.html">vm_protect</a> - Set access privilege attribute for a region of virtual memory.<br>
+<a href="vm_read.html">vm_read</a> - Read the specified range of target task's address space.<br>
+<a href="vm_region.html">vm_region</a> - Return description of a virtual memory region.<br>
+<a href="vm_remap.html">vm_remap</a> - Map memory objects in one address space to that of another's.<br>
+<a href="vm_wire.html"> vm_wire</a> - Modify the target region's paging characteristics.<br>
+<a href="vm_write.html">vm_write</a> - Write data to the specified address in the target address space.<br>
+</p>
+Data Structures
+<p>
+<a href="vm_region_basic_info.html">vm_region_basic_info</a> - Defines the attributes of a task's memory region.<br>
+<a href="vm_statistics.html">vm_statistics</a> - Defines statistics for the kernel's use of virtual memory.<br>
+</p>
+</blockquote>
+
+<h4>External Memory Management Interface</h4>
+<blockquote>
+The External Memory Management Interface (EMMI) is undergoing significant change in the Darwin system.
+For this reason, the interface is not currently available to user-level programs. Even for kernel
+extensions, use of these interfaces in not supported. Instead, the BSD filesystem's Universal Buffer Cache (UBC)
+mechanism should be used.<br>
+<p>
+<a href="MO_change_attributes.html">memory_object_change_attributes</a> - Modify subset of memory object attributes.<br>
+<a href="memory_object_destroy.html">memory_object_destroy</a> - Shut down a memory object.<br>
+<a href="MO_get_attributes.html">memory_object_get_attributes</a> - Return current attributes for a memory object.<br>
+<a href="memory_object_lock_request.html">memory_object_lock_request</a> - Restrict access to memory object data.<br>
+<a href="MO_SY_completed.html">memory_object_synchronize_completed</a> - Synchronized data has been processed.<br>
+</p>
+Data Structures
+<p>
+<a href="memory_object_attr_info.html">memory_object_attr_info</a> - Defines memory object attributes.<br>
+<a href="memory_object_perf_info.html">memory_object_perf_info</a>- Specifies performance-related memory object attributes.<br>
+</p>
+External Memory Manager Interface Callbacks
+<p>
+<a href="memory_object_create.html">memory_object_create</a> - Assign a new memory object to the default memory manager.<br>
+<a href="MO_data_initialize.html">memory_object_data_initialize</a> - Provide initial data for a new memory object.<br>
+<a href="memory_object_data_request.html">memory_object_data_request</a> - Request that memory manager page-in specified data.<br>
+<a href="memory_object_data_return.html">memory_object_data_return</a> - Return memory object data to the appropriate memory manager.<br>
+<a href="memory_object_data_unlock.html">memory_object_data_unlock</a> - Request a memory manager release the lock on specific data.<br>
+<a href="memory_object_init.html">memory_object_init</a> - Inform a memory manager on first use of a memory object.<br>
+<a href="memory_object_synchronize.html">memory_object_synchronize</a> - Request synchronization of data with backing store.<br>
+<a href="memory_object_terminate.html">memory_object_terminate</a> - Relinquish access to a memory object.<br>
+</p>
+EMMI Callback Server Helpers
+<p>
+<a href="MO_default_server.html">memory_object_default_server</a> - Handle kernel operation request targeted for the default pager.<br>
+<a href="memory_object_server.html">memory_object_server</a> - Handle kernel operation request aimed at a given memory manager.<br>
+</p>
+</blockquote>
+
+<h4>Default Memory Management Interface</h4>
+<blockquote>
+<p>
+<a href="default_pager_add_segment.html">default_pager_add_segment</a> - Add additional backing storage for a default pager.<br>
+<a href="DP_backing_store_create.html">default_pager_backing_store_create</a> - Create a backing storage object.<br>
+<a href="DP_backing_store_delete.html"> default_pager_backing_store_delete</a> - Delete a backing storage object.<br>
+<a href="DP_backing_store_info.html">default_pager_backing_store_info</a> - Return information about a backing storage object.<br>
+<a href="default_pager_info.html">default_pager_info</a> - Furnish caller with information about the default pager.<br>
+<a href="DP_object_create.html">default_pager_object_create</a> - Initialize a non-persistent memory object.<br>
+<a href="HD_memory_manager.html">host_default_memory_manager</a> - Register/Lookup the host's default pager.<br>
+</p>
+</blockquote>
+
+</blockquote>
+
+<h3>Process Management Interface</h3>
+<blockquote>
+
+<h4>Task Interface</h4>
+<blockquote>
+<p>
+<a href="mach_ports_lookup.html">mach_ports_lookup</a> - Provide caller with an array of the target task's well-known ports.<br>
+<a href="mach_ports_register.html">mach_ports_register</a> - Register an array of well-known ports on behalf of the target task.<br>
+<a href="mach_task_self.html">mach_task_self</a> - Return a send right to the caller's task_self port.<br>
+<a href="task_create.html">task_create</a> - Create a new task.<br>
+<a href="task_get_emulation_vector.html">task_get_emulation_vector</a> - Return an array identifying the target task's user-level system call handlers.<br>
+<a href="task_get_exception_ports.html">task_get_exception_ports</a> - Return send rights to the target task's exception ports.<br>
+<a href="task_get_special_port.html">task_get_special_port</a> - Return a send write to the indicated special port.<br>
+<a href="task_info.html">task_info</a> - Return per-task information according to specified flavor.<br>
+<a href="task_resume.html">task_resume</a> - Decrement the target task's suspend count.<br>
+<a href="task_sample.html">task_sample</a> - Sample the target task's thread program counters periodically.<br>
+<a href="task_set_emulation.html">task_set_emulation</a> - Establish a user-level handler for a system call.<br>
+<a href="task_set_emulation_vector.html">task_set_emulation_vector</a> - Establish the target task's user-level system call handlers.<br>
+<a href="task_set_exception_ports.html">task_set_exception_ports</a> - Set target task's exception ports.<br>
+<a href="task_set_info.html">task_set_info</a> - Set task-specific information state.<br>
+<a href="task_set_port_space.html">task_set_port_space</a> - Set the size of the target task's port name space table.<br>
+<a href="task_set_special_port.html">task_set_special_port</a> - Set the indicated special port.<br>
+<a href="task_suspend.html">task_suspend</a> - Suspend the target task.<br>
+<a href="task_swap_exception_ports.html">task_swap_exception_ports</a> - Set target task's exception ports, returning the previous exception ports.<br>
+<a href="task_terminate.html">task_terminate</a> - Terminate the target task and deallocate its resources.<br>
+<a href="task_threads.html">task_threads</a> - Return the target task's list of threads.<br>
+</p>
+Task Data Structures
+<p>
+<a href="task_basic_info.html">task_basic_info</a> - Defines basic information for a task.<br>
+<a href="task_thread_times_info.html">task_thread_times_info</a> - Defines thread execution times information for tasks.<br>
+</p>
+</blockquote>
+
+<h4>Thread Interface</h4>
+<blockquote>
+<p>
+<a href="mach_thread_self.html">mach_thread_self</a> - Returns the thread self port.<br>
+<a href="thread_abort.html">thread_abort</a> - Abort a thread.<br>
+<a href="thread_abort_safely.html">thread_abort_safely</a> - Abort a thread, restartably.<br>
+<a href="thread_create.html">thread_create</a> - Create a thread within a task.<br>
+<a href="thread_create_running.html">thread_create_running</a> - Optimized creation of a running thread.<br>
+<a href="thread_depress_abort.html">thread_depress_abort</a> - Cancel thread scheduling depression.<br>
+<a href="thread_get_exception_ports.html">thread_get_exception_ports</a> - Return a send right to an exception port.<br>
+<a href="thread_get_special_port.html">thread_get_special_port</a> - Return a send right to the caller-specified special port.<br>
+<a href="thread_get_state.html">thread_get_state</a> - Return the execution state for a thread.<br>
+<a href="thread_info.html">thread_info</a> - Return information about a thread.<br>
+<a href="thread_resume.html">thread_resume</a> - Resume a thread.<br>
+<a href="thread_sample.html">thread_sample</a> - Perform periodic PC sampling for a thread.<br>
+<a href="thread_set_exception_ports.html">thread_set_exception_ports</a> - Set exception ports for a thread.<br>
+<a href="thread_set_special_port.html">thread_set_special_port</a> - Set caller-specified special port belonging to the target thread.<br>
+<a href="thread_set_state.html">thread_set_state</a> - Set the target thread's user-mode execution state.<br>
+<a href="thread_suspend.html">thread_suspend</a> - Suspend a thread.<br>
+<a href="TS_exception_ports.html">thread_swap_exception_ports</a> - Swap exception ports for a thread.<br>
+<a href="thread_terminate.html">thread_terminate</a> - Destroy a thread.<br>
+<a href="thread_wire.html">thread_wire</a> - Mark the thread as privileged with respect to kernel resources.<br>
+</p>
+Thread Data Structures
+<p>
+<a href="thread_basic_info.html">thread_basic_info</a> - Defines basic information for a thread.<br>
+</p>
+Thread Exception Callbacks
+<p>
+<a href="catch_exception_raise.html">catch_exception_raise</a> - Handles the occurrence of an exception within a thread.<br>
+</p>
+Thread Exception Callback Server Helpers
+<p>
+<a href="exc_server.html">exc_server</a> - Handle kernel-reported thread exception.<br>
+</p>
+</blockquote>
+
+<h4>Scheduling Interface</h4>
+<blockquote>
+<p>
+<a href="task_policy.html">task_policy</a> - Set target task's default scheduling policy state.<br>
+<a href="task_set_policy.html">task_set_policy</a> - Set target task's default scheduling policy state.<br>
+<a href="thread_policy.html">thread_policy</a> - Set target thread's scheduling policy state.<br>
+<a href="thread_set_policy.html">thread_set_policy</a> - Set target thread's scheduling policy state.<br>
+<a href="thread_switch.html">thread_switch</a> - Cause context switch with options.<br>
+</p>
+Scheduling Data Structures
+<p>
+<a href="policy_fifo_info.html">policy_fifo_info</a> - Specifies information associated with the system's First-In-First-Out scheduling policy.<br>
+<a href="policy_rr_info.html">policy_rr_info</a> - Specifies information associated with the system's Round Robin scheduling policy.<br>
+<a href="policy_timeshare_info.html">policy_timeshare_info</a> - Specifies information associated with the system's Timeshare scheduling policy.<br>
+</p>
+</blockquote>
+</blockquote>
+
+<h3>System Management Interface</h3>
+<blockquote>
+
+<h4>Host Interface</h4>
+<blockquote>
+<p>
+<a href="host_get_clock_service.html">host_get_clock_service</a> - Return a send right to a kernel clock's service port.<br>
+<a href="host_get_time.html">host_get_time</a> - Returns the current time as seen by that host.<br>
+<a href="host_info.html">host_info</a> - Return information about a host.<br>
+<a href="host_kernel_version.html">host_kernel_version</a> - Return kernel version information for a host.<br>
+<a href="host_statistics.html">host_statistics</a> - Return statistics for a host.<br>
+<a href="mach_host_self.html">mach_host_self</a> - Returns send rights to the task's host self port.<br>
+</p>
+Data Structures
+<p>
+<a href="host_basic_info.html">host_basic_info</a> - Used to present basic information about a host.<br>
+<a href="host_load_info.html">host_load_info</a> - Used to present a host's processor load information.<br>
+<a href="host_sched_info.html">host_sched_info</a> - - Used to present the set of scheduler limits associated with the host.<br>
+<a href="kernel_resource_sizes.html">kernel_resource_sizes</a> - Used to present the sizes of kernel's major structures.<br>
+</p>
+</blockquote>
+
+<h4>Host Control Interface</h4>
+<blockquote>
+<p>
+<a href="host_adjust_time.html">host_adjust_time</a> - Arranges for the time on a specified host to be gradually changed by an adjustment value.<br>
+<a href="HD_memory_manager.html">host_default_memory_manager</a> - Set the default memory manager.<br>
+<a href="host_get_boot_info.html">host_get_boot_info</a> - Return operator boot information.<br>
+<a href="host_get_clock_control.html">host_get_clock_control</a> - Return a send right to a kernel clock's control port.<br>
+<a href="host_processor_slots.html">host_processor_slots</a> - Return a list of numbers that map processor slots to active processors.<br>
+<a href="host_processors.html">host_processors</a> - Return a list of send rights representing all processor ports.<br>
+<a href="host_reboot.html">host_reboot</a> - Reboot this host.<br>
+<a href="host_set_time.html">host_set_time</a> - Establishes the time on the specified host.<br>
+</p>
+</blockquote>
+
+<h4>Host Security Interface</h4>
+<blockquote>
+<p>
+<a href="host_security_create_task_token.html">host_security_create_task_token</a> - Create a new task with an explicit security token.<br>
+<a href="host_security_set_task_token.html">host_security_set_task_token</a> - Change the target task's security token.<br>
+</p>
+</blockquote>
+
+<h4>Resource Accounting Interface</h4>
+<blockquote>
+<i>
+The Mach resource accounting mechanism is not functional in the current Mac OS X/Darwin system. It will become functional in a future release.
+</i>
+<p>
+<a href="ledger_create.html">ledger_create</a> - Create a subordinate ledger.<br>
+<a href="ledger_read.html">ledger_read</a> - Return the ledger limit and balance.<br>
+<a href="ledger_terminate.html">ledger_terminate</a> - Destroy a ledger.<br>
+<a href="ledger_transfer.html">ledger_transfer</a> - Transfer resources from a parent ledger to a child.<br>
+</p>
+</blockquote>
+
+<h4>Processor Management Interface</h4>
+<blockquote>
+<p>
+<a href="processor_control.html">processor_control</a> - Perform caller-specified operation on target processor.<br>
+<a href="processor_exit.html">processor_exit</a> - Exit a processor.<br>
+<a href="processor_info.html">processor_info</a> - Return information about a processor.<br>
+<a href="processor_start.html">processor_start</a> - Start a processor.<br>
+</p>
+Processor Data Structures
+<p>
+<a href="processor_basic_info.html">processor_basic_info</a> - Defines the basic information about a processor.<br>
+</p>
+</blockquote>
+
+<h4>Processor Set Interface</h4>
+<blockquote>
+<i>
+The processor set interface allows for the grouping of tasks and
+processors for the purpose of exclusive scheduling. These interface
+are <b>deprecated</b> and should not be used in code that isn't tied
+to a particular release of Mac OS X/Darwin. These will likely change
+or disappear in a future release.
+</i>
+<p>
+<a href="host_processor_sets.html">host_processor_sets</a> - Return a list of send rights representing all processor set name ports.<br>
+<a href="host_processor_set_priv.html">host_processor_set_priv</a> - Translate a processor set name port into a processor set control port.<br>
+<a href="processor_assign.html">processor_assign</a> - Assign a processor to a processor set.<br>
+<a href="processor_get_assignment.html">processor_get_assignment</a> - Get current assignment for a processor.<br>
+<a href="processor_set_create.html">processor_set_create</a> - Create a new processor set.<br>
+<a href="processor_set_default.html">processor_set_default</a> - Return the default processor set.<br>
+<a href="processor_set_destroy.html">processor_set_destroy</a> - Destroy the target processor set.<br>
+<a href="processor_set_info.html">processor_set_info</a> - Return processor set state according to caller-specified flavor.<br>
+<a href="processor_set_max_priority.html">processor_set_max_priority</a> - Sets the maximum scheduling priority for a processor set.<br>
+<a href="P_set_policy_control.html">processor_set_policy_control</a> - Set target processor set's scheduling policy state.<br>
+<a href="P_set_policy_disable.html">processor_set_policy_disable</a> - Enables a scheduling policy for a processor set.<br>
+<a href="P_set_policy_enable.html">processor_set_policy_enable</a> - Enables a scheduling policy for a processor set.<br>
+<a href="processor_set_statistics.html">processor_set_statistics</a> - Return scheduling statistics for a processor set.<br>
+<a href="processor_set_tasks.html">processor_set_tasks</a> - Return all tasks currently assigned to the target processor set.<br>
+<a href="processor_set_threads.html">processor_set_threads</a> - Return all threads currently assigned to the target processor set.<br>
+<a href="task_assign.html">task_assign</a> - Assign a task to a processor set.<br>
+<a href="task_assign_default.html">task_assign_default</a> - Assign a task to the default processor set.<br>
+<a href="task_get_assignment.html">task_get_assignment</a> - Create a new task with an explicit security token.<br>
+<a href="thread_assign.html">thread_assign</a> - Assign a thread to a processor set.<br>
+<a href="thread_assign_default.html">thread_assign_default</a> - Assign a thread to the default processor set.<br>
+<a href="thread_get_assignment.html">thread_get_assignment</a> - Return the processor set to which a thread is assigned.<br>
+</p>
+Processor Set Data Structures
+<p>
+<a href="processor_set_basic_info.html">processor_set_basic_info</a> - Defines the basic information about a processor set.<br>
+<a href="processor_set_load_info.html">processor_set_load_info</a> - Defines the scheduling statistics for a processor set.<br>
+</p>
+</blockquote>
+
+<h4>Clock Interface</h4>
+<blockquote>
+<p>
+<a href="clock_alarm.html">clock_alarm</a> - Set up an alarm.<br>
+<a href="clock_get_attributes.html">clock_get_attributes</a> - Return attributes of a clock.<br>
+<a href="clock_get_time.html">clock_get_time</a> - Return the current time.<br>
+<a href="clock_map_time.html">clock_map_time</a> - Return a memory object that maps a clock.<br>
+<a href="clock_set_attributes.html">clock_set_attributes</a> - Set a particular clock's attributes.<br>
+<a href="clock_set_time.html">clock_set_time</a> - Set the current time.<br>
+<a href="clock_sleep.html">clock_sleep</a> - Delay the invoking thread until a specified time.<br>
+</p>
+Clock Data Structures
+<p>
+<a href="mapped_tvalspec.html">mapped_tvalspec</a> - Specifies the format the kernel uses to maintain a mapped clock's time.<br>
+<a href="tvalspec.html">tvalspec</a> - Defines format of system time values.<br>
+</p>
+Clock Interface Callbacks
+<p>
+<a href="clock_alarm_reply.html">clock_alarm_reply</a> - Ring a preset alarm.<br>
+</p>
+Clock Callback Server Helpers
+<p>
+<a href="clock_reply_server.html"> clock_reply_server</a> - Handle kernel-generated alarm.<br>
+</p>
+</blockquote>
+
+<h4>Multi-Computer Support Interface</h4>
+<blockquote>
+<i>
+These multi-computer support interfaces are no longer supported by
+the Mac OS X/Darwin kernel. If and when multi-computer support is
+added back in, something like these will likely be added.
+</i>
+<p>
+<a href="host_page_size.html">host_page_size</a> - Returns the page size for the given host.<br>
+<a href="ledger_get_remote.html">ledger_get_remote</a> - Return send right to specified host's remote ledger port.<br>
+<a href="ledger_set_remote.html">ledger_set_remote</a> - Set this host's remote ledger port.<br>
+<a href="norma_get_special_port.html">norma_get_special_port</a> - Returns a send right for a specified node-specific special port.<br>
+<a href="norma_node_self.html">norma_node_self</a> - Return the node index of the current host.<br>
+<a href="norma_port_location_hint.html">norma_port_location_hint</a> - Guess a port's current location.<br>
+<a href="norma_set_special_port.html">norma_set_special_port</a> - Set node-specific special port.<br>
+<a href="norma_task_clone.html">norma_task_clone</a> - Create a remote task that shares access to parent task's memory.<br>
+<a href="norma_task_create.html">norma_task_create</a> - Create a remote task using task_create semantics.<br>
+<a href="norma_task_teleport.html">norma_task_teleport</a> - "Clone" a task on a specified node.<br>
+</p>
+</blockquote>
+
+</blockquote>
+
+<h3>Machine Specific Interface</h3>
+<blockquote>
+
+<h4>Intel 386 Support</h4>
+<blockquote>
+<p>
+<a href="i386_get_ldt.html">i386_get_ldt</a> - Returns per-thread segment descriptors from the local descriptor table (LDT).<br>
+<a href="i386_io_port_add.html">i386_io_port_add</a> - Adds a device to the I/O permission bitmap for a thread. <br>
+<a href="i386_io_port_list.html">i386_io_port_list</a> - Returns a list of the devices named in the thread's I/O permission bitmap.<br>
+<a href="i386_io_port_remove.html">i386_io_port_remove</a> - Removes the specified device from the thread's I/O permission bitmap.<br>
+<a href="i386_set_ldt.html">i386_set_ldt</a> - Allows a thread to have a private local descriptor table (LDT).<br>
+</p>
+</blockquote>
+
+<h4>PowerPC Support</h4>
+<blockquote>
+<p>
+</p>
+</blockquote>
+
+</blockquote>
+
+</BODY>
+
+</HTML>
+
-<h2>io_done_queue_create</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Create an <strong>io_done_queue</strong> kernel object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t io_done_queue_create</strong>
\r <strong>(mach_port_t</strong> <var>host</var>,
\r <strong>mach_port_t</strong> <var>queue</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host</var>
\r<dd>
\r[in host-name send right] The name (or control) port for the host on
\rwhich the io_done_queue should be created.
\r<p>
\r<dt> <var>queue</var>
\r<dd>
\r[out io-done-queue send right] The port referencing the created
\rio_done_queue.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe io_done_queue_create function is called to create a new
\rinstatiation of the kernel object supporting asynchronous read/write
\roperations on a device.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\r Invalid <var>host</var> parameter.
\r <p>
\r <dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
\r<dd>
\r Insufficient kernel resources to allocate kernel object.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="io_done_queue_terminate.html"><strong>io_done_queue_terminate</strong></a>,
\r<a href="io_done_queue_wait.html"><strong>io_done_queue_wait</strong></a>,
\r<a href="device_read_async.html"><strong>device_read_async</strong></a>,
\r<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>,
\r<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>,
\r<a href="device_write_async.html"><strong>device_write_async</strong></a>,
\r<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>.
\r\ No newline at end of file
+<h2>io_done_queue_create</h2>
+<hr>
+<p>
+<strong>Function</strong> - Create an <strong>io_done_queue</strong> kernel object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t io_done_queue_create</strong>
+ <strong>(mach_port_t</strong> <var>host</var>,
+ <strong>mach_port_t</strong> <var>queue</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host</var>
+<dd>
+[in host-name send right] The name (or control) port for the host on
+which the io_done_queue should be created.
+<p>
+<dt> <var>queue</var>
+<dd>
+[out io-done-queue send right] The port referencing the created
+io_done_queue.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The io_done_queue_create function is called to create a new
+instatiation of the kernel object supporting asynchronous read/write
+operations on a device.
+<h3>RETURN VALUES</h3>
+<dl>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+ Invalid <var>host</var> parameter.
+ <p>
+ <dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
+<dd>
+ Insufficient kernel resources to allocate kernel object.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="io_done_queue_terminate.html"><strong>io_done_queue_terminate</strong></a>,
+<a href="io_done_queue_wait.html"><strong>io_done_queue_wait</strong></a>,
+<a href="device_read_async.html"><strong>device_read_async</strong></a>,
+<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>,
+<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>,
+<a href="device_write_async.html"><strong>device_write_async</strong></a>,
+<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>.
-<h2>io_done_queue_terminate</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Terminate an io_done_queue kernel object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<device/device.h></strong>
\r\r<strong>kern_return_t io_done_queue_terminate</strong>
\r <strong>(mach_port_t</strong> <var>queue</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>queue</var>
\r<dd>
\r[in io-done-queue send right] The port referencing the <strong>io_done_queue</strong>
\rto be destroyed.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>io_done_queue_terminate</strong> function is called to destroy a previous
\rinstatiation of the kernel object supporting asynchronous read/write
\roperations on a device.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r <dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\r Invalid <var>queue</var> parameter.
\r <p>
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>,
\r<a href="io_done_queue_wait.html"><strong>io_done_queue_wait</strong></a>,
\r<a href="device_read_async.html"><strong>device_read_async</strong></a>,
\r<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>,
\r<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>,
\r<a href="device_write_async.html"><strong>device_write_async</strong></a>,
\r<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>.
\r\ No newline at end of file
+<h2>io_done_queue_terminate</h2>
+<hr>
+<p>
+<strong>Function</strong> - Terminate an io_done_queue kernel object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<device/device.h></strong>
+
+<strong>kern_return_t io_done_queue_terminate</strong>
+ <strong>(mach_port_t</strong> <var>queue</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>queue</var>
+<dd>
+[in io-done-queue send right] The port referencing the <strong>io_done_queue</strong>
+to be destroyed.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>io_done_queue_terminate</strong> function is called to destroy a previous
+instatiation of the kernel object supporting asynchronous read/write
+operations on a device.
+<h3>RETURN VALUES</h3>
+<dl>
+ <dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+ Invalid <var>queue</var> parameter.
+ <p>
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>,
+<a href="io_done_queue_wait.html"><strong>io_done_queue_wait</strong></a>,
+<a href="device_read_async.html"><strong>device_read_async</strong></a>,
+<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>,
+<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>,
+<a href="device_write_async.html"><strong>device_write_async</strong></a>,
+<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>.
-<h2>io_done_queue_wait</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> - Wait on an io_done_queue kernel object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t io_done_queue_wait</strong>
\r <strong>(mach_port_t</strong> <var>queue</var>,
\r <strong>io_done_result_t</strong> <var>*result</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>queue</var>
\r<dd>
\r[in io-done-queue send right] The port referencing the io_done_queue
\rto be destroyed.
\r<p>
\r<dt> <var>result</var>
\r<dd>
\r[out structure] The data structure to be filled in with the completion
\rstatus of the I/O operation.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>io_done_queue_wait</strong> interface is called to obtain the results of a
\rpreviously requested asynchronous I/O operation. For each
\r<strong>io_done_queue_wait</strong> invocation, the status of one I/O request is
\rreturned. If there are no pending I/O completions, io_done_queue_wait
\rblocks in the kernel on the address of the completion queue. The
\rmKernel, from interrupt context, enqueues (in FIFO order) completions
\r(struct <strong>io_done_result</strong>'s) on the completion queue and posts a wakeup
\ron the queue for each I/O completion. Completion processing previously
\rdone by the mKernel <strong>io_done thread</strong> is now done by the task thread when
\rit awakens.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r <dt> <strong>KERN_TERMINATED</strong>
\r<dd>
\r Stale <strong>io_done_queue</strong> handle.
\r <p>
\r\r <dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\r Invalid <var>queue</var> parameter.
\r <p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\r The <var>result</var> parameter is a bad address.
\r <p>
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>,
\r<a href="io_done_queue_wait.html"><strong>io_done_queue_wait</strong></a>,
\r<a href="device_read_async.html"><strong>device_read_async</strong></a>,
\r<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>,
\r<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>,
\r<a href="device_write_async.html"><strong>device_write_async</strong></a>,
\r<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>.
\r\ No newline at end of file
+<h2>io_done_queue_wait</h2>
+<hr>
+<p>
+<strong>System Trap</strong> - Wait on an io_done_queue kernel object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t io_done_queue_wait</strong>
+ <strong>(mach_port_t</strong> <var>queue</var>,
+ <strong>io_done_result_t</strong> <var>*result</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>queue</var>
+<dd>
+[in io-done-queue send right] The port referencing the io_done_queue
+to be destroyed.
+<p>
+<dt> <var>result</var>
+<dd>
+[out structure] The data structure to be filled in with the completion
+status of the I/O operation.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>io_done_queue_wait</strong> interface is called to obtain the results of a
+previously requested asynchronous I/O operation. For each
+<strong>io_done_queue_wait</strong> invocation, the status of one I/O request is
+returned. If there are no pending I/O completions, io_done_queue_wait
+blocks in the kernel on the address of the completion queue. The
+mKernel, from interrupt context, enqueues (in FIFO order) completions
+(struct <strong>io_done_result</strong>'s) on the completion queue and posts a wakeup
+on the queue for each I/O completion. Completion processing previously
+done by the mKernel <strong>io_done thread</strong> is now done by the task thread when
+it awakens.
+<h3>RETURN VALUES</h3>
+<dl>
+ <dt> <strong>KERN_TERMINATED</strong>
+<dd>
+ Stale <strong>io_done_queue</strong> handle.
+ <p>
+
+ <dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+ Invalid <var>queue</var> parameter.
+ <p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+ The <var>result</var> parameter is a bad address.
+ <p>
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="io_done_queue_create.html"><strong>io_done_queue_create</strong></a>,
+<a href="io_done_queue_wait.html"><strong>io_done_queue_wait</strong></a>,
+<a href="device_read_async.html"><strong>device_read_async</strong></a>,
+<a href="device_read_async_inband.html"><strong>device_read_async_inband</strong></a>,
+<a href="DR_overwrite_async.html"><strong>device_read_overwrite_async</strong></a>,
+<a href="device_write_async.html"><strong>device_write_async</strong></a>,
+<a href="device_write_async_inband.html"><strong>device_write_async_inband</strong></a>.
-<h2>kernel_resource_sizes</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Used to present the sizes of kernel's major structures.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct kernel_resource_sizes</strong>
\r<strong>{</strong>
\r <strong>vm_size_t</strong> <var>task</var><strong>;</strong>
\r <strong>vm_size_t</strong> <var>thread</var><strong>;</strong>
\r <strong>vm_size_t</strong> <var>port</var><strong>;</strong>
\r <strong>vm_size_t</strong> <var>memory_region</var><strong>;</strong>
\r <strong>vm_size_t</strong> <var>memory_object</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct kernel_resource_sizes* kernel_resource_sizes_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>task</var>
\r<dd>
\rSpace consumed by an empty task.
\r<p>
\r<dt> <var>thread</var>
\r<dd>
\rSpace consumed by a thread.
\r<p>
\r<dt> <var>port</var>
\r<dd>
\rSpace consumed by a port with an empty message queue.
\r<p>
\r<dt> <var>memory_region</var>
\r<dd>
\rSpace consumed by each distinct memory region (as reported by
\r<strong>vm_region</strong>) in a task's address space.
\r<p>
\r<dt> <var>memory_object</var>
\r<dd>
\rSpace consumed to manage a memory object with no resident pages or
\rcopy objects.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>kernel_resource_sizes</strong> structure defines the sizes
\rof significant kernel
\rstructures.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_info.html"><strong>host_info</strong></a>.
\r\ No newline at end of file
+<h2>kernel_resource_sizes</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Used to present the sizes of kernel's major structures.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct kernel_resource_sizes</strong>
+<strong>{</strong>
+ <strong>vm_size_t</strong> <var>task</var><strong>;</strong>
+ <strong>vm_size_t</strong> <var>thread</var><strong>;</strong>
+ <strong>vm_size_t</strong> <var>port</var><strong>;</strong>
+ <strong>vm_size_t</strong> <var>memory_region</var><strong>;</strong>
+ <strong>vm_size_t</strong> <var>memory_object</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct kernel_resource_sizes* kernel_resource_sizes_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>task</var>
+<dd>
+Space consumed by an empty task.
+<p>
+<dt> <var>thread</var>
+<dd>
+Space consumed by a thread.
+<p>
+<dt> <var>port</var>
+<dd>
+Space consumed by a port with an empty message queue.
+<p>
+<dt> <var>memory_region</var>
+<dd>
+Space consumed by each distinct memory region (as reported by
+<strong>vm_region</strong>) in a task's address space.
+<p>
+<dt> <var>memory_object</var>
+<dd>
+Space consumed to manage a memory object with no resident pages or
+copy objects.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>kernel_resource_sizes</strong> structure defines the sizes
+of significant kernel
+structures.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_info.html"><strong>host_info</strong></a>.
-<h2>ledger_create</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Create a subordinate ledger.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t ledger_create</strong>
\r <strong>(ledger_port_t</strong> <var>parent_ledger</var>,
\r <strong>ledger_port_t</strong> <var>ledger_ledger</var>,
\r <strong>ledger_port_t</strong> <var>child_ledger</var>,
\r <strong>ledger_item_t</strong> <var>transfer</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>parent_ledger</var>
\r<dd>
\r[in ledger send right]
\rThe parent ledger.
\r<p>
\r<dt> <var>ledger_ledger</var>
\r<dd>
\r[in ledger send right]
\rThe wired kernel memory ledger providing the
\rspace from which the ledger itself is drawn.
\r<p>
\r<dt> <var>child_ledger</var>
\r<dd>
\r[out ledger send right]
\rThe new child ledger, of the same resource type
\ras the parent ledger.
\r<p>
\r<dt> <var>transfer</var>
\r<dd>
\r[in scalar]
\rThe resource amount to transfer to the new ledger.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>ledger_create</strong> function creates a subordinate ledger.
\rResource limits can be
\rtransferred from the parent ledger. The child ledger itself
\ris accounted against
\rthe <var>ledger_ledger</var>. A new ledger inherits the remote service port.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is not implemented in OSF/1 R1.3.
\r<p>
\rA ledger limit of <strong>LEDGER_ITEM_INFINITE</strong> allows any amount (even
\rinfinity) to be withdrawn. The root ledger has such a limit.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
\r<dd>
\rTransferring the resources would cause the parent ledger to exceed its
\rlimits.
\r<p>
\r<dt> <strong>KERN_INVALID_LEDGER</strong>
\r<dd>
\r<var>ledger_ledger</var> is not a wired kernel memory ledger.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="ledger_transfer.html"><strong>ledger_transfer</strong></a>,
\r<a href="ledger_terminate.html"><strong>ledger_terminate</strong></a>,
\r<a href="ledger_read.html"><strong>ledger_read</strong></a>,
\r<a href="ledger_set_remote.html"><strong>ledger_set_remote</strong></a>.
\r\ No newline at end of file
+<h2>ledger_create</h2>
+<hr>
+<p>
+<strong>Function</strong> - Create a subordinate ledger.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t ledger_create</strong>
+ <strong>(ledger_port_t</strong> <var>parent_ledger</var>,
+ <strong>ledger_port_t</strong> <var>ledger_ledger</var>,
+ <strong>ledger_port_t</strong> <var>child_ledger</var>,
+ <strong>ledger_item_t</strong> <var>transfer</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>parent_ledger</var>
+<dd>
+[in ledger send right]
+The parent ledger.
+<p>
+<dt> <var>ledger_ledger</var>
+<dd>
+[in ledger send right]
+The wired kernel memory ledger providing the
+space from which the ledger itself is drawn.
+<p>
+<dt> <var>child_ledger</var>
+<dd>
+[out ledger send right]
+The new child ledger, of the same resource type
+as the parent ledger.
+<p>
+<dt> <var>transfer</var>
+<dd>
+[in scalar]
+The resource amount to transfer to the new ledger.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>ledger_create</strong> function creates a subordinate ledger.
+Resource limits can be
+transferred from the parent ledger. The child ledger itself
+is accounted against
+the <var>ledger_ledger</var>. A new ledger inherits the remote service port.
+<h3>NOTES</h3>
+<p>
+This interface is not implemented in OSF/1 R1.3.
+<p>
+A ledger limit of <strong>LEDGER_ITEM_INFINITE</strong> allows any amount (even
+infinity) to be withdrawn. The root ledger has such a limit.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
+<dd>
+Transferring the resources would cause the parent ledger to exceed its
+limits.
+<p>
+<dt> <strong>KERN_INVALID_LEDGER</strong>
+<dd>
+<var>ledger_ledger</var> is not a wired kernel memory ledger.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="ledger_transfer.html"><strong>ledger_transfer</strong></a>,
+<a href="ledger_terminate.html"><strong>ledger_terminate</strong></a>,
+<a href="ledger_read.html"><strong>ledger_read</strong></a>,
+<a href="ledger_set_remote.html"><strong>ledger_set_remote</strong></a>.
-<h2>ledger_get_remote</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return send right to specified host's remote ledger port.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t ledger_get_remote</strong>
\r <strong>(ledger_port_t</strong> <var>ledger</var>,
\r <strong>host_t</strong> <var>host_name</var>,
\r <strong>ledger</strong> <var>service_port</var><strong>);</strong>
\r\r\r<strong>kern_return_t ledger_return_remote</strong>
\r <strong>(ledger_port_t</strong> <var>ledger</var>,
\r <strong>host_t</strong> <var>host_name</var>,
\r <strong>ledger</strong> <var>service_port</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>ledger</var>
\r<dd>
\r[in ledger send right]
\rThe ledger whose service port is desired.
\r<p>
\r<dt> <var>host_name</var>
\r<dd>
\r[in host-name send right]
\rThe name for the host requesting the service
\rport.
\r<p>
\r<dt> <var>service_port</var>
\r<dd>
\r[out ledger-service send right]
\rThe ledger service port.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>ledger_get_remote</strong> function returns the remote ledger
\rservice port for the
\rledger
\r<h3>NOTES</h3>
\r<p>
\rThis interface is not implemented in OSF/1 R1.3.
\r<p>
\rThis mechanism supports distributed resource ledgers in the following way:
\r<dl>
\r<dd>
\rWith <strong>ledger_set_remote</strong>, a ledger is assigned a remote
\rledger service port.
\r<dd>
\rThis ledger is used as the ledger for a create operation.
\rIf the ledger is local to the target kernel, all is fine.
\r<dd>
\rFor a non-local creation, the target kernel sees that the supplied
\rledger is not
\ra local ledger. The kernel sends a <strong>ledger_get_remote</strong> message to it,
\rincluding the host name.
\r<dd>
\rThe (remote) ledger receives this message, ignores the host name and returns
\rthe remote ledger service port.
\r<dd>
\rAssuming that the remote ledger service port is not a local ledger, the kernel
\rsends a <strong>ledger_get_remote</strong> message to this service port.
\r<dd>
\rA server receives this request (with the <strong>ledger_return_remote</strong>
\rserver interface)
\rand uses the identity of the service port as well as the host name of the
\rtarget kernel to locate or create a suitable ledger on that kernel.
\r<dd>
\rThe port for a ledger on the target kernel is sent to that kernel and used.
\r</dl>
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="ledger_create.html"><strong>ledger_create</strong></a>,
\r<a href="ledger_set_remote.html"><strong>ledger_set_remote</strong></a>.
\r\ No newline at end of file
+<h2>ledger_get_remote</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return send right to specified host's remote ledger port.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t ledger_get_remote</strong>
+ <strong>(ledger_port_t</strong> <var>ledger</var>,
+ <strong>host_t</strong> <var>host_name</var>,
+ <strong>ledger</strong> <var>service_port</var><strong>);</strong>
+
+
+<strong>kern_return_t ledger_return_remote</strong>
+ <strong>(ledger_port_t</strong> <var>ledger</var>,
+ <strong>host_t</strong> <var>host_name</var>,
+ <strong>ledger</strong> <var>service_port</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>ledger</var>
+<dd>
+[in ledger send right]
+The ledger whose service port is desired.
+<p>
+<dt> <var>host_name</var>
+<dd>
+[in host-name send right]
+The name for the host requesting the service
+port.
+<p>
+<dt> <var>service_port</var>
+<dd>
+[out ledger-service send right]
+The ledger service port.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>ledger_get_remote</strong> function returns the remote ledger
+service port for the
+ledger
+<h3>NOTES</h3>
+<p>
+This interface is not implemented in OSF/1 R1.3.
+<p>
+This mechanism supports distributed resource ledgers in the following way:
+<dl>
+<dd>
+With <strong>ledger_set_remote</strong>, a ledger is assigned a remote
+ledger service port.
+<dd>
+This ledger is used as the ledger for a create operation.
+If the ledger is local to the target kernel, all is fine.
+<dd>
+For a non-local creation, the target kernel sees that the supplied
+ledger is not
+a local ledger. The kernel sends a <strong>ledger_get_remote</strong> message to it,
+including the host name.
+<dd>
+The (remote) ledger receives this message, ignores the host name and returns
+the remote ledger service port.
+<dd>
+Assuming that the remote ledger service port is not a local ledger, the kernel
+sends a <strong>ledger_get_remote</strong> message to this service port.
+<dd>
+A server receives this request (with the <strong>ledger_return_remote</strong>
+server interface)
+and uses the identity of the service port as well as the host name of the
+target kernel to locate or create a suitable ledger on that kernel.
+<dd>
+The port for a ledger on the target kernel is sent to that kernel and used.
+</dl>
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="ledger_create.html"><strong>ledger_create</strong></a>,
+<a href="ledger_set_remote.html"><strong>ledger_set_remote</strong></a>.
-<h2>ledger_read</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return the ledger limit and balance.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t ledger_read</strong>
\r <strong>(ledger_port_t</strong> <var>ledger</var>,
\r <strong>ledger_item_t</strong> <var>balance</var>,
\r <strong>ledger_item_t</strong> <var>maximum</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>ledger</var>
\r<dd>
\r[in ledger send right]
\rThe ledger to read
\r<p>
\r<dt> <var>balance</var>
\r<dd>
\r[out scalar]
\rThe current usage
\r<p>
\r<dt> <var>maximum</var>
\r<dd>
\r[out scalar]
\rThe resource limit
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>ledger_read</strong> function returns the current balance
\rand limit in a ledger.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is not implemented in OSF/1 R1.3.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="ledger_create.html"><strong>ledger_create</strong></a>,
\r<a href="ledger_terminate.html"><strong>ledger_terminate</strong></a>,
\r<a href="ledger_transfer.html"><strong>ledger_transfer</strong></a>.
\r\r\r\ No newline at end of file
+<h2>ledger_read</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return the ledger limit and balance.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t ledger_read</strong>
+ <strong>(ledger_port_t</strong> <var>ledger</var>,
+ <strong>ledger_item_t</strong> <var>balance</var>,
+ <strong>ledger_item_t</strong> <var>maximum</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>ledger</var>
+<dd>
+[in ledger send right]
+The ledger to read
+<p>
+<dt> <var>balance</var>
+<dd>
+[out scalar]
+The current usage
+<p>
+<dt> <var>maximum</var>
+<dd>
+[out scalar]
+The resource limit
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>ledger_read</strong> function returns the current balance
+and limit in a ledger.
+<h3>NOTES</h3>
+<p>
+This interface is not implemented in OSF/1 R1.3.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="ledger_create.html"><strong>ledger_create</strong></a>,
+<a href="ledger_terminate.html"><strong>ledger_terminate</strong></a>,
+<a href="ledger_transfer.html"><strong>ledger_transfer</strong></a>.
+
+
-<h2>ledger_set_remote</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set this host's remote ledger port.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t ledger_set_remote</strong>
\r <strong>(ledger_port_t</strong> <var>ledger</var>,
\r <strong>ledger_port_t</strong> <var>service_port</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>ledger</var>
\r<dd>
\r[in ledger send right]
\rThe ledger whose service port is to be set.
\r<p>
\r<dt> <var>service_port</var>
\r<dd>
\r[in ledger-service send right]
\rThe ledger service port
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>ledger_set_remote</strong> function sets the remote ledger service port
\rfor the ledger. This is the port the ledger will return for
\r<strong>ledger_get_remote</strong> requests.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is not implemented in OSF/1 R1.3.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="ledger_create.html"><strong>ledger_create</strong></a>,
\r<a href="ledger_get_remote.html"><strong>ledger_get_remote</strong></a>.
\r\ No newline at end of file
+<h2>ledger_set_remote</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set this host's remote ledger port.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t ledger_set_remote</strong>
+ <strong>(ledger_port_t</strong> <var>ledger</var>,
+ <strong>ledger_port_t</strong> <var>service_port</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>ledger</var>
+<dd>
+[in ledger send right]
+The ledger whose service port is to be set.
+<p>
+<dt> <var>service_port</var>
+<dd>
+[in ledger-service send right]
+The ledger service port
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>ledger_set_remote</strong> function sets the remote ledger service port
+for the ledger. This is the port the ledger will return for
+<strong>ledger_get_remote</strong> requests.
+<h3>NOTES</h3>
+<p>
+This interface is not implemented in OSF/1 R1.3.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="ledger_create.html"><strong>ledger_create</strong></a>,
+<a href="ledger_get_remote.html"><strong>ledger_get_remote</strong></a>.
-<h2>ledger_terminate</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Destroy a ledger.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t ledger_terminate</strong>
\r <strong>(ledger_port_t</strong> <var>ledger</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>ledger</var>
\r<dd>
\r[in ledger send right]
\rThe ledger to destroy
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>ledger_terminate</strong> function destroys a ledger. All
\rresources drawn from this
\rledger will also be destroyed. The resource limits in the ledger
\rare returned to the ledger's parent.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is not implemented in OSF/1 R1.3.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="ledger_create.html"><strong>ledger_create</strong></a>,
\r<a href="ledger_read.html"><strong>ledger_read</strong></a>,
\r<a href="ledger_transfer.html"><strong>ledger_transfer</strong></a>.
\r\ No newline at end of file
+<h2>ledger_terminate</h2>
+<hr>
+<p>
+<strong>Function</strong> - Destroy a ledger.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t ledger_terminate</strong>
+ <strong>(ledger_port_t</strong> <var>ledger</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>ledger</var>
+<dd>
+[in ledger send right]
+The ledger to destroy
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>ledger_terminate</strong> function destroys a ledger. All
+resources drawn from this
+ledger will also be destroyed. The resource limits in the ledger
+are returned to the ledger's parent.
+<h3>NOTES</h3>
+<p>
+This interface is not implemented in OSF/1 R1.3.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="ledger_create.html"><strong>ledger_create</strong></a>,
+<a href="ledger_read.html"><strong>ledger_read</strong></a>,
+<a href="ledger_transfer.html"><strong>ledger_transfer</strong></a>.
-<h2>ledger_transfer</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Transfer resources from a parent ledger to a child.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t ledger_transfer</strong>
\r <strong>(ledger_port_t</strong> <var>parent_ledger</var>,
\r <strong>ledger_port_t</strong> <var>child_ledger</var>,
\r <strong>ledger_item_t</strong> <var>transfer</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>parent_ledger</var>
\r<dd>
\r[in ledger send right]
\rThe parent ledger
\r<p>
\r<dt> <var>child_ledger</var>
\r<dd>
\r[in ledger send right]
\rThe child ledger
\r<p>
\r<dt> <var>transfer</var>
\r<dd>
\r[in scalar]
\rThe resource amount to transfer. A positive amount moves
\rthe resource allocation from the parent to the child; a negative amount
\rmoves the reverse.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>ledger_transfer</strong> function transfers resources from
\ra parent to a child ledger.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is not implemented in OSF/1 R1.3.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
\r<dd>
\rTransferring the resources would cause one ledger to exceed its limit.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="ledger_create.html"><strong>ledger_create</strong></a>,
\r<a href="ledger_terminate.html"><strong>ledger_terminate</strong></a>,
\r<a href="ledger_read.html"><strong>ledger_read</strong></a>.
\r\ No newline at end of file
+<h2>ledger_transfer</h2>
+<hr>
+<p>
+<strong>Function</strong> - Transfer resources from a parent ledger to a child.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t ledger_transfer</strong>
+ <strong>(ledger_port_t</strong> <var>parent_ledger</var>,
+ <strong>ledger_port_t</strong> <var>child_ledger</var>,
+ <strong>ledger_item_t</strong> <var>transfer</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>parent_ledger</var>
+<dd>
+[in ledger send right]
+The parent ledger
+<p>
+<dt> <var>child_ledger</var>
+<dd>
+[in ledger send right]
+The child ledger
+<p>
+<dt> <var>transfer</var>
+<dd>
+[in scalar]
+The resource amount to transfer. A positive amount moves
+the resource allocation from the parent to the child; a negative amount
+moves the reverse.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>ledger_transfer</strong> function transfers resources from
+a parent to a child ledger.
+<h3>NOTES</h3>
+<p>
+This interface is not implemented in OSF/1 R1.3.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
+<dd>
+Transferring the resources would cause one ledger to exceed its limit.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="ledger_create.html"><strong>ledger_create</strong></a>,
+<a href="ledger_terminate.html"><strong>ledger_terminate</strong></a>,
+<a href="ledger_read.html"><strong>ledger_read</strong></a>.
-<h2>lock_acquire</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Acquire access rights to a lock.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t lock_acquire</strong>
\r <strong>(lock_set_t</strong> <var>lock_set</var>,
\r <strong>int</strong> <var>lock_id</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>lock_set</var>
\r<dd>
\r[in send right] The port naming the lock set which represents the
\rlock.
\r<p>
\r<dt> <var>lock_id</var>
\r<dd>
\r[in scalar] The lock, represented by the lock set, to be acquired.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>lock_acquire</strong> function acquires access rights to a specific lock
\rbeing represented by a given lock set. If the lock is already
\rcontrolled by another thread then the calling thread will block.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe lock was acquired.
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe specified lock set is invalid, or the lock id is out of range.
\r<p>
\r<dt> <strong>KERN_LOCK_UNSTABLE</strong>
\r<dd>
\rThe acquired lock has an unstable state.
\r <p>
\r<dt> <strong>KERN_LOCK_SET_DESTROYED</strong>
\r<dd>
\rThe specified lock has been destroyed.
\r<p>
\r<dt> <strong>KERN_ABORTED</strong>
\r<dd>
\rWhile blocked to wait for the specified lock to become available, the calling
\r thread was awoken by an unrelated event, such as thread termination.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="lock_release.html"><strong>lock_release</strong></a>,
\r<a href="lock_try.html"><strong>lock_try</strong></a>,
\r<a href="lock_handoff.html"><strong>lock_handoff</strong></a>,
\r<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>,
\r<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>,
\r<a href="lock_set_create.html"><strong>lock_set_create</strong></a>,
\r<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>.
\r\ No newline at end of file
+<h2>lock_acquire</h2>
+<hr>
+<p>
+<strong>Function</strong> - Acquire access rights to a lock.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t lock_acquire</strong>
+ <strong>(lock_set_t</strong> <var>lock_set</var>,
+ <strong>int</strong> <var>lock_id</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>lock_set</var>
+<dd>
+[in send right] The port naming the lock set which represents the
+lock.
+<p>
+<dt> <var>lock_id</var>
+<dd>
+[in scalar] The lock, represented by the lock set, to be acquired.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>lock_acquire</strong> function acquires access rights to a specific lock
+being represented by a given lock set. If the lock is already
+controlled by another thread then the calling thread will block.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The lock was acquired.
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The specified lock set is invalid, or the lock id is out of range.
+<p>
+<dt> <strong>KERN_LOCK_UNSTABLE</strong>
+<dd>
+The acquired lock has an unstable state.
+ <p>
+<dt> <strong>KERN_LOCK_SET_DESTROYED</strong>
+<dd>
+The specified lock has been destroyed.
+<p>
+<dt> <strong>KERN_ABORTED</strong>
+<dd>
+While blocked to wait for the specified lock to become available, the calling
+ thread was awoken by an unrelated event, such as thread termination.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="lock_release.html"><strong>lock_release</strong></a>,
+<a href="lock_try.html"><strong>lock_try</strong></a>,
+<a href="lock_handoff.html"><strong>lock_handoff</strong></a>,
+<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>,
+<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>,
+<a href="lock_set_create.html"><strong>lock_set_create</strong></a>,
+<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>.
-<h2>lock_handoff</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Hand-off ownership of a lock.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t lock_handoff</strong>
\r <strong>(lock_set_t</strong> <var>lock_set</var>,
\r <strong>int</strong> <var>lock_id</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>lock_set</var>
\r<dd>
\r[in send right] The port naming the lock set which represents the
\rlock.
\r<p>
\r<dt> <var>lock_id</var>
\r<dd>
\r[in scalar] The lock, represented by the lock set, to be handed off.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>lock_handoff</strong> function passes lock ownership from the calling
\rthread to an anonymous accepting thread. The lock must be owned by the
\rcalling thread. If the accepting thread is not waiting to receive the
\rlock, the calling thread will block until the hand-off is accepted.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe specified lock_set is invalid, or the lock_id is out of range.
\r<p>
\r<dt> <strong>KERN_INVALID_RIGHT</strong>
\r<dd>
\rThe calling thread does not own the lock being handed off.
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe lock hand-off was successful.
\r<p>
\r<dt> <strong>KERN_LOCK_SET_DESTROYED</strong>
\r<dd>
\rThe specified lock has been destroyed.
\r<p>
\r<dt> <strong>KERN_ABORTED</strong>
\r<dd>
\rWhile blocked to wait for the accepting thread to assume the lock's ownership,
\r the calling thread was awoken by an unrelated event;
\r the lock's handoff state is cleared.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="lock_acquire.html"><strong>lock_acquire</strong></a>,
\r<a href="lock_release.html"><strong>lock_release</strong></a>,
\r<a href="lock_try.html"><strong>lock_try</strong></a>,
\r<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>,
\r<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>,
\r<a href="lock_set_create.html"><strong>lock_set_create</strong></a>,
\r<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>.
\r\ No newline at end of file
+<h2>lock_handoff</h2>
+<hr>
+<p>
+<strong>Function</strong> - Hand-off ownership of a lock.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t lock_handoff</strong>
+ <strong>(lock_set_t</strong> <var>lock_set</var>,
+ <strong>int</strong> <var>lock_id</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>lock_set</var>
+<dd>
+[in send right] The port naming the lock set which represents the
+lock.
+<p>
+<dt> <var>lock_id</var>
+<dd>
+[in scalar] The lock, represented by the lock set, to be handed off.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>lock_handoff</strong> function passes lock ownership from the calling
+thread to an anonymous accepting thread. The lock must be owned by the
+calling thread. If the accepting thread is not waiting to receive the
+lock, the calling thread will block until the hand-off is accepted.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The specified lock_set is invalid, or the lock_id is out of range.
+<p>
+<dt> <strong>KERN_INVALID_RIGHT</strong>
+<dd>
+The calling thread does not own the lock being handed off.
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The lock hand-off was successful.
+<p>
+<dt> <strong>KERN_LOCK_SET_DESTROYED</strong>
+<dd>
+The specified lock has been destroyed.
+<p>
+<dt> <strong>KERN_ABORTED</strong>
+<dd>
+While blocked to wait for the accepting thread to assume the lock's ownership,
+ the calling thread was awoken by an unrelated event;
+ the lock's handoff state is cleared.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="lock_acquire.html"><strong>lock_acquire</strong></a>,
+<a href="lock_release.html"><strong>lock_release</strong></a>,
+<a href="lock_try.html"><strong>lock_try</strong></a>,
+<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>,
+<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>,
+<a href="lock_set_create.html"><strong>lock_set_create</strong></a>,
+<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>.
-<h2>lock_handoff_accept</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Accept a lock hand-off.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t lock_handoff_accept</strong>
\r <strong>(lock_set_t</strong> <var>lock_set</var>,
\r <strong>int</strong> <var>lock_id</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>lock_set</var>
\r<dd>
\r[in send right] The port naming the lock set which represents the
\rlock.
\r<p>
\r<dt> <var>lock_id</var>
\r<dd>
\r[in scalar] The lock, represented by the lock set, that is the object
\rof the handoff operation.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>lock_handoff_accept</strong> function accepts a lock
\rhand-off from an anonymous sending thread. If the sending thread is
\rnot waiting to hand-off the lock, the calling thread will block until
\rthe lock handoff is completed. Only one thread may be waiting to
\raccept a lock handoff at any given time.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_ALREADY_WAITING</strong>
\r<dd>
\rAnother thread is already waiting for a hand-off of this lock.
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe specified lock_set is invalid, or the lock_id is out of range.
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe lock hand-off was successful.
\r<p>
\r<dt> <strong>KERN_LOCK_UNSTABLE</strong>
\r<dd>
\rThe acquired lock has an unstable state.
\r<p>
\r<dt> <strong>KERN_LOCK_SET_DESTROYED</strong>
\r<dd>
\rThe specified lock has been destroyed.
\r<p>
\r<dt> <strong>KERN_ABORTED</strong>
\r<dd>
\rWhile blocked to wait for the sending thread to transfer the lock's ownership,
\r the calling thread was awoken by an unrelated event;
\r the lock's handoff state is cleared.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="lock_acquire.html"><strong>lock_acquire</strong></a>,
\r<a href="lock_release.html"><strong>lock_release</strong></a>,
\r<a href="lock_try.html"><strong>lock_try</strong></a>,
\r<a href="lock_handoff.html"><strong>lock_handoff</strong></a>.
\r\ No newline at end of file
+<h2>lock_handoff_accept</h2>
+<hr>
+<p>
+<strong>Function</strong> - Accept a lock hand-off.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t lock_handoff_accept</strong>
+ <strong>(lock_set_t</strong> <var>lock_set</var>,
+ <strong>int</strong> <var>lock_id</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>lock_set</var>
+<dd>
+[in send right] The port naming the lock set which represents the
+lock.
+<p>
+<dt> <var>lock_id</var>
+<dd>
+[in scalar] The lock, represented by the lock set, that is the object
+of the handoff operation.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>lock_handoff_accept</strong> function accepts a lock
+hand-off from an anonymous sending thread. If the sending thread is
+not waiting to hand-off the lock, the calling thread will block until
+the lock handoff is completed. Only one thread may be waiting to
+accept a lock handoff at any given time.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_ALREADY_WAITING</strong>
+<dd>
+Another thread is already waiting for a hand-off of this lock.
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The specified lock_set is invalid, or the lock_id is out of range.
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The lock hand-off was successful.
+<p>
+<dt> <strong>KERN_LOCK_UNSTABLE</strong>
+<dd>
+The acquired lock has an unstable state.
+<p>
+<dt> <strong>KERN_LOCK_SET_DESTROYED</strong>
+<dd>
+The specified lock has been destroyed.
+<p>
+<dt> <strong>KERN_ABORTED</strong>
+<dd>
+While blocked to wait for the sending thread to transfer the lock's ownership,
+ the calling thread was awoken by an unrelated event;
+ the lock's handoff state is cleared.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="lock_acquire.html"><strong>lock_acquire</strong></a>,
+<a href="lock_release.html"><strong>lock_release</strong></a>,
+<a href="lock_try.html"><strong>lock_try</strong></a>,
+<a href="lock_handoff.html"><strong>lock_handoff</strong></a>.
-<h2>lock_make_stable</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Stabilize the state of the specified lock.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t lock_make_stable</strong>
\r <strong>(lock_set_t</strong> <var>lock_set</var>,
\r <strong>int</strong> <var>lock_id</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>lock_set</var>
\r<dd>
\r[in send right] The port naming the lock set which represents the
\rlock.
\r<p>
\r<dt> <var>lock_id</var>
\r<dd>
\r[in scalar] The lock, represented by the lock set, to be stabilized.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>lock_make_stable</strong> function clears the specified lock's unstable
\rstate, making the lock's state stable again.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe specified lock set is invalid, or the lock id is out of range.
\r <p>
\r <dt> <strong>KERN_INVALID_RIGHT</strong>
\r <dd>
\r The caller does not own the specified lock.
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe lock's state was stabilized.
\r<p>
\r<dt> <strong>KERN_LOCK_SET_DESTROYED</strong>
\r<dd>
\rThe specified lock has been destroyed.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="lock_acquire.html"><strong>lock_acquire</strong></a>,
\r<a href="lock_release.html"><strong>lock_release</strong></a>,
\r<a href="lock_try.html"><strong>lock_try</strong></a>,
\r<a href="lock_handoff.html"><strong>lock_handoff</strong></a>,
\r<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>,
\r<a href="lock_set_create.html"><strong>lock_set_create</strong></a>,
\r<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>.
\r\ No newline at end of file
+<h2>lock_make_stable</h2>
+<hr>
+<p>
+<strong>Function</strong> - Stabilize the state of the specified lock.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t lock_make_stable</strong>
+ <strong>(lock_set_t</strong> <var>lock_set</var>,
+ <strong>int</strong> <var>lock_id</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>lock_set</var>
+<dd>
+[in send right] The port naming the lock set which represents the
+lock.
+<p>
+<dt> <var>lock_id</var>
+<dd>
+[in scalar] The lock, represented by the lock set, to be stabilized.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>lock_make_stable</strong> function clears the specified lock's unstable
+state, making the lock's state stable again.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The specified lock set is invalid, or the lock id is out of range.
+ <p>
+ <dt> <strong>KERN_INVALID_RIGHT</strong>
+ <dd>
+ The caller does not own the specified lock.
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The lock's state was stabilized.
+<p>
+<dt> <strong>KERN_LOCK_SET_DESTROYED</strong>
+<dd>
+The specified lock has been destroyed.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="lock_acquire.html"><strong>lock_acquire</strong></a>,
+<a href="lock_release.html"><strong>lock_release</strong></a>,
+<a href="lock_try.html"><strong>lock_try</strong></a>,
+<a href="lock_handoff.html"><strong>lock_handoff</strong></a>,
+<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>,
+<a href="lock_set_create.html"><strong>lock_set_create</strong></a>,
+<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>.
-<h2>lock_release</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Release ownership of a lock.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t lock_release</strong>
\r <strong>(lock_set_t</strong> <var>lock_set</var>,
\r <strong>int</strong> <var>lock_id</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>lock_set</var>
\r<dd>
\r[in send right] The port naming the lock set which represents the
\rlock.
\r<p>
\r<dt> <var>lock_id</var>
\r<dd>
\r[in scalar] The lock, represented by the lock set, to be released.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>lock_release</strong> function release the ownership of the specified lock.
\rIf the calling thread does not own the lock then the call will fail.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe specified lock_set is invalid, or the lock_id is out of range.
\r <p>
\r <dt> <strong>KERN_INVALID_RIGHT</strong>
\r <dd>
\r The specified task does not own the specified lock.
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe ownership of the lock was released.
\r<p>
\r<dt> <strong>KERN_LOCK_SET_DESTROYED</strong>
\r<dd>
\rThe specified lock has been destroyed.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="lock_acquire.html"><strong>lock_acquire</strong></a>,
\r<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>,
\r<a href="lock_try.html"><strong>lock_try</strong></a>,
\r<a href="lock_handoff.html"><strong>lock_handoff</strong></a>,
\r<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>,
\r<a href="lock_set_create.html"><strong>lock_set_create</strong></a>,
\r<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>.
\r\ No newline at end of file
+<h2>lock_release</h2>
+<hr>
+<p>
+<strong>Function</strong> - Release ownership of a lock.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t lock_release</strong>
+ <strong>(lock_set_t</strong> <var>lock_set</var>,
+ <strong>int</strong> <var>lock_id</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>lock_set</var>
+<dd>
+[in send right] The port naming the lock set which represents the
+lock.
+<p>
+<dt> <var>lock_id</var>
+<dd>
+[in scalar] The lock, represented by the lock set, to be released.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>lock_release</strong> function release the ownership of the specified lock.
+If the calling thread does not own the lock then the call will fail.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The specified lock_set is invalid, or the lock_id is out of range.
+ <p>
+ <dt> <strong>KERN_INVALID_RIGHT</strong>
+ <dd>
+ The specified task does not own the specified lock.
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The ownership of the lock was released.
+<p>
+<dt> <strong>KERN_LOCK_SET_DESTROYED</strong>
+<dd>
+The specified lock has been destroyed.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="lock_acquire.html"><strong>lock_acquire</strong></a>,
+<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>,
+<a href="lock_try.html"><strong>lock_try</strong></a>,
+<a href="lock_handoff.html"><strong>lock_handoff</strong></a>,
+<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>,
+<a href="lock_set_create.html"><strong>lock_set_create</strong></a>,
+<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>.
-<h2>lock_set_create</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Create a new lock set.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t lock_set_create</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>lock_set_t</strong> <var>lock_set</var>,
\r <strong>int</strong> <var>locks</var>,
\r <strong>int</strong> <var>policy</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\rThe task receiving the send right to the newly created lock set.
\r<p>
\r<dt> <var>lock_set</var>
\r<dd>
\r[out send right] The port naming the lock set which represents the lock.
\r<p>
\r<dt> <var>locks</var>
\r<dd>
\r[in scalar] The number of locks the lock set will represent (must be a positive value).
\r<p>
\r<dt> <var>policy</var>
\r<dd>
\r[in scalar] The blocked thread wakeup policy for the newly created lock set. Valid policies are:
\r <dl>
\r<p>
\r<dt> SYNC_POLICY_FIFO
\r<dd>
\ra first-in-first-out policy for scheduling thread wakeup.
\r<p>
\r<dt> SYNC_POLICY_FIXED_PRIORITY
\r<dd>
\ra fixed priority policy for scheduling thread wakeup.
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>lock_set_create</strong> function creates a new lock set representing a
\rcollection of associated locks. The lock set is associated with the
\rspecified task. A send right naming the lock set is returned to the
\rcaller.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe lock set was created.
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rEither the task or policy argument is invalid, or the locks argument
\rhas a value that is less than or equal to zero.
\r<p>
\r<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
\r<dd>
\rThe kernel could not allocate the lock set.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="lock_acquire.html"><strong>lock_acquire</strong></a>,
\r<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>,
\r<a href="lock_try.html"><strong>lock_try</strong></a>,
\r<a href="lock_handoff.html"><strong>lock_handoff</strong></a>,
\r<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>,
\r<a href="lock_try.html"><strong>lock_try</strong></a>,
\r<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>.
\r\ No newline at end of file
+<h2>lock_set_create</h2>
+<hr>
+<p>
+<strong>Function</strong> - Create a new lock set.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t lock_set_create</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>lock_set_t</strong> <var>lock_set</var>,
+ <strong>int</strong> <var>locks</var>,
+ <strong>int</strong> <var>policy</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+The task receiving the send right to the newly created lock set.
+<p>
+<dt> <var>lock_set</var>
+<dd>
+[out send right] The port naming the lock set which represents the lock.
+<p>
+<dt> <var>locks</var>
+<dd>
+[in scalar] The number of locks the lock set will represent (must be a positive value).
+<p>
+<dt> <var>policy</var>
+<dd>
+[in scalar] The blocked thread wakeup policy for the newly created lock set. Valid policies are:
+ <dl>
+<p>
+<dt> SYNC_POLICY_FIFO
+<dd>
+a first-in-first-out policy for scheduling thread wakeup.
+<p>
+<dt> SYNC_POLICY_FIXED_PRIORITY
+<dd>
+a fixed priority policy for scheduling thread wakeup.
+</dl>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>lock_set_create</strong> function creates a new lock set representing a
+collection of associated locks. The lock set is associated with the
+specified task. A send right naming the lock set is returned to the
+caller.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The lock set was created.
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+Either the task or policy argument is invalid, or the locks argument
+has a value that is less than or equal to zero.
+<p>
+<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
+<dd>
+The kernel could not allocate the lock set.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="lock_acquire.html"><strong>lock_acquire</strong></a>,
+<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>,
+<a href="lock_try.html"><strong>lock_try</strong></a>,
+<a href="lock_handoff.html"><strong>lock_handoff</strong></a>,
+<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>,
+<a href="lock_try.html"><strong>lock_try</strong></a>,
+<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>.
-<h2>lock_set_destroy</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Destroy a lock set and its associated locks.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t lock_set_destroy</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>lock_set_t</strong> <var>lock_set</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\rThe task associated with the lock set.
\r<p>
\r<dt> <var>lock_set</var>
\r<dd>
\r[in send right] The port naming the lock set being destroyed.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>lock_set_destroy</strong> function will destroy a lock set and all of its
\rassociated locks. Threads that are blocked on locks represented by the
\rdestroyed lock set are unblocked and will receive a
\rKERN_LOCK_SET_DESTROYED error message indicating that the lock set was
\rdestroyed. The <strong>lock_set_destroy</strong> function will only succeed if the
\rspecified task is associated with the specified lock set.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe specified lock set or task is invalid.
\r <p>
\r <dt> <strong>KERN_INVALID_RIGHT</strong>
\r <dd>
\r The specified task does not own the specified lock set.
\r<p>
\r <dt> <strong>KERN_LOCK_SET_DESTROYED</strong>
\r <dd>
\r The specified lock set does not exist.
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe lock set was destroyed.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="lock_acquire.html"><strong>lock_acquire</strong></a>,
\r<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>,
\r<a href="lock_try.html"><strong>lock_try</strong></a>,
\r<a href="lock_handoff.html"><strong>lock_handoff</strong></a>,
\r<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>,
\r<a href="lock_try.html"><strong>lock_try</strong></a>,
\r<a href="lock_set_create.html"><strong>lock_set_create</strong></a>.
\r\ No newline at end of file
+<h2>lock_set_destroy</h2>
+<hr>
+<p>
+<strong>Function</strong> - Destroy a lock set and its associated locks.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t lock_set_destroy</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>lock_set_t</strong> <var>lock_set</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+The task associated with the lock set.
+<p>
+<dt> <var>lock_set</var>
+<dd>
+[in send right] The port naming the lock set being destroyed.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>lock_set_destroy</strong> function will destroy a lock set and all of its
+associated locks. Threads that are blocked on locks represented by the
+destroyed lock set are unblocked and will receive a
+KERN_LOCK_SET_DESTROYED error message indicating that the lock set was
+destroyed. The <strong>lock_set_destroy</strong> function will only succeed if the
+specified task is associated with the specified lock set.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The specified lock set or task is invalid.
+ <p>
+ <dt> <strong>KERN_INVALID_RIGHT</strong>
+ <dd>
+ The specified task does not own the specified lock set.
+<p>
+ <dt> <strong>KERN_LOCK_SET_DESTROYED</strong>
+ <dd>
+ The specified lock set does not exist.
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The lock set was destroyed.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="lock_acquire.html"><strong>lock_acquire</strong></a>,
+<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>,
+<a href="lock_try.html"><strong>lock_try</strong></a>,
+<a href="lock_handoff.html"><strong>lock_handoff</strong></a>,
+<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>,
+<a href="lock_try.html"><strong>lock_try</strong></a>,
+<a href="lock_set_create.html"><strong>lock_set_create</strong></a>.
-<h2>lock_try</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Attempt to acquire access rights to a lock.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t lock_try</strong>
\r <strong>(lock_set_t</strong> <var>lock_set</var>,
\r <strong>int</strong> <var>lock_id</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>lock_set</var>
\r<dd>
\r[in send right] The port naming the lock set which represents the lock.
\r<p>
\r<dt> <var>lock_id</var>
\r<dd>
\r[in scalar] The lock, represented by the lock set, to be acquired.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>lock_try</strong> function attempts to acquire the specified lock without
\rblocking. The return value indicates whether the lock was acquired.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe specified lock_set is invalid, or the lock_id is out of range.
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe lock was acquired.
\r<p>
\r<dt> <strong>KERN_LOCK_UNSTABLE</strong>
\r<dd>
\rThe acquired lock has an unstable state.
\r<p>
\r<dt> <strong>KERN_LOCK_SET_DESTROYED</strong>
\r<dd>
\rThe specified lock has been destroyed.
\r<p>
\r<dt> <strong>KERN_LOCK_OWNED</strong>
\r<dd>
\rAnother thread currently owns the requested lock.
\r<p>
\r<dt> <strong>KERN_LOCK_OWNED_SELF</strong>
\r<dd>
\rThe calling thread already owns the lock.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="lock_acquire.html"><strong>lock_acquire</strong></a>,
\r<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>,
\r<a href="lock_release.html"><strong>lock_release</strong></a>,
\r<a href="lock_handoff.html"><strong>lock_handoff</strong></a>,
\r<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>,
\r<a href="lock_set_create.html"><strong>lock_set_create</strong></a>,
\r<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>.
\r\ No newline at end of file
+<h2>lock_try</h2>
+<hr>
+<p>
+<strong>Function</strong> - Attempt to acquire access rights to a lock.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t lock_try</strong>
+ <strong>(lock_set_t</strong> <var>lock_set</var>,
+ <strong>int</strong> <var>lock_id</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>lock_set</var>
+<dd>
+[in send right] The port naming the lock set which represents the lock.
+<p>
+<dt> <var>lock_id</var>
+<dd>
+[in scalar] The lock, represented by the lock set, to be acquired.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>lock_try</strong> function attempts to acquire the specified lock without
+blocking. The return value indicates whether the lock was acquired.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The specified lock_set is invalid, or the lock_id is out of range.
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The lock was acquired.
+<p>
+<dt> <strong>KERN_LOCK_UNSTABLE</strong>
+<dd>
+The acquired lock has an unstable state.
+<p>
+<dt> <strong>KERN_LOCK_SET_DESTROYED</strong>
+<dd>
+The specified lock has been destroyed.
+<p>
+<dt> <strong>KERN_LOCK_OWNED</strong>
+<dd>
+Another thread currently owns the requested lock.
+<p>
+<dt> <strong>KERN_LOCK_OWNED_SELF</strong>
+<dd>
+The calling thread already owns the lock.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="lock_acquire.html"><strong>lock_acquire</strong></a>,
+<a href="lock_make_stable.html"><strong>lock_make_stable</strong></a>,
+<a href="lock_release.html"><strong>lock_release</strong></a>,
+<a href="lock_handoff.html"><strong>lock_handoff</strong></a>,
+<a href="lock_handoff_accept.html"><strong>lock_handoff_accept</strong></a>,
+<a href="lock_set_create.html"><strong>lock_set_create</strong></a>,
+<a href="lock_set_destroy.html"><strong>lock_set_destroy</strong></a>.
-<h2>mach_host_self</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> - Returns the host self port
\r<h3>SYNOPSIS</h3>
\r<pre>
\rhost_name_port_t mach_host_self( void );</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<p>
\rNone.
\r\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_host_self</strong> function
\rreturns send rights to the task's host self port.
\rBy default, this is the name port for the current host
\rbut can be a different value if so set.
\r\r<h3>RETURN VALUES</h3>
\r<p>
\r[host-self send right] Send rights to the host's name port.
\r\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_info.html"><strong>host_info</strong></a>,
\r<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>.
\r\ No newline at end of file
+<h2>mach_host_self</h2>
+<hr>
+<p>
+<strong>System Trap</strong> - Returns the host self port
+<h3>SYNOPSIS</h3>
+<pre>
+host_name_port_t mach_host_self( void );</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<p>
+None.
+
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_host_self</strong> function
+returns send rights to the task's host self port.
+By default, this is the name port for the current host
+but can be a different value if so set.
+
+<h3>RETURN VALUES</h3>
+<p>
+[host-self send right] Send rights to the host's name port.
+
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_info.html"><strong>host_info</strong></a>,
+<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>.
-<h2>mach_msg</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> / <strong>Function</strong> - Send and/or receive a message from the target port.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>mach_msg_return_t mach_msg</strong>
\r <strong>(mach_msg_header_t</strong> <var>msg</var>,
\r <strong>mach_msg_option_t</strong> <var>option</var>,
\r <strong>mach_msg_size_t</strong> <var>send_size</var>,
\r <strong>mach_msg_size_t</strong> <var>receive_limit</var>,
\r <strong>mach_port_t</strong> <var>receive_name</var>,
\r <strong>mach_msg_timeout_t</strong> <var>timeout</var>,
\r <strong>mach_port_t</strong> <var>notify</var><strong>);</strong>
\r\r<strong>mach_msg_return_t mach_msg_overwrite</strong>
\r <strong>(mach_msg_header_t*</strong> <var>send_msg</var>,
\r <strong>mach_msg_option_t</strong> <var>option</var>,
\r <strong>mach_msg_size_t</strong> <var>send_size</var>,
\r <strong>mach_msg_size_t</strong> <var>receive_limit</var>,
\r <strong>mach_port_t</strong> <var>receive_name</var>,
\r <strong>mach_msg_timeout_t</strong> <var>timeout</var>,
\r <strong>mach_port_t</strong> <var>notify</var>,
\r <strong>mach_msg_header_t</strong> <var>*receive_msg</var>,
\r <strong>mach_msg_size_t</strong> <var>receive_msg_size</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>msg</var>
\r<dd>
\r[pointer to in/out structure containing random and reply rights] A
\rmessage buffer used by <strong>mach_msg</strong> both for send and receive. This must
\rbe naturally aligned.
\r<p>
\r<dt> <var>send_msg</var>
\r<dd>
\r[pointer to in structure containing random and reply rights] The mes-
\rsage buffer to be sent. This must be naturally aligned.
\r<p>
\r<dt> <var>option</var>
\r<dd>
\r[in scalar] Message options are bit values, combined with bitwise-or.
\rOne or both of MACH_SEND_MSG and MACH_RCV_MSG should be used. Other
\roptions act as modifiers.
\r<p>
\r<dt> <var>send_size</var>
\r<dd>
\r[in scalar] When sending a message, specifies the size of the message
\rbuffer to be sent (the size of the header and body) in
\rbytes. Otherwise zero should be supplied.
\r<p>
\r<dt> <var>receive_limit</var>
\r<dd>
\r[in scalar] When receiving a message, specifies the maximum size of
\rthe msg or receive_msg buffer in bytes. Otherwise zero should be sup-
\rplied.
\r<p>
\r<dt> <var>receive_name</var>
\r<dd>
\r[in random right] When receiving a message, specifies the port or port
\rset. Otherwise MACH_PORT_NULL should be supplied.
\r<p>
\r<dt> <var>timeout</var>
\r<dd>
\r[in scalar] When using the MACH_SEND_TIMEOUT and MACH_RCV_TIMEOUT
\roptions, specifies the time in milliseconds to wait before giving
\rup. Otherwise MACH_MSG_TIMEOUT_NONE should be supplied.
\r<p>
\r<dt> <var>notify</var>
\r<dd>
\r[in notify receive right] When using the MACH_SEND_CANCEL and
\rMACH_RCV_NOTIFY options, specifies the port used for the
\rnotification. Otherwise MACH_PORT_NULL should be supplied.
\r<p>
\r<dt> <var>receive_msg</var>
\r<dd>
\r[pointer to in/out structure] A message buffer into which a message
\r(header and body) will be received. This must be naturally aligned. By
\rdefault (<strong>mach_msg</strong>), any received message will overwrite the send
\rmessage buffer. This buffer is in/out only if the MACH_RCV_OVERWRITE
\roption is used; otherwise this buffer is out only.
\r<p>
\r<dt> <var>receive_msg_size</var>
\r<dd>
\r[in scalar] When using the MACH_RCV_OVERWRITE option, specifies the
\rsize (in bytes) of the receive "message" that is to be used by
\r<strong>mach_msg</strong> to indicate the disposition of received out-of-line regions.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_msg</strong> system call sends and receives Mach messages. Mach
\rmessages contain data, which can include port rights and addresses of
\rlarge regions of memory. <strong>mach_msg</strong> uses the same buffer for sending and
\rreceiving a message; the other calls permit separate send and receive
\rbuffers (although they may be specified to be the same).
\rIf the option argument contains MACH_SEND_MSG, the call sends a
\rmessage. The <var>send_size</var> argument specifies the size of the message
\rbuffer (header and body) to send. The msgh_remote_port field of the
\rmessage header specifies the destination of the message.
\rIf the option argument contains MACH_RCV_MSG, it receives a
\rmessage. The receive_limit argument specifies the size of a buffer
\rthat will receive the message; messages that are larger are not
\rreceived. The receive_name argument specifies the port or port set
\rfrom which to receive.
\r<p>
\rIf the option argument contains both MACH_SEND_MSG and MACH_RCV_MSG,
\rthen <strong>mach_msg</strong> does both send and receive operations (in that
\rorder). If the send operation encounters an error (any return code
\rother than MACH_MSG_SUCCESS), the call returns immediately
\rwithout attempting the receive operation. Semantically the combined
\rcall is equivalent to separate send and receive calls, but it saves
\ra system call and enables other internal optimizations.
\r\rIf the option argument specifies neither MACH_SEND_MSG nor
\rMACH_RCV_MSG, <strong>mach_msg</strong> does nothing.
\rSome options, like MACH_SEND_TIMEOUT and MACH_RCV_TIMEOUT, share a
\rsupporting argument. If these options are used together, they make
\rindependent use of the supporting argument's value.
\r<h3>NOTES</h3>
\r<p>
\rThe Mach kernel provides message-oriented, capability-based
\rinter-process communication. The inter-process communication (IPC)
\rprimitives efficiently support many different styles of interaction,
\rincluding remote procedure calls, object-oriented distributed
\rprogramming, streaming of data, and sending very large amounts of
\rdata.
\r<h4>Major Concepts</h4>
\r<p>
\rThe IPC primitives operate on three abstractions: messages, ports, and
\rport sets. User tasks access all other kernel services and
\rabstractions via the IPC primitives.
\r<p>
\rThe message primitives let tasks send and receive messages. Tasks send
\rmessages to ports. Messages sent to a port are delivered reliably
\r(messages may not be lost) and are received in the order in which they
\rwere sent via send rights by a given sending task (or a given
\rkernel). (Messages sent to send-once rights are unordered.)
\r<p>
\rMessages
\rcontain a fixed-size header and a variable-sized message body
\rcontaining kernel and user data, and a variable-size trailer of kernel
\rappended message attributes. The header describes the destination
\rand the size of the message (header plus body). The message body
\rcontains descriptions of additional port rights to be transmitted,
\rdescriptions of "out-of-line" memory regions to be sent and a
\rvariable amount of user data, which typically includes type conversion
\rinformation. The out-of-line memory regions (including out-of-line
\rport arrays) are (typically) disjoint from the message body.
\rThe IPC implementation makes use of the VM system to efficiently
\rtransfer large amounts of data. The message can contain the addresses
\rof regions of the sender's address space which should be transferred
\ras part of the message.
\r<p>
\rWhen a task receives a message containing
\rsuch out-of-line regions of data, the data can appear in unused
\rportions or overwrite an existing portion of the receiver's address
\rspace (depending on the requested receive options). Under favorable
\rcircumstances, the transmission of out-of-line data is optimized so
\rthat sender and receiver share the physical pages of data
\rcopy-on-write, and no actual data copy occurs unless the pages are
\rwritten. Regions of memory up to 4 gigabytes may be sent in this
\rmanner.
\r<p>
\rPorts hold a queue of messages. Tasks operate on a port to send and
\rreceive messages by exercising capabilities (rights) for the
\rport. Multiple tasks can hold send rights for a port.
\rTasks can also
\rhold send-once rights, which grant the ability to send a single
\rmessage. Only one task can hold the receive capability (receive
\rright) for a port.
\r<p>
\rPort rights can be transferred between tasks via
\rmessages. The sender of a message can specify in the message that the
\rmessage contains a port right. If a message contains a receive right
\rfor a port, the receive right is removed from the sender of the
\rmessage and transferred to the receiver of the
\rmessage. While the receive right is in transit, tasks holding send
\rrights can still send messages to the port, and they are queued until
\ra task acquires the receive right and uses it to receive the messages.
\r<p>
\rTasks can receive messages from ports and port sets. The port set
\rabstraction allows a single thread to wait for a message from any of
\rseveral ports. Tasks manipulate port sets with a port set name,
\rwhich is taken from the same name space as are the port rights. The
\rport-set name may not be transferred in a message. A port set holds
\rreceive rights, and a receive operation on a port set blocks waiting
\rfor a message sent to any of the constituent ports. A port may not be-
\rlong to more than one port set, and if a port is a member of a port
\rset, the holder of the receive right can't receive directly from the
\rport.
\r<p>
\rPort rights are a secure, location-independent way of naming
\rports. The port queue is a protected data structure, only accessible
\rvia the kernel's exported message primitives. Rights are also
\rprotected by the kernel; there is no way for a malicious user task to
\rguess a port's internal name and send a message to a port to which it
\rshouldn't have access. Port rights do not carry any location in-
\rformation. When a receive right for a port moves from task to task,
\rand even between tasks on different machines, the send rights for
\rthe port remain unchanged and continue to function.
\r<h4>Port Rights</h4>
\r<p>
\rEach task has its own space of port rights. Port rights are named with
\rpositive (unsigned) integers. For all architectures, sizeof
\r(mach_port_t) = sizeof (mach_port_name_t) = sizeof (void*) and so user
\rspace addresses may be used as port names, except for the reserved
\rvalues MACH_PORT_NULL (0) and MACH_PORT_DEAD (all 1 bits). When the
\rkernel chooses a name for a new right, however, it is free to pick any
\runused name (one which denotes no right) in the space.
\r<p>
\rThere are three basic kinds of rights: receive rights, send rights and
\rsend-once rights. A port name can name any of these types of rights,
\ror name a port-set, be a dead name, or name nothing. Dead names are
\rnot capabilities. They act as place-holders to prevent a name from
\rbeing otherwise used.
\r<p>
\rA port is destroyed, or dies, when its receive right is
\rde-allocated. When a port dies, send and send-once rights for the port
\rturn into dead names. Any messages queued at the port are destroyed,
\rwhich de-allocates the port rights and out-of-line memory in the
\rmessages.
\r<p>
\rEach send-once right held by a task has a different name. In contrast,
\rwhen a task holds send rights or a receive right for a port, the
\rrights share a single name.
\r<p>
\rTasks may hold multiple user-references for send rights. When a task
\rreceives a send right which it already holds, the kernel increments
\rthe right's user-reference count. When a task de-allocates a send
\rright, the kernel decrements its user-reference count, and the task
\ronly loses the send right when the count goes to zero.
\r<p>
\rSend-once rights always have a user reference count of one. Tasks may
\rhold multiple user references for dead names.
\rEach send-once right generated guarantees the receipt of a single
\rmessage, either a message sent to that send-once right or, if the
\rsend-once right is in any way destroyed, a send-once notification.
\r<p>
\rA message can carry port rights; the msgh_remote or msgh_local fields
\rin the message header or the disposition field in a message body
\rdescriptor specify the type of port right and how the port right is to
\rbe extracted from the caller. The values MACH_PORT_NULL and
\rMACH_PORT_DEAD are valid in place of a port right in a message body.
\r<p>
\rIn a sent message, the following mach_msg_type_name_t values denote
\rport rights:
\r<dl>
\r<dt> MACH_MSG_TYPE_MAKE_SEND
\r <dd>
\rThe message will carry a send right, but the caller must supply a
\rreceive right. The send right is created from the receive right, and the
\rreceive right's make-send count is incremented.
\r<dt> MACH_MSG_TYPE_COPY_SEND
\r <dd>
\rThe message will carry a send right, and the caller must supply a send
\rright. The user reference count for the supplied send right is not
\rchanged. The caller may also supply a dead name and the receiving
\rtask will get MACH_PORT_DEAD.
\r<dt> MACH_MSG_TYPE_MOVE_SEND
\r <dd>
\rThe message will carry a send right, and the caller must supply a send
\rright. The user reference count for the supplied send right is
\rdecremented, and the right is destroyed if the count becomes
\rzero. Unless a receive right remains, the name becomes available for
\rrecycling. The caller may also supply a dead name, which loses a user
\rreference, and the receiving task will get MACH_PORT_DEAD.
\r<dt> MACH_MSG_TYPE_MAKE_SEND_ONCE
\r<dd>
\rThe message will carry a send-once right, but the caller must supply a
\rreceive right. The send-once right is created from the receive right.
\rNote that send once rights can only be created from the receive right.
\r<dt> MACH_MSG_TYPE_MOVE_SEND_ONCE
\r <dd>
\rThe message will carry a send-once right, and the caller must supply a
\rsend-once right. The caller loses the supplied send-once right. The
\rcaller may also supply a dead name, which loses a user reference,
\rand the receiving task will get MACH_PORT_DEAD.
\r<dt> MACH_MSG_TYPE_MOVE_RECEIVE
\r <dd>
\rThe message will carry a receive right, and the caller must supply a
\rreceive right. The caller loses the supplied receive right, but
\rretains any send rights with the same name. The make-send count and
\rsequence number of the receive right are reset to zero and
\rno-more-senders notification requests are cancelled (with a
\rsend-once notification being sent to the no-more-senders notification
\rright), but the port retains other attributes like queued messages
\rand extant send and send-once rights.
\rIf a message carries a send or send-once right, and the port dies
\rwhile the message is in transit, then the receiving task will get
\rMACH_PORT_DEAD instead of a right.
\r </dl>
\r <p>
\rThe following mach_msg_type_name_t values in a received message
\rindicate that it carries port rights:
\r <dl>
\r<dt> MACH_MSG_TYPE_PORT_SEND
\r <dd>
\rThis value is an alias for MACH_MSG_TYPE_MOVE_SEND. The
\rmessage carried a send right. If the receiving task already has send and/
\ror receive rights for the port, then that name for the port will be reused.
\rOtherwise, the right will have a new, previously unused, name. If the
\rtask already has send rights, it gains a user reference for the right (un-
\rless this would cause the user-reference count to overflow). Otherwise,
\rit acquires send rights, with a user-reference count of one.
\r<dt> MACH_MSG_TYPE_PORT_SEND_ONCE
\r <dd>
\rThis value is an alias for MACH_MSG_TYPE_MOVE_SEND_ONCE. The message
\rcarried a send-once right. The right will have a new, previously
\runused, name.
\r<dt> MACH_MSG_TYPE_PORT_RECEIVE
\r <dd>
\rThis value is an alias for MACH_MSG_TYPE_MOVE_RECEIVE. The message
\rcarried a receive right. If the receiving task already has send rights
\rfor the port, then that name for the port will be reused; otherwise,
\rthe right will have a new, previously unused name.
\r </dl>
\r <p>
\rIt is also possible to send a (nearly unbounded) array of port rights
\r"out-of-line". All of the rights named by the array must be of the
\rsame type. The array is physically copied with the message body
\rproper. The array of port right (names) can be received by the
\rreceiver using the same options available for out-of-line data
\rreception described below.
\r<h4>Memory</h4>
\r <p>
\rA message can contain one or more regions of the sender's address
\rspace which are to be transferred as part of the message. The message
\rcarries a logical copy of the memory. For this "out-of-line" memory,
\rthe kernel can copy the data or use virtual memory techniques to defer
\rany actual page copies unless the sender or the receiver modifies
\rthe data, the physical pages remain shared.
\r<p>
\r The sender of the message must explicitly request an out-of-line
\rtransfer. Such a region is described as an arbitrary region of the
\rsender's address space. The sender always sees this memory as being
\rcopied to the receiver.
\r<p>
\r For each region, the sender has a de-allocate option. If the option is
\rset and the out-of-line memory region is not null, then the region is
\rimplicitly de-allocated from the sender, as if by vm_deallocate. In
\rparticular, the start address is truncated down and the end address
\rrounded up so that every page overlapped by the memory region is
\rde-allocated (thereby possibly de-allocating more memory than is
\reffectively transmitted). The use of this option effectively changes
\rthe memory copy to a memory movement. Aside from possibly optimizing
\rthe sender's use of memory, the de-allocation option allows the kernel
\rto more efficiently handle the transfer of memory.
\r <p>
\rFor each region, the sender has the choice of permitting the kernel to
\rchoose a transmission strategy or the choice of requiring physical
\rcopy:
\r <dl>
\r<dt> MACH_MSG_VIRTUAL_COPY
\r <dd>
\rIn a sent message, this flag allows the kernel to choose any mechanism
\rto transmit the data. For large regions, this involves constructing a
\rvirtual copy of the pages containing the region. The portion of the
\rfirst page preceding the data and the portion of the last page
\rfollowing the data are not copied (and will appear as zero if the
\rvirtual copy is dynamically allocated in the receiver).
\r <p>
\rIn a received message, this flag indicates that the kernel transmitted
\ra virtual copy. Access to the received memory may involve interactions
\rwith the memory manager managing the sender's original data. Integri-
\rty-conscious receivers should exercise caution when dealing with out-
\rof-line memory from un-trustworthy sources. Receivers concerned about
\rdeterministic access time should also exercise caution. The dynamic
\rallocation option guarantees that the virtual copy will not be di-
\rrectly referenced during the act of receiving the message.
\r<dt> MACH_MSG_PHYSICAL_COPY
\r <dd>
\rIn a sent message, this flag requires that the kernel construct an
\ractual copy of the memory (either into wired kernel memory or default
\rmemory managed space). There is a (fairly large) limit on the amount
\rof data that can be physically copied in a message. Port arrays always
\rassume this option when sent.
\r <p>
\rIn a received message, this flag indicates that the kernel did
\rtransmit a physical copy.
\r </dl>
\r <p>
\rThe receiver has two options for the reception of out-of-line memory
\r(or "out-of-line" port arrays): allocation and overwrite.
\rIn the absence of the MACH_RCV_OVERWRITE option, all out-of-line re-
\rgions are dynamically allocated. Allocated out-of-line memory arrives
\rsomewhere in the receiver's address space as new memory. It has the
\rsame inheritance and protection attributes as newly vm_allocate'ed
\rmemory. The receiver has the responsibility of de-allocating (with
\rvm_deallocate) the memory when it is no longer needed. If the message
\rcontains more than one region, each will be allocated its own region,
\rnot necessarily contiguously. If the sender's data was transmitted as
\ra virtual copy the allocated region will have the same data alignment
\rwithin the page; otherwise, the received data will appear starting at
\rthe beginning of a page.
\r <p>
\rIf the MACH_RCV_OVERWRITE option is set, the receiver can specify how
\reach received region is to be processed (dynamically allocated as
\rdescribed above, or written over existing memory). With this option,
\rthe contents of the receive buffer (receive_msg) are examined by the
\rkernel. The kernel scans the descriptors in the receive buffer
\r"message" to determine how to handle each out-of-line region. (Note:
\rwhereas receive_limit is the maximum size of the receive buffer,
\rreceive_msg_size is the amount filled in with this "message".) The
\rkernel uses each out-of-line data descriptor (in order) to specify
\rthe processing for each received data region in turn, each out-of-line
\rport array descriptor is used correspondingly. (Intermingled port
\rdescriptors are ignored when matching descriptors between the
\rincoming message and the receive buffer list.)
\r<p>
\rThe copy option in the
\rmatching descriptor specifies the processing:
\r <dl>
\r<dt> MACH_MSG_OVERWRITE
\r <dd>
\rThis flag indicates that the region should write over a specified
\rregion of the receiver's address space, as indicated by the address
\rand size/ count fields of the descriptor. The full range overwritten
\rmust already exist (be allocated or mapped) in the receiver's address
\rspace. Depending on the nature of the data transmission this
\roverwrite may involve virtual memory manipulations or it may involve
\ractual data copy.
\r<dt> MACH_MSG_ALLOCATE
\r <dd>
\rThis flag indicates that the region is to be dynamically allocated. No
\rother descriptor values are relevant.
\r </dl>
\r <p>
\rIf not enough descriptors appear in the receive buffer to describe all
\rreceived regions, additional regions are dynamically allocated. If
\rthe receiver specifies more descriptors than there are regions in the
\rreceived message, the additional descriptors are ignored (and do not
\rappear in the final received message).
\r <p>
\rNote that the receive buffer descriptors will be overwritten:
\rThe size fields in descriptors will be updated (when scanned, they
\rspecified the maximum sizes of regions, when received, they specify
\rthe actual sizes of received regions).
\rThe copy fields in descriptors will be updated (when scanned, they
\rspecified allocate versus overwrite, when received, they indicate
\rwhether the region was physically or virtually copied).
\rThe descriptors may appear in different positions (given intermingled
\rport descriptors).
\rDescriptors that were not used (because there were not that many
\rreceived regions) will be discarded.
\r <p>
\rNull out-of-line memory is legal. If the out-of-line region size is
\rzero, then the region's specified address is ignored. A receive
\rallocated null out-of-line memory region always has a zero address.
\rUnaligned addresses and region sizes that are not page multiples are
\rlegal. A received message can also contain regions with unaligned
\raddresses and sizes which are not multiples of the page size.
\r<h4>Message Send</h4>
\r <p>
\rThe send operation queues a message to a port. The message carries a
\rcopy of the caller's data. After the send, the caller can freely
\rmodify the message buffer or the out-of-line memory regions and the
\rmessage contents will remain unchanged.
\r <p>
\rThe message carries with it the security ID of the sender, which the
\rreceiver can request in the message trailer.
\r <p>
\rMessage delivery is reliable and sequenced. Reception of a message
\rguarantees that all messages previously sent to the port by a single
\rtask (or a single kernel) via send rights have been received and that
\rthey are received in the order in which they were sent. Messages sent
\rto send-once rights are unordered.
\r <p>
\rIf the destination port's queue is full, several things can happen. If
\rthe message is sent to a send-once right (msgh_remote_port carries a
\rsend-once right), then the kernel ignores the queue limit and delivers
\rthe message. Otherwise the caller blocks until there is room in the
\rqueue, unless the MACH_SEND_TIMEOUT option is used. If a port has
\rseveral blocked senders, then any of them may queue the next message
\rwhen space in the queue becomes available, with the proviso that a
\rblocked sender will not be indefinitely starved.
\rThese options modify MACH_SEND_MSG. If MACH_SEND_MSG is not also
\rspecified, they are ignored.
\r<dl>
\r<dt> MACH_SEND_TIMEOUT
\r <dd>
\rThe timeout argument should specify a maximum time (in milliseconds)
\rfor the call to block before giving up. If the message can't be queued
\rbefore the timeout interval elapses, then the call returns
\rMACH_SEND_TIMED_OUT. A zero timeout is legitimate.
\r<dt> MACH_SEND_INTERRUPT
\r <dd>
\rIf specified, the <strong>mach_msg</strong> call will return
\rMACH_SEND_INTERRUPTED if a software interrupt aborts the call.
\rOtherwise, the send operation will be retried.
\r<dt> MACH_SEND_TRAILER
\r <dd>
\rIf set, the kernel, instead of determining the message attributes
\ritself, will accept a formatted message trailer from the sender. The
\rsupplied trailer must be of the latest version supported by the
\rkernel, and must contain all message attributes defined by the
\rkernel. Only tasks with a security ID of KERNEL_SECURITY_ID can use
\rthis option; the intended use of this option is in support of the
\rNet Message server. The trailer must follow the message in memory as
\rit would appear in a received message. (The send_size argument to
\r<strong>mach_msg</strong> still indicates the size of the message proper, not including
\rthis trailer.)
\r </dl>
\r <p>
\rThe queueing of a message carrying receive rights may create a
\rcircular loop of receive rights and messages, which can never be
\rreceived. For example, a message carrying a receive right can be
\rsent to that receive right. This situation is not an error, but the
\rkernel will garbage-collect such loops, destroying the messages.
\rSome return codes, like MACH_SEND_TIMED_OUT, imply that the message
\rwas almost sent, but could not be queued. In these situations, the
\rkernel tries to return the message contents to the caller with a
\rpseudo-receive operation. This prevents the loss of port rights or
\rmemory which only exist in the message, for example, a receive right
\rwhich was moved into the message, or out-of-line memory sent with
\rthe de-allocate option.
\r <p>
\rThe intent of the pseudo-receive operation is to restore, as best as
\rpossible, the state prior to attempting the send. This involves
\rrestoring the port rights and out-of-line memory regions contained in
\rthe message. The port right names and out-of-line addresses in the
\rmessage send buffer are updated to reflect the new values resulting
\rfrom their effective reception. The pseudo-receive handles the des-
\rtination and reply rights as any other rights; they are not reversed
\ras is the appearance in a normal received message. Also, no trailer is
\rappended to the message. After the pseudo-receive, the message is
\rready to be resent. If the message is not resent, note that
\rout-of-line memory regions may have moved and some port rights may
\rhave changed names.
\r <p>
\rAlthough unlikely, the pseudo-receive operation may encounter resource
\rshortages. This is similar to a MACH_RCV_BODY_ERROR return code from
\ra receive operation. When this happens, the normal send return codes
\rare augmented with the MACH_MSG_IPC_SPACE, MACH_MSG_VM_SPACE,
\rMACH_MSG_IPC_KERNEL and MACH_MSG_VM_KERNEL bits to indicate the
\rnature of the resource shortage.
\r<h4>Message Receive</h4>
\r <p>
\rThe receive operation de-queues a message from a port. The receiving
\rtask acquires the port rights and out-of-line memory regions carried
\rin the message.
\rThe receive_name argument specifies a port or port set from which to
\rreceive. If a port is specified, the caller must possess the receive
\rright for the port and the port must not be a member of a port set. If
\rno message is present, the call blocks, subject to the
\rMACH_RCV_TIMEOUT option.
\r<p>
\rIf a port set is specified, the call will receive a message sent to
\rany of the member ports. It is permissible for the port set to have
\rno member ports, and ports may be added and removed while a receive
\rfrom the port set is in progress. The received message can come from
\rany of the member ports which have messages, with the proviso that a
\rmember port with messages will not be indefinitely starved. The
\rmsgh_local_port field in the received message header specifies from
\rwhich port in the port set the message came.
\r<p>
\rThe receive_limit argument specifies the size of the caller's message
\rbuffer (which must be big enough for the message header, body and
\rtrailer); the msgh_size field of the received message indicates the
\ractual size of the received message header and body. The <strong>mach_msg</strong> call
\rwill not receive a message larger than receive_limit. Messages that
\rare too large are destroyed, unless the MACH_RCV_LARGE option is used.
\rFollowing the received data, at the next natural boundary, is a
\rmessage trailer. The msgh_size field of the received message does not
\rinclude the length of this trailer; the trailer's length is given by
\rthe msgh_trailer_size field within the trailer. The receiver of a
\rmessage is given a choice as to what trailer format is desired, and,
\rwithin that format, which of the leading trailer attributes are
\rdesired (that is, to get trailer element three, the receiver must also
\raccept elements one and two). For any given trailer format (of which
\rthere is currently only one), the trailer is compatibly extended by
\radding additional elements to the end.
\r<p>
\rReceived messages are stamped (in the trailer) with a sequence number,
\rtaken from the port from which the message was received. (Messages
\rreceived from a port set are stamped with a sequence number from the
\rappropriate member port.) Newly created ports start with a zero
\rsequence number, and the sequence number is reset to zero whenever the
\rport's receive right moves between tasks. When a message is de-queued
\rfrom the port, it is stamped with the port's sequence number and the
\rport's sequence number is then incremented. (Note that this occurs
\rwhether or not the receiver requests the sequence number in the trail-
\rer.) The de-queue and increment operations are atomic, so that
\rmultiple threads receiving messages from a port can use the msgh_seqno
\rfield to reconstruct the original order of the messages.
\r<p>
\rThe destination and reply ports are reversed in a received message
\rheader. The msgh_local_port field carries the name of the destination
\rport, from which the message was received, and the msgh_remote_port
\rfield carries the reply port right. The bits in msgh_bits are also
\rreversed. The MACH_MSGH_BITS_LOCAL bits have a value of
\rMACH_MSG_TYPE_PORT_SEND_ONCE or MACH_MSG_TYPE_PORT_SEND depending on
\rthe type of right to which the message was sent. The
\rMACH_MSGH_BITS_REMOTE bits describe the reply port right.
\r<p>
\rA received message can contain port rights and out-of-line memory. The
\rmsgh_local_port field does not carry a port right; the act of
\rreceiving the message consumes the send or send-once right for the
\rdestination port. The msgh_remote_port field does carry a port right,
\rand the message can carry additional port rights and memory if the
\rMACH_MSGH_BITS_COMPLEX bit is set. Received port rights and memory
\rshould be consumed or de-allocated in some fashion.
\rIn almost all cases, msgh_local_port will specify the name of a
\rreceive right, either receive_name, or, if receive_name is a port
\rset, a member of receive_name.
\r<p>
\rIf other threads are concurrently
\rmanipulating the receive right, the situation is more complicated. If
\rthe receive right is renamed during the call, then msgh_local_port
\rspecifies the right's new name. If the caller loses the receive right
\rafter the message was de-queued from it, then <strong>mach_msg</strong> will proceed
\rinstead of returning MACH_RCV_PORT_DIED. If the receive right was
\rdestroyed, then msgh_local_port specifies MACH_PORT_DEAD. If the
\rreceive right still exists, but isn't held by the caller, then
\rmsgh_local_port specifies MACH_PORT_NULL.
\r<p>
\rThe following options modify MACH_RCV_MSG. If MACH_RCV_MSG is not also
\rspecified, they are ignored.
\r<dl>
\r<dt> MACH_RCV_TIMEOUT
\r <dd>
\rThe timeout argument should specify a maximum time (in milliseconds)
\rfor the call to block before giving up. If no message arrives before
\rthe timeout interval elapses, then the call returns
\rMACH_RCV_TIMED_OUT. A zero timeout is legitimate.
\r<dt> MACH_RCV_NOTIFY
\r <dd>
\rThe notify argument should specify a receive right for a notify
\rport. If receiving the reply port creates a new port right in the
\rcaller, then the notify port is used to request a dead-name
\rnotification for the new port right.
\r<dt> MACH_RCV_INTERRUPT
\r <dd>
\rIf specified, the <strong>mach_msg</strong> call will return MACH_RCV_INTERRUPTED if a
\rsoftware interrupt aborts the call. Otherwise, the receive operation
\rwill be retried.
\r<dt> MACH_RCV_OVERWRITE
\r <dd>
\rIf specified, the message buffer specified by receive_msg (or msg), of
\rlength receive_msg_size, will be scanned for out-of-line descriptors to
\rspecify the processing to be done when receiving out-of-line regions.
\rThis option is only allowed for <strong>mach_msg_overwrite</strong>.
\r<dt> MACH_RCV_LARGE
\r <dd>
\rIf the message is larger than receive_limit or an out-of-line region
\ris larger than the size allowed by a corresponding receive descriptor
\r(MACH_RCV_OVERWRITE), the message remains queued instead of being
\rdestroyed. If the header, trailer and body would not fit into
\rreceive_limit, only the message header (mach_msg_header) and trailer
\rheader (mach_msg_trailer) are returned with the actual size of the
\rmessage returned in the msgh_size field, the actual size of the
\rtrailer returned in the msgh_trailer_size field and an error return
\rvalue of MACH_RCV_TOO_LARGE. If receive_limit is sufficient but an
\rout-of-line descriptor is not, the message header, trailer and body
\rare received, with out-of-line descriptors set to indicate the
\rnature and size of the out-of-line regions, with an error return of
\rMACH_RCV_SCATTER_SMALL. No out-of-line regions or port rights
\r(including the reply right) will be received. If this option is not
\rspecified, messages too large will be de-queued and then destroyed;
\rthe caller receives the message header, with all fields correct,
\rincluding the destination port but excepting the reply port, which is
\rMACH_PORT_NULL and an empty (no additional element) message trailer.
\r<dt> MACH_RCV_TRAILER_TYPE(value)
\r <dd>
\rThis macro encodes the type of trailer the kernel must return with the
\rmessage. If the kernel does not recognize this type, it returns
\rMACH_RCV_INVALID_TRAILER. Currently, only MACH_MSG_TRAILER_FORMAT_0 is
\rsupported.
\r<dt> MACH_RCV_TRAILER_ELEMENTS(value)
\r <dd>
\rThis macro encodes the number of trailer elements desired. If the ker-
\rnel does not support this number for the requested trailer type, the
\rkernel returns MACH_RCV_INVALID_TRAILER. Zero is a legal value.
\r </dl>
\r <p>
\r The following trailer elements are supported:
\r <dl>
\r<dt> MACH_RCV_TRAILER_SEQNO
\r <dd>
\rReturns the sequence number of the message relative to its port. This
\rvalue is of type mach_port_seqno_t.
\r<dt> MACH_RCV_TRAILER_SENDER
\r <dd>
\rReturns the security ID of the task that sent the message. This value
\ris of type security_id_t.
\r </dl>
\r <p>
\rIf a resource shortage prevents the reception of a port right, the
\rport right is destroyed and the caller sees the name
\rMACH_PORT_NULL. If a resource shortage prevents the reception of an
\rout-of-line memory region, the region is destroyed and the caller sees
\ra zero address. In addition, the corresponding element in the size
\rarray is set to zero. A task never receives port rights or memory for
\rwhich it is not told.
\r <p>
\rThe MACH_RCV_HEADER_ERROR return code indicates a resource shortage
\rin the reception of the message header. The reply port and all port
\rrights and memory in the message are destroyed. The caller receives
\rthe message header with all fields correct except for the reply
\rport.
\r <p>
\rThe MACH_RCV_BODY_ERROR return code indicates a resource shortage in
\rthe reception of the message body. The message header, including the
\rreply port, is correct. The kernel attempts to transfer all port
\rrights and memory regions in the body, and only destroys those that
\rcan't be transferred.
\r<h4>Atomicity</h4>
\r <p>
\rThe <strong>mach_msg</strong> call handles port rights in the message header
\ratomically. Out-of-line memory and port rights in the message body do
\rnot enjoy this atomicity guarantee. These elements may be processed
\rfront-to-back, back-to-front, in some random order, or even
\ratomically.
\r <p>
\rFor example, consider sending a message with the destination port
\rspecified as MACH_MSG_TYPE_MOVE_SEND and the reply port specified as
\rMACH_MSG_TYPE_COPY_SEND. The same send right, with one user-refer-
\rence, is supplied for both the msgh_remote_port and msgh_local_port
\rfields. Because <strong>mach_msg</strong> processes the port rights atomically, this
\rsucceeds. If msgh_remote_port were processed before msgh_local_port,
\rthen <strong>mach_msg</strong> would return MACH_SEND_INVALID_REPLY in this situation.
\r <p>
\rOn the other hand, suppose the destination and reply port are both
\rspecified as MACH_MSG_TYPE_MOVE_SEND, and again the same send right
\rwith one user-reference is supplied for both. Now the send operation
\rfails, but because it processes the rights atomically, <strong>mach_msg</strong> can
\rreturn either MACH_SEND_INVALID_DEST or MACH_SEND_INVALID_REPLY.
\r<p>
\rFor example, consider receiving a message at the same time another
\rthread is deallocating the destination receive right. Suppose the
\rreply port field carries a send right for the destination port. If the
\rde-allocation happens before the dequeuing, the receiver gets
\rMACH_RCV_PORT_DIED. If the de-allocation happens after the receive,
\rthe msgh_local_port and the msgh_remote_port fields both specify
\rthe same right, which becomes a dead name when the receive right is
\rde-allocated. If the de-allocation happens between the de-queue and
\rthe receive, the msgh_local_port and msgh_remote_port fields both
\rspecify MACH_PORT_DEAD. Because the rights are processed atomically,
\rit is not possible for just one of the two fields to hold
\rMACH_PORT_DEAD.
\r<p>
\rThe MACH_RCV_NOTIFY option provides a more likely example. Suppose a
\rmessage carrying a send-once right reply port is received with
\rMACH_RCV_NOTIFY at the same time the reply port is destroyed. If the
\rreply port is destroyed first, then msgh_remote_port specifies
\rMACH_PORT_DEAD and the kernel does not generate a dead-name
\rnotification. If the reply port is destroyed after it is received,
\rthen msgh_remote_port specifies a dead name for which the kernel
\rgenerates a dead-name notification. Either the reply port is dead on
\rarrival or notification is requested.
\r<h4>Implementation</h4>
\r<p>
\r<strong>mach_msg</strong> and <strong>mach_msg_overwrite</strong> are wrappers for a system call. They
\rhave the responsibility for repeating the interrupted system call.
\r<h3>CAUTIONS</h3>
\r<p>
\rIf MACH_RCV_TIMEOUT is used without MACH_RCV_INTERRUPT, then the
\rtimeout duration might not be accurate. When the call is interrupted
\rand automatically retried, the original timeout is used. If
\rinterrupts occur frequently enough, the timeout interval might never
\rexpire. MACH_SEND_TIMEOUT without MACH_SEND_INTERRUPT suffers from the
\rsame problem.
\r<h3>RETURN VALUES</h3>
\r<p>
\rThe send operation can generate the following return codes. These
\rreturn codes imply that the call did nothing:
\r<dl>
\r<p>
\r<dt> MACH_SEND_MSG_TOO_SMALL
\r <dd>
\rThe specified send_size was smaller than the minimum size for a
\rmessage.
\r<p>
\r<dt> MACH_SEND_NO_BUFFER
\r <dd>
\rA resource shortage prevented the kernel from allocating a message
\rbuffer.
\r<p>
\r<dt> MACH_SEND_INVALID_DATA
\r <dd>
\rThe supplied message buffer was not readable.
\r<p>
\r<dt> MACH_SEND_INVALID_HEADER
\r <dd>
\rThe msgh_bits value was invalid.
\r<p>
\r<dt> MACH_SEND_INVALID_DEST
\r <dd>
\rThe msgh_remote_port value was invalid.
\r<p>
\r<dt> MACH_SEND_INVALID_NOTIFY
\r <dd>
\rWhen using MACH_SEND_CANCEL, the notify argument did not
\rdenote a valid receive right.
\r<p>
\r<dt> MACH_SEND_INVALID_REPLY
\r <dd>
\rThe msgh_local_port value was invalid.
\r<p>
\r<dt> MACH_SEND_INVALID_TRAILER
\r <dd>
\rThe trailer to be sent does not correspond to the current kernel format,
\ror the sending task does not have the privilege to supply the message
\rattributes.
\r </dl>
\r <p>
\rThese return codes imply that some or all of the message was destroyed:
\r <dl>
\r<p>
\r<dt> MACH_SEND_INVALID_MEMORY
\r <dd>
\rThe message body specified out-of-line data that was not readable.
\r<p>
\r<dt> MACH_SEND_INVALID_RIGHT
\r <dd>
\rThe message body specified a port right which the caller didn't possess.
\r<p>
\r<dt> MACH_SEND_INVALID_TYPE
\r <dd>
\rA kernel processed descriptor was invalid.
\r<p>
\r<dt> MACH_SEND_MSG_TOO_SMALL
\r <dd>
\rThe last data item in the message ran over the end of the message.
\r </dl>
\r <p>
\rThese return codes imply that the message was returned to the caller with a
\rpseudo-receive operation:
\r <dl>
\r<p>
\r<dt> MACH_SEND_TIMED_OUT
\r <dd>
\rThe timeout interval expired.
\r<p>
\r<dt> MACH_SEND_INTERRUPTED
\r <dd>
\rA software interrupt occurred.
\r </dl>
\r <p>
\rThis return code implies that the message was queued:
\r <dl>
\r<p>
\r<dt> MACH_MSG_SUCCESS
\r <dd>
\rThe message was queued.
\r </dl>
\r <p>
\rThe receive operation can generate the following return codes. These return
\rcodes imply that the call did not de-queue a message:
\r <dl>
\r<p>
\r<dt> MACH_RCV_INVALID_NAME
\r <dd>
\rThe specified receive_name was invalid.
\r<p>
\r<dt> MACH_RCV_IN_SET
\r <dd>
\rThe specified port was a member of a port set.
\r<p>
\r<dt> MACH_RCV_TIMED_OUT
\r <dd>
\rThe timeout interval expired.
\r<p>
\r<dt> MACH_RCV_INTERRUPTED
\r <dd>
\rA software interrupt occurred.
\r<p>
\r<dt> MACH_RCV_PORT_DIED
\r <dd>
\rThe caller lost the rights specified by receive_name.
\r<p>
\r<dt> MACH_RCV_PORT_CHANGED
\r <dd>
\rreceive_name specified a receive right which was moved into a port set
\rduring the call.
\r<p>
\r<dt> MACH_RCV_TOO_LARGE
\r <dd>
\rWhen using MACH_RCV_LARGE, the message was larger than
\rreceive_limit. The message is left queued, and its actual size is
\rreturned in the message header/message body.
\r<p>
\r<dt> MACH_RCV_SCATTER_SMALL
\r <dd>
\rWhen using MACH_RCV_LARGE with MACH_RCV_OVERWRITE, one or more scatter
\rlist descriptors specified an overwrite region smaller than the
\rcorresponding incoming region. The message is left queued, and the
\rproper descriptors are returned in the message header/message body.
\r<p>
\r<dt> MACH_RCV_INVALID_TRAILER
\r <dd>
\rThe trailer type desired, or the number of trailer elements desired, is
\rnot supported by the kernel.
\r </dl>
\r <p>
\rThese return codes imply that a message was de-queued and destroyed:
\r <dl>
\r<p>
\r<dt> MACH_RCV_HEADER_ERROR
\r <dd>
\rA resource shortage prevented the reception of the port rights in the
\rmessage header.
\r<p>
\r<dt> MACH_RCV_INVALID_NOTIFY
\r <dd>
\rWhen using MACH_RCV_NOTIFY, the notify argument did not denote a
\rvalid receive right.
\r<p>
\r<dt> MACH_RCV_INVALID_DATA
\r <dd>
\rThe specified message buffer was not writable.
\r<p>
\r<dt> MACH_RCV_TOO_LARGE
\r <dd>
\rWhen not using MACH_RCV_LARGE, a message larger than
\rreceive_limit was de-queued and destroyed.
\r<p>
\r<dt> MACH_RCV_SCATTER_SMALL
\r <dd>
\rWhen not using MACH_RCV_LARGE with MACH_RCV_OVERWRITE, one or more
\rscatter list descriptors specified an overwrite region smaller than
\rthe corresponding incoming region. The message was de-queued and
\rdestroyed.
\r<p>
\r<dt> MACH_RCV_OVERWRITE_ERROR
\r <dd>
\rA region specified by a receive overwrite descriptor
\r(MACH_RCV_OVERWRITE) was not allocated or could not be written.
\r<p>
\r<dt> MACH_RCV_INVALID_TYPE
\r <dd>
\rWhen using MACH_RCV_OVERWRITE, one or more scatter list descriptors
\rdid not have the type matching the corresponding incoming message
\rdescriptor or had an invalid copy (disposition) field.
\r<p>
\r<dt> MACH_RCV_LIMITS
\r <dd>
\rThe combined size of all out-of-line memory regions or the total num-
\rber of port rights in the message exceeds the limit set for the port.
\rThese return codes imply that a message was received:
\r<p>
\r<dt> MACH_RCV_BODY_ERROR
\r <dd>
\rA resource shortage prevented the reception of a port right or out-of-
\rline memory region in the message body.
\r<p>
\r<dt> MACH_MSG_SUCCESS
\r <dd>
\rA message was received.
\r </dl>
\r <p>
\rResource shortages can occur after a message is de-queued, while
\rtransferring port rights and out-of-line memory regions to the
\rreceiving task. The <strong>mach_msg</strong> call returns MACH_RCV_HEADER_ERROR or
\rMACH_RCV_BODY_ERROR in this situation. These return codes always carry
\r extra bits (bitwise-or'ed) that indicate the nature of the resource
\rshortage:
\r <dl>
\r<p>
\r<dt> MACH_MSG_IPC_SPACE
\r <dd>
\rThere was no room in the task's IPC name space for another port name.
\r<p>
\r<dt> MACH_MSG_VM_SPACE
\r <dd>
\rThere was no room in the task's VM address space for an out-of-line
\rmemory region.
\r<p>
\r<dt> MACH_MSG_IPC_KERNEL
\r <dd>
\rA kernel resource shortage prevented the reception of a port right.
\r<p>
\r<dt> MACH_MSG_VM_KERNEL
\r <dd>
\rA kernel resource shortage prevented the reception of an out-of-line
\rmemory region.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_allocate.html"><strong>vm_allocate</strong></a>,
\r<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>,
\r<a href="vm_write.html"><strong>vm_write</strong></a>,
\r<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>,
\r<p>
\rData Structures:
\rmach_msg_header.
\r\ No newline at end of file
+<h2>mach_msg</h2>
+<hr>
+<p>
+<strong>System Trap</strong> / <strong>Function</strong> - Send and/or receive a message from the target port.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>mach_msg_return_t mach_msg</strong>
+ <strong>(mach_msg_header_t</strong> <var>msg</var>,
+ <strong>mach_msg_option_t</strong> <var>option</var>,
+ <strong>mach_msg_size_t</strong> <var>send_size</var>,
+ <strong>mach_msg_size_t</strong> <var>receive_limit</var>,
+ <strong>mach_port_t</strong> <var>receive_name</var>,
+ <strong>mach_msg_timeout_t</strong> <var>timeout</var>,
+ <strong>mach_port_t</strong> <var>notify</var><strong>);</strong>
+
+<strong>mach_msg_return_t mach_msg_overwrite</strong>
+ <strong>(mach_msg_header_t*</strong> <var>send_msg</var>,
+ <strong>mach_msg_option_t</strong> <var>option</var>,
+ <strong>mach_msg_size_t</strong> <var>send_size</var>,
+ <strong>mach_msg_size_t</strong> <var>receive_limit</var>,
+ <strong>mach_port_t</strong> <var>receive_name</var>,
+ <strong>mach_msg_timeout_t</strong> <var>timeout</var>,
+ <strong>mach_port_t</strong> <var>notify</var>,
+ <strong>mach_msg_header_t</strong> <var>*receive_msg</var>,
+ <strong>mach_msg_size_t</strong> <var>receive_msg_size</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>msg</var>
+<dd>
+[pointer to in/out structure containing random and reply rights] A
+message buffer used by <strong>mach_msg</strong> both for send and receive. This must
+be naturally aligned.
+<p>
+<dt> <var>send_msg</var>
+<dd>
+[pointer to in structure containing random and reply rights] The mes-
+sage buffer to be sent. This must be naturally aligned.
+<p>
+<dt> <var>option</var>
+<dd>
+[in scalar] Message options are bit values, combined with bitwise-or.
+One or both of MACH_SEND_MSG and MACH_RCV_MSG should be used. Other
+options act as modifiers.
+<p>
+<dt> <var>send_size</var>
+<dd>
+[in scalar] When sending a message, specifies the size of the message
+buffer to be sent (the size of the header and body) in
+bytes. Otherwise zero should be supplied.
+<p>
+<dt> <var>receive_limit</var>
+<dd>
+[in scalar] When receiving a message, specifies the maximum size of
+the msg or receive_msg buffer in bytes. Otherwise zero should be sup-
+plied.
+<p>
+<dt> <var>receive_name</var>
+<dd>
+[in random right] When receiving a message, specifies the port or port
+set. Otherwise MACH_PORT_NULL should be supplied.
+<p>
+<dt> <var>timeout</var>
+<dd>
+[in scalar] When using the MACH_SEND_TIMEOUT and MACH_RCV_TIMEOUT
+options, specifies the time in milliseconds to wait before giving
+up. Otherwise MACH_MSG_TIMEOUT_NONE should be supplied.
+<p>
+<dt> <var>notify</var>
+<dd>
+[in notify receive right] When using the MACH_SEND_CANCEL and
+MACH_RCV_NOTIFY options, specifies the port used for the
+notification. Otherwise MACH_PORT_NULL should be supplied.
+<p>
+<dt> <var>receive_msg</var>
+<dd>
+[pointer to in/out structure] A message buffer into which a message
+(header and body) will be received. This must be naturally aligned. By
+default (<strong>mach_msg</strong>), any received message will overwrite the send
+message buffer. This buffer is in/out only if the MACH_RCV_OVERWRITE
+option is used; otherwise this buffer is out only.
+<p>
+<dt> <var>receive_msg_size</var>
+<dd>
+[in scalar] When using the MACH_RCV_OVERWRITE option, specifies the
+size (in bytes) of the receive "message" that is to be used by
+<strong>mach_msg</strong> to indicate the disposition of received out-of-line regions.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_msg</strong> system call sends and receives Mach messages. Mach
+messages contain data, which can include port rights and addresses of
+large regions of memory. <strong>mach_msg</strong> uses the same buffer for sending and
+receiving a message; the other calls permit separate send and receive
+buffers (although they may be specified to be the same).
+If the option argument contains MACH_SEND_MSG, the call sends a
+message. The <var>send_size</var> argument specifies the size of the message
+buffer (header and body) to send. The msgh_remote_port field of the
+message header specifies the destination of the message.
+If the option argument contains MACH_RCV_MSG, it receives a
+message. The receive_limit argument specifies the size of a buffer
+that will receive the message; messages that are larger are not
+received. The receive_name argument specifies the port or port set
+from which to receive.
+<p>
+If the option argument contains both MACH_SEND_MSG and MACH_RCV_MSG,
+then <strong>mach_msg</strong> does both send and receive operations (in that
+order). If the send operation encounters an error (any return code
+other than MACH_MSG_SUCCESS), the call returns immediately
+without attempting the receive operation. Semantically the combined
+call is equivalent to separate send and receive calls, but it saves
+a system call and enables other internal optimizations.
+
+If the option argument specifies neither MACH_SEND_MSG nor
+MACH_RCV_MSG, <strong>mach_msg</strong> does nothing.
+Some options, like MACH_SEND_TIMEOUT and MACH_RCV_TIMEOUT, share a
+supporting argument. If these options are used together, they make
+independent use of the supporting argument's value.
+<h3>NOTES</h3>
+<p>
+The Mach kernel provides message-oriented, capability-based
+inter-process communication. The inter-process communication (IPC)
+primitives efficiently support many different styles of interaction,
+including remote procedure calls, object-oriented distributed
+programming, streaming of data, and sending very large amounts of
+data.
+<h4>Major Concepts</h4>
+<p>
+The IPC primitives operate on three abstractions: messages, ports, and
+port sets. User tasks access all other kernel services and
+abstractions via the IPC primitives.
+<p>
+The message primitives let tasks send and receive messages. Tasks send
+messages to ports. Messages sent to a port are delivered reliably
+(messages may not be lost) and are received in the order in which they
+were sent via send rights by a given sending task (or a given
+kernel). (Messages sent to send-once rights are unordered.)
+<p>
+Messages
+contain a fixed-size header and a variable-sized message body
+containing kernel and user data, and a variable-size trailer of kernel
+appended message attributes. The header describes the destination
+and the size of the message (header plus body). The message body
+contains descriptions of additional port rights to be transmitted,
+descriptions of "out-of-line" memory regions to be sent and a
+variable amount of user data, which typically includes type conversion
+information. The out-of-line memory regions (including out-of-line
+port arrays) are (typically) disjoint from the message body.
+The IPC implementation makes use of the VM system to efficiently
+transfer large amounts of data. The message can contain the addresses
+of regions of the sender's address space which should be transferred
+as part of the message.
+<p>
+When a task receives a message containing
+such out-of-line regions of data, the data can appear in unused
+portions or overwrite an existing portion of the receiver's address
+space (depending on the requested receive options). Under favorable
+circumstances, the transmission of out-of-line data is optimized so
+that sender and receiver share the physical pages of data
+copy-on-write, and no actual data copy occurs unless the pages are
+written. Regions of memory up to 4 gigabytes may be sent in this
+manner.
+<p>
+Ports hold a queue of messages. Tasks operate on a port to send and
+receive messages by exercising capabilities (rights) for the
+port. Multiple tasks can hold send rights for a port.
+Tasks can also
+hold send-once rights, which grant the ability to send a single
+message. Only one task can hold the receive capability (receive
+right) for a port.
+<p>
+Port rights can be transferred between tasks via
+messages. The sender of a message can specify in the message that the
+message contains a port right. If a message contains a receive right
+for a port, the receive right is removed from the sender of the
+message and transferred to the receiver of the
+message. While the receive right is in transit, tasks holding send
+rights can still send messages to the port, and they are queued until
+a task acquires the receive right and uses it to receive the messages.
+<p>
+Tasks can receive messages from ports and port sets. The port set
+abstraction allows a single thread to wait for a message from any of
+several ports. Tasks manipulate port sets with a port set name,
+which is taken from the same name space as are the port rights. The
+port-set name may not be transferred in a message. A port set holds
+receive rights, and a receive operation on a port set blocks waiting
+for a message sent to any of the constituent ports. A port may not be-
+long to more than one port set, and if a port is a member of a port
+set, the holder of the receive right can't receive directly from the
+port.
+<p>
+Port rights are a secure, location-independent way of naming
+ports. The port queue is a protected data structure, only accessible
+via the kernel's exported message primitives. Rights are also
+protected by the kernel; there is no way for a malicious user task to
+guess a port's internal name and send a message to a port to which it
+shouldn't have access. Port rights do not carry any location in-
+formation. When a receive right for a port moves from task to task,
+and even between tasks on different machines, the send rights for
+the port remain unchanged and continue to function.
+<h4>Port Rights</h4>
+<p>
+Each task has its own space of port rights. Port rights are named with
+positive (unsigned) integers. For all architectures, sizeof
+(mach_port_t) = sizeof (mach_port_name_t) = sizeof (void*) and so user
+space addresses may be used as port names, except for the reserved
+values MACH_PORT_NULL (0) and MACH_PORT_DEAD (all 1 bits). When the
+kernel chooses a name for a new right, however, it is free to pick any
+unused name (one which denotes no right) in the space.
+<p>
+There are three basic kinds of rights: receive rights, send rights and
+send-once rights. A port name can name any of these types of rights,
+or name a port-set, be a dead name, or name nothing. Dead names are
+not capabilities. They act as place-holders to prevent a name from
+being otherwise used.
+<p>
+A port is destroyed, or dies, when its receive right is
+de-allocated. When a port dies, send and send-once rights for the port
+turn into dead names. Any messages queued at the port are destroyed,
+which de-allocates the port rights and out-of-line memory in the
+messages.
+<p>
+Each send-once right held by a task has a different name. In contrast,
+when a task holds send rights or a receive right for a port, the
+rights share a single name.
+<p>
+Tasks may hold multiple user-references for send rights. When a task
+receives a send right which it already holds, the kernel increments
+the right's user-reference count. When a task de-allocates a send
+right, the kernel decrements its user-reference count, and the task
+only loses the send right when the count goes to zero.
+<p>
+Send-once rights always have a user reference count of one. Tasks may
+hold multiple user references for dead names.
+Each send-once right generated guarantees the receipt of a single
+message, either a message sent to that send-once right or, if the
+send-once right is in any way destroyed, a send-once notification.
+<p>
+A message can carry port rights; the msgh_remote or msgh_local fields
+in the message header or the disposition field in a message body
+descriptor specify the type of port right and how the port right is to
+be extracted from the caller. The values MACH_PORT_NULL and
+MACH_PORT_DEAD are valid in place of a port right in a message body.
+<p>
+In a sent message, the following mach_msg_type_name_t values denote
+port rights:
+<dl>
+<dt> MACH_MSG_TYPE_MAKE_SEND
+ <dd>
+The message will carry a send right, but the caller must supply a
+receive right. The send right is created from the receive right, and the
+receive right's make-send count is incremented.
+<dt> MACH_MSG_TYPE_COPY_SEND
+ <dd>
+The message will carry a send right, and the caller must supply a send
+right. The user reference count for the supplied send right is not
+changed. The caller may also supply a dead name and the receiving
+task will get MACH_PORT_DEAD.
+<dt> MACH_MSG_TYPE_MOVE_SEND
+ <dd>
+The message will carry a send right, and the caller must supply a send
+right. The user reference count for the supplied send right is
+decremented, and the right is destroyed if the count becomes
+zero. Unless a receive right remains, the name becomes available for
+recycling. The caller may also supply a dead name, which loses a user
+reference, and the receiving task will get MACH_PORT_DEAD.
+<dt> MACH_MSG_TYPE_MAKE_SEND_ONCE
+<dd>
+The message will carry a send-once right, but the caller must supply a
+receive right. The send-once right is created from the receive right.
+Note that send once rights can only be created from the receive right.
+<dt> MACH_MSG_TYPE_MOVE_SEND_ONCE
+ <dd>
+The message will carry a send-once right, and the caller must supply a
+send-once right. The caller loses the supplied send-once right. The
+caller may also supply a dead name, which loses a user reference,
+and the receiving task will get MACH_PORT_DEAD.
+<dt> MACH_MSG_TYPE_MOVE_RECEIVE
+ <dd>
+The message will carry a receive right, and the caller must supply a
+receive right. The caller loses the supplied receive right, but
+retains any send rights with the same name. The make-send count and
+sequence number of the receive right are reset to zero and
+no-more-senders notification requests are cancelled (with a
+send-once notification being sent to the no-more-senders notification
+right), but the port retains other attributes like queued messages
+and extant send and send-once rights.
+If a message carries a send or send-once right, and the port dies
+while the message is in transit, then the receiving task will get
+MACH_PORT_DEAD instead of a right.
+ </dl>
+ <p>
+The following mach_msg_type_name_t values in a received message
+indicate that it carries port rights:
+ <dl>
+<dt> MACH_MSG_TYPE_PORT_SEND
+ <dd>
+This value is an alias for MACH_MSG_TYPE_MOVE_SEND. The
+message carried a send right. If the receiving task already has send and/
+or receive rights for the port, then that name for the port will be reused.
+Otherwise, the right will have a new, previously unused, name. If the
+task already has send rights, it gains a user reference for the right (un-
+less this would cause the user-reference count to overflow). Otherwise,
+it acquires send rights, with a user-reference count of one.
+<dt> MACH_MSG_TYPE_PORT_SEND_ONCE
+ <dd>
+This value is an alias for MACH_MSG_TYPE_MOVE_SEND_ONCE. The message
+carried a send-once right. The right will have a new, previously
+unused, name.
+<dt> MACH_MSG_TYPE_PORT_RECEIVE
+ <dd>
+This value is an alias for MACH_MSG_TYPE_MOVE_RECEIVE. The message
+carried a receive right. If the receiving task already has send rights
+for the port, then that name for the port will be reused; otherwise,
+the right will have a new, previously unused name.
+ </dl>
+ <p>
+It is also possible to send a (nearly unbounded) array of port rights
+"out-of-line". All of the rights named by the array must be of the
+same type. The array is physically copied with the message body
+proper. The array of port right (names) can be received by the
+receiver using the same options available for out-of-line data
+reception described below.
+<h4>Memory</h4>
+ <p>
+A message can contain one or more regions of the sender's address
+space which are to be transferred as part of the message. The message
+carries a logical copy of the memory. For this "out-of-line" memory,
+the kernel can copy the data or use virtual memory techniques to defer
+any actual page copies unless the sender or the receiver modifies
+the data, the physical pages remain shared.
+<p>
+ The sender of the message must explicitly request an out-of-line
+transfer. Such a region is described as an arbitrary region of the
+sender's address space. The sender always sees this memory as being
+copied to the receiver.
+<p>
+ For each region, the sender has a de-allocate option. If the option is
+set and the out-of-line memory region is not null, then the region is
+implicitly de-allocated from the sender, as if by vm_deallocate. In
+particular, the start address is truncated down and the end address
+rounded up so that every page overlapped by the memory region is
+de-allocated (thereby possibly de-allocating more memory than is
+effectively transmitted). The use of this option effectively changes
+the memory copy to a memory movement. Aside from possibly optimizing
+the sender's use of memory, the de-allocation option allows the kernel
+to more efficiently handle the transfer of memory.
+ <p>
+For each region, the sender has the choice of permitting the kernel to
+choose a transmission strategy or the choice of requiring physical
+copy:
+ <dl>
+<dt> MACH_MSG_VIRTUAL_COPY
+ <dd>
+In a sent message, this flag allows the kernel to choose any mechanism
+to transmit the data. For large regions, this involves constructing a
+virtual copy of the pages containing the region. The portion of the
+first page preceding the data and the portion of the last page
+following the data are not copied (and will appear as zero if the
+virtual copy is dynamically allocated in the receiver).
+ <p>
+In a received message, this flag indicates that the kernel transmitted
+a virtual copy. Access to the received memory may involve interactions
+with the memory manager managing the sender's original data. Integri-
+ty-conscious receivers should exercise caution when dealing with out-
+of-line memory from un-trustworthy sources. Receivers concerned about
+deterministic access time should also exercise caution. The dynamic
+allocation option guarantees that the virtual copy will not be di-
+rectly referenced during the act of receiving the message.
+<dt> MACH_MSG_PHYSICAL_COPY
+ <dd>
+In a sent message, this flag requires that the kernel construct an
+actual copy of the memory (either into wired kernel memory or default
+memory managed space). There is a (fairly large) limit on the amount
+of data that can be physically copied in a message. Port arrays always
+assume this option when sent.
+ <p>
+In a received message, this flag indicates that the kernel did
+transmit a physical copy.
+ </dl>
+ <p>
+The receiver has two options for the reception of out-of-line memory
+(or "out-of-line" port arrays): allocation and overwrite.
+In the absence of the MACH_RCV_OVERWRITE option, all out-of-line re-
+gions are dynamically allocated. Allocated out-of-line memory arrives
+somewhere in the receiver's address space as new memory. It has the
+same inheritance and protection attributes as newly vm_allocate'ed
+memory. The receiver has the responsibility of de-allocating (with
+vm_deallocate) the memory when it is no longer needed. If the message
+contains more than one region, each will be allocated its own region,
+not necessarily contiguously. If the sender's data was transmitted as
+a virtual copy the allocated region will have the same data alignment
+within the page; otherwise, the received data will appear starting at
+the beginning of a page.
+ <p>
+If the MACH_RCV_OVERWRITE option is set, the receiver can specify how
+each received region is to be processed (dynamically allocated as
+described above, or written over existing memory). With this option,
+the contents of the receive buffer (receive_msg) are examined by the
+kernel. The kernel scans the descriptors in the receive buffer
+"message" to determine how to handle each out-of-line region. (Note:
+whereas receive_limit is the maximum size of the receive buffer,
+receive_msg_size is the amount filled in with this "message".) The
+kernel uses each out-of-line data descriptor (in order) to specify
+the processing for each received data region in turn, each out-of-line
+port array descriptor is used correspondingly. (Intermingled port
+descriptors are ignored when matching descriptors between the
+incoming message and the receive buffer list.)
+<p>
+The copy option in the
+matching descriptor specifies the processing:
+ <dl>
+<dt> MACH_MSG_OVERWRITE
+ <dd>
+This flag indicates that the region should write over a specified
+region of the receiver's address space, as indicated by the address
+and size/ count fields of the descriptor. The full range overwritten
+must already exist (be allocated or mapped) in the receiver's address
+space. Depending on the nature of the data transmission this
+overwrite may involve virtual memory manipulations or it may involve
+actual data copy.
+<dt> MACH_MSG_ALLOCATE
+ <dd>
+This flag indicates that the region is to be dynamically allocated. No
+other descriptor values are relevant.
+ </dl>
+ <p>
+If not enough descriptors appear in the receive buffer to describe all
+received regions, additional regions are dynamically allocated. If
+the receiver specifies more descriptors than there are regions in the
+received message, the additional descriptors are ignored (and do not
+appear in the final received message).
+ <p>
+Note that the receive buffer descriptors will be overwritten:
+The size fields in descriptors will be updated (when scanned, they
+specified the maximum sizes of regions, when received, they specify
+the actual sizes of received regions).
+The copy fields in descriptors will be updated (when scanned, they
+specified allocate versus overwrite, when received, they indicate
+whether the region was physically or virtually copied).
+The descriptors may appear in different positions (given intermingled
+port descriptors).
+Descriptors that were not used (because there were not that many
+received regions) will be discarded.
+ <p>
+Null out-of-line memory is legal. If the out-of-line region size is
+zero, then the region's specified address is ignored. A receive
+allocated null out-of-line memory region always has a zero address.
+Unaligned addresses and region sizes that are not page multiples are
+legal. A received message can also contain regions with unaligned
+addresses and sizes which are not multiples of the page size.
+<h4>Message Send</h4>
+ <p>
+The send operation queues a message to a port. The message carries a
+copy of the caller's data. After the send, the caller can freely
+modify the message buffer or the out-of-line memory regions and the
+message contents will remain unchanged.
+ <p>
+The message carries with it the security ID of the sender, which the
+receiver can request in the message trailer.
+ <p>
+Message delivery is reliable and sequenced. Reception of a message
+guarantees that all messages previously sent to the port by a single
+task (or a single kernel) via send rights have been received and that
+they are received in the order in which they were sent. Messages sent
+to send-once rights are unordered.
+ <p>
+If the destination port's queue is full, several things can happen. If
+the message is sent to a send-once right (msgh_remote_port carries a
+send-once right), then the kernel ignores the queue limit and delivers
+the message. Otherwise the caller blocks until there is room in the
+queue, unless the MACH_SEND_TIMEOUT option is used. If a port has
+several blocked senders, then any of them may queue the next message
+when space in the queue becomes available, with the proviso that a
+blocked sender will not be indefinitely starved.
+These options modify MACH_SEND_MSG. If MACH_SEND_MSG is not also
+specified, they are ignored.
+<dl>
+<dt> MACH_SEND_TIMEOUT
+ <dd>
+The timeout argument should specify a maximum time (in milliseconds)
+for the call to block before giving up. If the message can't be queued
+before the timeout interval elapses, then the call returns
+MACH_SEND_TIMED_OUT. A zero timeout is legitimate.
+<dt> MACH_SEND_INTERRUPT
+ <dd>
+If specified, the <strong>mach_msg</strong> call will return
+MACH_SEND_INTERRUPTED if a software interrupt aborts the call.
+Otherwise, the send operation will be retried.
+<dt> MACH_SEND_TRAILER
+ <dd>
+If set, the kernel, instead of determining the message attributes
+itself, will accept a formatted message trailer from the sender. The
+supplied trailer must be of the latest version supported by the
+kernel, and must contain all message attributes defined by the
+kernel. Only tasks with a security ID of KERNEL_SECURITY_ID can use
+this option; the intended use of this option is in support of the
+Net Message server. The trailer must follow the message in memory as
+it would appear in a received message. (The send_size argument to
+<strong>mach_msg</strong> still indicates the size of the message proper, not including
+this trailer.)
+ </dl>
+ <p>
+The queueing of a message carrying receive rights may create a
+circular loop of receive rights and messages, which can never be
+received. For example, a message carrying a receive right can be
+sent to that receive right. This situation is not an error, but the
+kernel will garbage-collect such loops, destroying the messages.
+Some return codes, like MACH_SEND_TIMED_OUT, imply that the message
+was almost sent, but could not be queued. In these situations, the
+kernel tries to return the message contents to the caller with a
+pseudo-receive operation. This prevents the loss of port rights or
+memory which only exist in the message, for example, a receive right
+which was moved into the message, or out-of-line memory sent with
+the de-allocate option.
+ <p>
+The intent of the pseudo-receive operation is to restore, as best as
+possible, the state prior to attempting the send. This involves
+restoring the port rights and out-of-line memory regions contained in
+the message. The port right names and out-of-line addresses in the
+message send buffer are updated to reflect the new values resulting
+from their effective reception. The pseudo-receive handles the des-
+tination and reply rights as any other rights; they are not reversed
+as is the appearance in a normal received message. Also, no trailer is
+appended to the message. After the pseudo-receive, the message is
+ready to be resent. If the message is not resent, note that
+out-of-line memory regions may have moved and some port rights may
+have changed names.
+ <p>
+Although unlikely, the pseudo-receive operation may encounter resource
+shortages. This is similar to a MACH_RCV_BODY_ERROR return code from
+a receive operation. When this happens, the normal send return codes
+are augmented with the MACH_MSG_IPC_SPACE, MACH_MSG_VM_SPACE,
+MACH_MSG_IPC_KERNEL and MACH_MSG_VM_KERNEL bits to indicate the
+nature of the resource shortage.
+<h4>Message Receive</h4>
+ <p>
+The receive operation de-queues a message from a port. The receiving
+task acquires the port rights and out-of-line memory regions carried
+in the message.
+The receive_name argument specifies a port or port set from which to
+receive. If a port is specified, the caller must possess the receive
+right for the port and the port must not be a member of a port set. If
+no message is present, the call blocks, subject to the
+MACH_RCV_TIMEOUT option.
+<p>
+If a port set is specified, the call will receive a message sent to
+any of the member ports. It is permissible for the port set to have
+no member ports, and ports may be added and removed while a receive
+from the port set is in progress. The received message can come from
+any of the member ports which have messages, with the proviso that a
+member port with messages will not be indefinitely starved. The
+msgh_local_port field in the received message header specifies from
+which port in the port set the message came.
+<p>
+The receive_limit argument specifies the size of the caller's message
+buffer (which must be big enough for the message header, body and
+trailer); the msgh_size field of the received message indicates the
+actual size of the received message header and body. The <strong>mach_msg</strong> call
+will not receive a message larger than receive_limit. Messages that
+are too large are destroyed, unless the MACH_RCV_LARGE option is used.
+Following the received data, at the next natural boundary, is a
+message trailer. The msgh_size field of the received message does not
+include the length of this trailer; the trailer's length is given by
+the msgh_trailer_size field within the trailer. The receiver of a
+message is given a choice as to what trailer format is desired, and,
+within that format, which of the leading trailer attributes are
+desired (that is, to get trailer element three, the receiver must also
+accept elements one and two). For any given trailer format (of which
+there is currently only one), the trailer is compatibly extended by
+adding additional elements to the end.
+<p>
+Received messages are stamped (in the trailer) with a sequence number,
+taken from the port from which the message was received. (Messages
+received from a port set are stamped with a sequence number from the
+appropriate member port.) Newly created ports start with a zero
+sequence number, and the sequence number is reset to zero whenever the
+port's receive right moves between tasks. When a message is de-queued
+from the port, it is stamped with the port's sequence number and the
+port's sequence number is then incremented. (Note that this occurs
+whether or not the receiver requests the sequence number in the trail-
+er.) The de-queue and increment operations are atomic, so that
+multiple threads receiving messages from a port can use the msgh_seqno
+field to reconstruct the original order of the messages.
+<p>
+The destination and reply ports are reversed in a received message
+header. The msgh_local_port field carries the name of the destination
+port, from which the message was received, and the msgh_remote_port
+field carries the reply port right. The bits in msgh_bits are also
+reversed. The MACH_MSGH_BITS_LOCAL bits have a value of
+MACH_MSG_TYPE_PORT_SEND_ONCE or MACH_MSG_TYPE_PORT_SEND depending on
+the type of right to which the message was sent. The
+MACH_MSGH_BITS_REMOTE bits describe the reply port right.
+<p>
+A received message can contain port rights and out-of-line memory. The
+msgh_local_port field does not carry a port right; the act of
+receiving the message consumes the send or send-once right for the
+destination port. The msgh_remote_port field does carry a port right,
+and the message can carry additional port rights and memory if the
+MACH_MSGH_BITS_COMPLEX bit is set. Received port rights and memory
+should be consumed or de-allocated in some fashion.
+In almost all cases, msgh_local_port will specify the name of a
+receive right, either receive_name, or, if receive_name is a port
+set, a member of receive_name.
+<p>
+If other threads are concurrently
+manipulating the receive right, the situation is more complicated. If
+the receive right is renamed during the call, then msgh_local_port
+specifies the right's new name. If the caller loses the receive right
+after the message was de-queued from it, then <strong>mach_msg</strong> will proceed
+instead of returning MACH_RCV_PORT_DIED. If the receive right was
+destroyed, then msgh_local_port specifies MACH_PORT_DEAD. If the
+receive right still exists, but isn't held by the caller, then
+msgh_local_port specifies MACH_PORT_NULL.
+<p>
+The following options modify MACH_RCV_MSG. If MACH_RCV_MSG is not also
+specified, they are ignored.
+<dl>
+<dt> MACH_RCV_TIMEOUT
+ <dd>
+The timeout argument should specify a maximum time (in milliseconds)
+for the call to block before giving up. If no message arrives before
+the timeout interval elapses, then the call returns
+MACH_RCV_TIMED_OUT. A zero timeout is legitimate.
+<dt> MACH_RCV_NOTIFY
+ <dd>
+The notify argument should specify a receive right for a notify
+port. If receiving the reply port creates a new port right in the
+caller, then the notify port is used to request a dead-name
+notification for the new port right.
+<dt> MACH_RCV_INTERRUPT
+ <dd>
+If specified, the <strong>mach_msg</strong> call will return MACH_RCV_INTERRUPTED if a
+software interrupt aborts the call. Otherwise, the receive operation
+will be retried.
+<dt> MACH_RCV_OVERWRITE
+ <dd>
+If specified, the message buffer specified by receive_msg (or msg), of
+length receive_msg_size, will be scanned for out-of-line descriptors to
+specify the processing to be done when receiving out-of-line regions.
+This option is only allowed for <strong>mach_msg_overwrite</strong>.
+<dt> MACH_RCV_LARGE
+ <dd>
+If the message is larger than receive_limit or an out-of-line region
+is larger than the size allowed by a corresponding receive descriptor
+(MACH_RCV_OVERWRITE), the message remains queued instead of being
+destroyed. If the header, trailer and body would not fit into
+receive_limit, only the message header (mach_msg_header) and trailer
+header (mach_msg_trailer) are returned with the actual size of the
+message returned in the msgh_size field, the actual size of the
+trailer returned in the msgh_trailer_size field and an error return
+value of MACH_RCV_TOO_LARGE. If receive_limit is sufficient but an
+out-of-line descriptor is not, the message header, trailer and body
+are received, with out-of-line descriptors set to indicate the
+nature and size of the out-of-line regions, with an error return of
+MACH_RCV_SCATTER_SMALL. No out-of-line regions or port rights
+(including the reply right) will be received. If this option is not
+specified, messages too large will be de-queued and then destroyed;
+the caller receives the message header, with all fields correct,
+including the destination port but excepting the reply port, which is
+MACH_PORT_NULL and an empty (no additional element) message trailer.
+<dt> MACH_RCV_TRAILER_TYPE(value)
+ <dd>
+This macro encodes the type of trailer the kernel must return with the
+message. If the kernel does not recognize this type, it returns
+MACH_RCV_INVALID_TRAILER. Currently, only MACH_MSG_TRAILER_FORMAT_0 is
+supported.
+<dt> MACH_RCV_TRAILER_ELEMENTS(value)
+ <dd>
+This macro encodes the number of trailer elements desired. If the ker-
+nel does not support this number for the requested trailer type, the
+kernel returns MACH_RCV_INVALID_TRAILER. Zero is a legal value.
+ </dl>
+ <p>
+ The following trailer elements are supported:
+ <dl>
+<dt> MACH_RCV_TRAILER_SEQNO
+ <dd>
+Returns the sequence number of the message relative to its port. This
+value is of type mach_port_seqno_t.
+<dt> MACH_RCV_TRAILER_SENDER
+ <dd>
+Returns the security ID of the task that sent the message. This value
+is of type security_id_t.
+ </dl>
+ <p>
+If a resource shortage prevents the reception of a port right, the
+port right is destroyed and the caller sees the name
+MACH_PORT_NULL. If a resource shortage prevents the reception of an
+out-of-line memory region, the region is destroyed and the caller sees
+a zero address. In addition, the corresponding element in the size
+array is set to zero. A task never receives port rights or memory for
+which it is not told.
+ <p>
+The MACH_RCV_HEADER_ERROR return code indicates a resource shortage
+in the reception of the message header. The reply port and all port
+rights and memory in the message are destroyed. The caller receives
+the message header with all fields correct except for the reply
+port.
+ <p>
+The MACH_RCV_BODY_ERROR return code indicates a resource shortage in
+the reception of the message body. The message header, including the
+reply port, is correct. The kernel attempts to transfer all port
+rights and memory regions in the body, and only destroys those that
+can't be transferred.
+<h4>Atomicity</h4>
+ <p>
+The <strong>mach_msg</strong> call handles port rights in the message header
+atomically. Out-of-line memory and port rights in the message body do
+not enjoy this atomicity guarantee. These elements may be processed
+front-to-back, back-to-front, in some random order, or even
+atomically.
+ <p>
+For example, consider sending a message with the destination port
+specified as MACH_MSG_TYPE_MOVE_SEND and the reply port specified as
+MACH_MSG_TYPE_COPY_SEND. The same send right, with one user-refer-
+ence, is supplied for both the msgh_remote_port and msgh_local_port
+fields. Because <strong>mach_msg</strong> processes the port rights atomically, this
+succeeds. If msgh_remote_port were processed before msgh_local_port,
+then <strong>mach_msg</strong> would return MACH_SEND_INVALID_REPLY in this situation.
+ <p>
+On the other hand, suppose the destination and reply port are both
+specified as MACH_MSG_TYPE_MOVE_SEND, and again the same send right
+with one user-reference is supplied for both. Now the send operation
+fails, but because it processes the rights atomically, <strong>mach_msg</strong> can
+return either MACH_SEND_INVALID_DEST or MACH_SEND_INVALID_REPLY.
+<p>
+For example, consider receiving a message at the same time another
+thread is deallocating the destination receive right. Suppose the
+reply port field carries a send right for the destination port. If the
+de-allocation happens before the dequeuing, the receiver gets
+MACH_RCV_PORT_DIED. If the de-allocation happens after the receive,
+the msgh_local_port and the msgh_remote_port fields both specify
+the same right, which becomes a dead name when the receive right is
+de-allocated. If the de-allocation happens between the de-queue and
+the receive, the msgh_local_port and msgh_remote_port fields both
+specify MACH_PORT_DEAD. Because the rights are processed atomically,
+it is not possible for just one of the two fields to hold
+MACH_PORT_DEAD.
+<p>
+The MACH_RCV_NOTIFY option provides a more likely example. Suppose a
+message carrying a send-once right reply port is received with
+MACH_RCV_NOTIFY at the same time the reply port is destroyed. If the
+reply port is destroyed first, then msgh_remote_port specifies
+MACH_PORT_DEAD and the kernel does not generate a dead-name
+notification. If the reply port is destroyed after it is received,
+then msgh_remote_port specifies a dead name for which the kernel
+generates a dead-name notification. Either the reply port is dead on
+arrival or notification is requested.
+<h4>Implementation</h4>
+<p>
+<strong>mach_msg</strong> and <strong>mach_msg_overwrite</strong> are wrappers for a system call. They
+have the responsibility for repeating the interrupted system call.
+<h3>CAUTIONS</h3>
+<p>
+If MACH_RCV_TIMEOUT is used without MACH_RCV_INTERRUPT, then the
+timeout duration might not be accurate. When the call is interrupted
+and automatically retried, the original timeout is used. If
+interrupts occur frequently enough, the timeout interval might never
+expire. MACH_SEND_TIMEOUT without MACH_SEND_INTERRUPT suffers from the
+same problem.
+<h3>RETURN VALUES</h3>
+<p>
+The send operation can generate the following return codes. These
+return codes imply that the call did nothing:
+<dl>
+<p>
+<dt> MACH_SEND_MSG_TOO_SMALL
+ <dd>
+The specified send_size was smaller than the minimum size for a
+message.
+<p>
+<dt> MACH_SEND_NO_BUFFER
+ <dd>
+A resource shortage prevented the kernel from allocating a message
+buffer.
+<p>
+<dt> MACH_SEND_INVALID_DATA
+ <dd>
+The supplied message buffer was not readable.
+<p>
+<dt> MACH_SEND_INVALID_HEADER
+ <dd>
+The msgh_bits value was invalid.
+<p>
+<dt> MACH_SEND_INVALID_DEST
+ <dd>
+The msgh_remote_port value was invalid.
+<p>
+<dt> MACH_SEND_INVALID_NOTIFY
+ <dd>
+When using MACH_SEND_CANCEL, the notify argument did not
+denote a valid receive right.
+<p>
+<dt> MACH_SEND_INVALID_REPLY
+ <dd>
+The msgh_local_port value was invalid.
+<p>
+<dt> MACH_SEND_INVALID_TRAILER
+ <dd>
+The trailer to be sent does not correspond to the current kernel format,
+or the sending task does not have the privilege to supply the message
+attributes.
+ </dl>
+ <p>
+These return codes imply that some or all of the message was destroyed:
+ <dl>
+<p>
+<dt> MACH_SEND_INVALID_MEMORY
+ <dd>
+The message body specified out-of-line data that was not readable.
+<p>
+<dt> MACH_SEND_INVALID_RIGHT
+ <dd>
+The message body specified a port right which the caller didn't possess.
+<p>
+<dt> MACH_SEND_INVALID_TYPE
+ <dd>
+A kernel processed descriptor was invalid.
+<p>
+<dt> MACH_SEND_MSG_TOO_SMALL
+ <dd>
+The last data item in the message ran over the end of the message.
+ </dl>
+ <p>
+These return codes imply that the message was returned to the caller with a
+pseudo-receive operation:
+ <dl>
+<p>
+<dt> MACH_SEND_TIMED_OUT
+ <dd>
+The timeout interval expired.
+<p>
+<dt> MACH_SEND_INTERRUPTED
+ <dd>
+A software interrupt occurred.
+ </dl>
+ <p>
+This return code implies that the message was queued:
+ <dl>
+<p>
+<dt> MACH_MSG_SUCCESS
+ <dd>
+The message was queued.
+ </dl>
+ <p>
+The receive operation can generate the following return codes. These return
+codes imply that the call did not de-queue a message:
+ <dl>
+<p>
+<dt> MACH_RCV_INVALID_NAME
+ <dd>
+The specified receive_name was invalid.
+<p>
+<dt> MACH_RCV_IN_SET
+ <dd>
+The specified port was a member of a port set.
+<p>
+<dt> MACH_RCV_TIMED_OUT
+ <dd>
+The timeout interval expired.
+<p>
+<dt> MACH_RCV_INTERRUPTED
+ <dd>
+A software interrupt occurred.
+<p>
+<dt> MACH_RCV_PORT_DIED
+ <dd>
+The caller lost the rights specified by receive_name.
+<p>
+<dt> MACH_RCV_PORT_CHANGED
+ <dd>
+receive_name specified a receive right which was moved into a port set
+during the call.
+<p>
+<dt> MACH_RCV_TOO_LARGE
+ <dd>
+When using MACH_RCV_LARGE, the message was larger than
+receive_limit. The message is left queued, and its actual size is
+returned in the message header/message body.
+<p>
+<dt> MACH_RCV_SCATTER_SMALL
+ <dd>
+When using MACH_RCV_LARGE with MACH_RCV_OVERWRITE, one or more scatter
+list descriptors specified an overwrite region smaller than the
+corresponding incoming region. The message is left queued, and the
+proper descriptors are returned in the message header/message body.
+<p>
+<dt> MACH_RCV_INVALID_TRAILER
+ <dd>
+The trailer type desired, or the number of trailer elements desired, is
+not supported by the kernel.
+ </dl>
+ <p>
+These return codes imply that a message was de-queued and destroyed:
+ <dl>
+<p>
+<dt> MACH_RCV_HEADER_ERROR
+ <dd>
+A resource shortage prevented the reception of the port rights in the
+message header.
+<p>
+<dt> MACH_RCV_INVALID_NOTIFY
+ <dd>
+When using MACH_RCV_NOTIFY, the notify argument did not denote a
+valid receive right.
+<p>
+<dt> MACH_RCV_INVALID_DATA
+ <dd>
+The specified message buffer was not writable.
+<p>
+<dt> MACH_RCV_TOO_LARGE
+ <dd>
+When not using MACH_RCV_LARGE, a message larger than
+receive_limit was de-queued and destroyed.
+<p>
+<dt> MACH_RCV_SCATTER_SMALL
+ <dd>
+When not using MACH_RCV_LARGE with MACH_RCV_OVERWRITE, one or more
+scatter list descriptors specified an overwrite region smaller than
+the corresponding incoming region. The message was de-queued and
+destroyed.
+<p>
+<dt> MACH_RCV_OVERWRITE_ERROR
+ <dd>
+A region specified by a receive overwrite descriptor
+(MACH_RCV_OVERWRITE) was not allocated or could not be written.
+<p>
+<dt> MACH_RCV_INVALID_TYPE
+ <dd>
+When using MACH_RCV_OVERWRITE, one or more scatter list descriptors
+did not have the type matching the corresponding incoming message
+descriptor or had an invalid copy (disposition) field.
+<p>
+<dt> MACH_RCV_LIMITS
+ <dd>
+The combined size of all out-of-line memory regions or the total num-
+ber of port rights in the message exceeds the limit set for the port.
+These return codes imply that a message was received:
+<p>
+<dt> MACH_RCV_BODY_ERROR
+ <dd>
+A resource shortage prevented the reception of a port right or out-of-
+line memory region in the message body.
+<p>
+<dt> MACH_MSG_SUCCESS
+ <dd>
+A message was received.
+ </dl>
+ <p>
+Resource shortages can occur after a message is de-queued, while
+transferring port rights and out-of-line memory regions to the
+receiving task. The <strong>mach_msg</strong> call returns MACH_RCV_HEADER_ERROR or
+MACH_RCV_BODY_ERROR in this situation. These return codes always carry
+ extra bits (bitwise-or'ed) that indicate the nature of the resource
+shortage:
+ <dl>
+<p>
+<dt> MACH_MSG_IPC_SPACE
+ <dd>
+There was no room in the task's IPC name space for another port name.
+<p>
+<dt> MACH_MSG_VM_SPACE
+ <dd>
+There was no room in the task's VM address space for an out-of-line
+memory region.
+<p>
+<dt> MACH_MSG_IPC_KERNEL
+ <dd>
+A kernel resource shortage prevented the reception of a port right.
+<p>
+<dt> MACH_MSG_VM_KERNEL
+ <dd>
+A kernel resource shortage prevented the reception of an out-of-line
+memory region.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="vm_allocate.html"><strong>vm_allocate</strong></a>,
+<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>,
+<a href="vm_write.html"><strong>vm_write</strong></a>,
+<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>,
+<p>
+Data Structures:
+mach_msg_header.
-<h2>mach_msg_descriptor</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Specifies operations that must be performed on a given IPC message element.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>typedef struct</strong>
\r<strong>{</strong>
\r <strong>void*</strong> <var>pad1</var><strong>;</strong>
\r <strong>mach_msg_size_t</strong> <var>pad2</var><strong>;</strong>
\r <strong>unsigned int</strong> <var>pad3</var><strong> : 24;</strong>
\r <strong>mach_msg_descriptor_type_t</strong> <var>type</var><strong> : 8;</strong>
\r<strong>} mach_msg_type_descriptor_t;</strong>
\r\r<strong>typedef struct</strong>
\r<strong>{</strong>
\r <strong>mach_port_t</strong> <var>name</var><strong>;</strong>
\r <strong>mach_msg_size_t</strong> <var>pad1</var><strong>;</strong>
\r <strong>unsigned int</strong> <var>pad2</var><strong> : 16;</strong>
\r <strong>mach_msg_type_name_t</strong> <var>disposition</var><strong> : 8;</strong>
\r <strong>mach_msg_descriptor_type_t</strong> <var>type</var><strong> : 8;</strong>
\r<strong>} mach_msg_port_descriptor_t;</strong>
\r\r<strong>typedef struct</strong>
\r<strong>{</strong>
\r <strong>void*</strong> <var>address</var><strong>;</strong>
\r <strong>mach_msg_size_t</strong> <var>size</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>deallocate</var><strong> : 8;</strong>
\r <strong>mach_msg_copy_options_t</strong> <var>copy</var><strong> : 8;</strong>
\r <strong>unsigned int</strong> <var>pad1</var><strong> : 8;</strong>
\r <strong>mach_msg_descriptor_type_t</strong> <var>type</var><strong> : 8;</strong>
\r<strong>} mach_msg_ool_descriptor_t;</strong>
\r\r<strong>typedef struct</strong>
\r<strong>{</strong>
\r <strong>void*</strong> <var>address</var><strong>;</strong>
\r <strong>mach_msg_size_t</strong> <var>count</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>deallocate</var><strong> : 8;</strong>
\r <strong>mach_msg_copy_options_t</strong> <var>copy</var><strong> : 8;</strong>
\r <strong>mach_msg_type_name_t</strong> <var>disposition</var><strong> : 8;</strong>
\r <strong>mach_msg_descriptor_type_t</strong> <var>type</var><strong> : 8;</strong>
\r<strong>} mach_msg_ool_ports_descriptor_t;</strong>
\r\r<strong>typedef union</strong>
\r<strong>{</strong>
\r <strong>mach_msg_port_descriptor_t</strong> <var>port</var><strong>;</strong>
\r <strong>mach_msg_ool_descriptor_t</strong> <var>out_of_line</var><strong>;</strong>
\r <strong>mach_msg_ool_ports_descriptor_t</strong> <var>ool_ports</var><strong>;</strong>
\r <strong>mach_msg_type_descriptor_t</strong> <var>type</var><strong>;</strong>
\r<strong>} mach_msg_descriptor_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>name</var>
\r<dd>
\rFor single port descriptors, the name of the port whose right is being
\rsent.
\r <p>
\r<dt> <var>disposition</var>
\r<dd>
\rFor single port or out-of-line port array descriptors, the IPC processing
\rto be done for the rights for the named ports.
\r <p>
\r<dt> <var>address</var>
\r<dd>
\rFor out-of-line data or port array descriptors, the address of the
\rout-of-line data or port (name) array.
\r <p>
\r<dt> <var>size</var>
\r<dd>
\rFor out-of-line data descriptors, the size of the out-of-line region, in
\rbytes.
\r <p>
\r<dt> <var>deallocate</var>
\r<dd>
\rFor out-of-line data descriptors, true if the set of pages containing the
\rarray should be de-allocated when the message is sent.
\r <p>
\r<dt> <var>copy</var>
\r<dd>
\rFor out-of-line descriptors, a description of the method by which the
\rdata should be copied.
\r <p>
\r<dt> <var>count</var>
\r<dd>
\rFor out-of-line port array descriptors, the number of port names in the
\rarray.
\r <p>
\r<dt> <var>type</var>
\r<dd>
\rFor any type of descriptor, the type of descriptor.
\r <p>
\r<dt> <var>port</var>
\r<dd>
\rA descriptor that describes a single port right.
\r <p>
\r<dt> <var>out_of_line</var>
\r<dd>
\rA descriptor that describes an out-of-line data array.
\r <p>
\r<dt> <var>ool_ports</var>
\r<dd>
\rA descriptor that describes an out-of-line port array.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>mach_msg_descriptor</strong> structure describes the processing
\rto be performed
\rfor an element of kernel-processed data in a Mach message.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>.
\r<p>
\rData Structures:
\r<a href="mach_msg_header.html"><strong>mach_msg_header</strong></a>.
\r\ No newline at end of file
+<h2>mach_msg_descriptor</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Specifies operations that must be performed on a given IPC message element.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>typedef struct</strong>
+<strong>{</strong>
+ <strong>void*</strong> <var>pad1</var><strong>;</strong>
+ <strong>mach_msg_size_t</strong> <var>pad2</var><strong>;</strong>
+ <strong>unsigned int</strong> <var>pad3</var><strong> : 24;</strong>
+ <strong>mach_msg_descriptor_type_t</strong> <var>type</var><strong> : 8;</strong>
+<strong>} mach_msg_type_descriptor_t;</strong>
+
+<strong>typedef struct</strong>
+<strong>{</strong>
+ <strong>mach_port_t</strong> <var>name</var><strong>;</strong>
+ <strong>mach_msg_size_t</strong> <var>pad1</var><strong>;</strong>
+ <strong>unsigned int</strong> <var>pad2</var><strong> : 16;</strong>
+ <strong>mach_msg_type_name_t</strong> <var>disposition</var><strong> : 8;</strong>
+ <strong>mach_msg_descriptor_type_t</strong> <var>type</var><strong> : 8;</strong>
+<strong>} mach_msg_port_descriptor_t;</strong>
+
+<strong>typedef struct</strong>
+<strong>{</strong>
+ <strong>void*</strong> <var>address</var><strong>;</strong>
+ <strong>mach_msg_size_t</strong> <var>size</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>deallocate</var><strong> : 8;</strong>
+ <strong>mach_msg_copy_options_t</strong> <var>copy</var><strong> : 8;</strong>
+ <strong>unsigned int</strong> <var>pad1</var><strong> : 8;</strong>
+ <strong>mach_msg_descriptor_type_t</strong> <var>type</var><strong> : 8;</strong>
+<strong>} mach_msg_ool_descriptor_t;</strong>
+
+<strong>typedef struct</strong>
+<strong>{</strong>
+ <strong>void*</strong> <var>address</var><strong>;</strong>
+ <strong>mach_msg_size_t</strong> <var>count</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>deallocate</var><strong> : 8;</strong>
+ <strong>mach_msg_copy_options_t</strong> <var>copy</var><strong> : 8;</strong>
+ <strong>mach_msg_type_name_t</strong> <var>disposition</var><strong> : 8;</strong>
+ <strong>mach_msg_descriptor_type_t</strong> <var>type</var><strong> : 8;</strong>
+<strong>} mach_msg_ool_ports_descriptor_t;</strong>
+
+<strong>typedef union</strong>
+<strong>{</strong>
+ <strong>mach_msg_port_descriptor_t</strong> <var>port</var><strong>;</strong>
+ <strong>mach_msg_ool_descriptor_t</strong> <var>out_of_line</var><strong>;</strong>
+ <strong>mach_msg_ool_ports_descriptor_t</strong> <var>ool_ports</var><strong>;</strong>
+ <strong>mach_msg_type_descriptor_t</strong> <var>type</var><strong>;</strong>
+<strong>} mach_msg_descriptor_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>name</var>
+<dd>
+For single port descriptors, the name of the port whose right is being
+sent.
+ <p>
+<dt> <var>disposition</var>
+<dd>
+For single port or out-of-line port array descriptors, the IPC processing
+to be done for the rights for the named ports.
+ <p>
+<dt> <var>address</var>
+<dd>
+For out-of-line data or port array descriptors, the address of the
+out-of-line data or port (name) array.
+ <p>
+<dt> <var>size</var>
+<dd>
+For out-of-line data descriptors, the size of the out-of-line region, in
+bytes.
+ <p>
+<dt> <var>deallocate</var>
+<dd>
+For out-of-line data descriptors, true if the set of pages containing the
+array should be de-allocated when the message is sent.
+ <p>
+<dt> <var>copy</var>
+<dd>
+For out-of-line descriptors, a description of the method by which the
+data should be copied.
+ <p>
+<dt> <var>count</var>
+<dd>
+For out-of-line port array descriptors, the number of port names in the
+array.
+ <p>
+<dt> <var>type</var>
+<dd>
+For any type of descriptor, the type of descriptor.
+ <p>
+<dt> <var>port</var>
+<dd>
+A descriptor that describes a single port right.
+ <p>
+<dt> <var>out_of_line</var>
+<dd>
+A descriptor that describes an out-of-line data array.
+ <p>
+<dt> <var>ool_ports</var>
+<dd>
+A descriptor that describes an out-of-line port array.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>mach_msg_descriptor</strong> structure describes the processing
+to be performed
+for an element of kernel-processed data in a Mach message.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_msg.html"><strong>mach_msg</strong></a>.
+<p>
+Data Structures:
+<a href="mach_msg_header.html"><strong>mach_msg_header</strong></a>.
-<h2>mach_msg_header</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Specifies the content of an IPC message header.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>typedef struct</strong>
\r<strong>{</strong>
\r <strong>mach_msg_bits_t </strong> <var>msgh_bits</var><strong>;</strong>
\r <strong>mach_msg_size_t</strong> <var>msgh_size</var><strong>;</strong>
\r <strong>mach_port_t</strong> <var>msgh_remote_port</var><strong>;</strong>
\r <strong>mach_port_t</strong> <var>msgh_local_port</var><strong>;</strong>
\r <strong>mach_msg_size_t</strong> <var>msgh_reserved</var><strong>;</strong>
\r <strong>mach_msg_id_t</strong> <var>msgh_id</var><strong>;</strong>
\r<strong>} mach_msg_header_t;</strong>
\r\r<strong>typedef struct</strong>
\r<strong>{</strong>
\r <strong>mach_msg_size_t</strong> <var>msgh_descriptor_count</var><strong>;</strong>
\r<strong>} mach_msg_body_t;</strong>
\r\r<strong>typedef struct</strong>
\r<strong>{</strong>
\r <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong>
\r <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong>
\r<strong>} mach_msg_trailer_t;</strong>
\r\r<strong>typedef struct</strong>
\r<strong>{</strong>
\r <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong>
\r <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong>
\r <strong>mach_port_seqno_t</strong> <var>msgh_seqno</var><strong>;</strong>
\r<strong>} mach_msg_seqno_trailer_t;</strong>
\r\r<strong>typedef struct</strong>
\r<strong>{</strong>
\r <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong>
\r <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong>
\r <strong>mach_port_seqno_t</strong> <var>msgh_seqno</var><strong>;</strong>
\r <strong>security_token_t</strong> <var>msgh_sender</var><strong>;</strong>
\r<strong>} mach_msg_security_trailer_t;</strong>
\r\r<strong>typedef struct</strong>
\r<strong>{</strong>
\r <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong>
\r <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong>
\r <strong>mach_port_seqno_t</strong> <var>msgh_seqno</var><strong>;</strong>
\r <strong>security_token_t</strong> <var>msgh_sender</var><strong>;</strong>
\r <strong>unsigned int</strong> <var>dipc_sender_kmsg</var><strong>;</strong>
\r<strong>} mach_msg_dipc_trailer_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>msgh_bits</var>
\r<dd>
\rThis field specifies the following properties of the message:
\r<dl>
\r <p>
\r<dt> <strong>MACH_MSGH_BITS_REMOTE_MASK</strong>
\r<dd>
\rEncodes <var>mach_msg_type_name_t</var> values that specify the port
\rrights in the <var>msgh_remote_port</var> field. The value must specify
\ra send or send-once right for the destination of the message.
\r <p>
\r<dt> <strong>MACH_MSGH_BITS_LOCAL_MASK</strong>
\r<dd>
\rEncodes <var>mach_msg_type_name_t</var> values that specify the port
\rrights in the <var>msgh_local_port</var> field. If the value doesn't
\rspecify a send or send-once right for the message's reply port, it
\rmust be zero and <var>msgh_local_port</var> must be <strong>MACH_PORT_NULL</strong>.
\r <p>
\r<dt> <strong>MACH_MSGH_BITS_COMPLEX</strong>
\r<dd>
\rThe complex bit must be specified if the message body
\rcontains additional port rights or out-of-line memory regions.
\r <p>
\r<dt> <strong>MACH_MSGH_BITS_REMOTE</strong>(<var>bits</var>)
\r<dd>
\rThis macro returns the appropriate <var>mach_msg_type_name_t</var>
\rvalues, given a <var>msgh_bits</var> value.
\r <p>
\r<dt> <strong>MACH_MSGH_BITS_LOCAL</strong>(<var>bits</var>)
\r<dd>
\rThis macro returns the appropriate <var>mach_msg_type_name_t</var>
\rvalues, given a <var>msgh_bits</var> value.
\r <p>
\r<dt> <strong>MACH_MSGH_BITS</strong>(<var>remote</var>, <var>local</var>)
\r<dd>
\rThis macro constructs a value for <var>msgh_bits</var>, given two
\r<var>mach_msg_type_name_t</var> values.
\r</dl>
\r<p>
\r<dt> <var>msgh_size</var>
\r<dd>
\rThis field is ignored on send (the size to send is specified by the
\r<var>send_size</var> parameter to <strong>mach_msg</strong>); the field is set on
\rreceive to the sum of
\rthe message header and body sizes (in bytes). Note that this value may
\rbe different from the send size specified by the sender if the sender and
\rreceiver machines have differing sizes for port names, memory
\raddresses or memory range sizes.
\r <p>
\r<dt> <var>msgh_remote_port</var>
\r<dd>
\rWhen sending, specifies the destination port of the message. The field
\rmust carry a legitimate send or send-once right for a port. When
\rreceived, this field is swapped with <var>msgh_local_port</var>.
\r <p>
\r<dt> <var>msgh_local_port</var>
\r<dd>
\rWhen sending, specifies an auxiliary port right, which is
\rconventionally used as a reply port by the recipient of the message.
\rThe field must
\rcarry a send right, a send-once right, <strong>MACH_PORT_NULL</strong>, or
\r<strong>MACH_PORT_DEAD</strong>. When received, this field is swapped with
\r<var>msgh_remote_port</var>.
\r <p>
\r<dt> <var>msgh_id</var>
\r<dd>
\rNot set or read by the <strong>mach_msg</strong> call. The conventional meaning is to
\rconvey an operation or function ID.
\r <p>
\r<dt> <var>msgh_descriptor_count</var>
\r<dd>
\rThe number of descriptors of kernel processed data (port rights and
\rout-of-line data).
\r <p>
\r<dt> <var>msgh_trailer_type</var>
\r<dd>
\rAn identifier of the trailer version. Different values indicate not
\rnecessarily compatible trailer formats. The current (and only) trailer format
\ris <strong>MACH_MSG_TRAILER_FORMAT_0</strong>. There is currently only one
\rattribute defined within this trailer type: the sender's identity.
\r <p>
\r<dt> <var>msgh_trailer_size</var>
\r<dd>
\rThe length, in bytes, of the message trailer, including the trailer type
\rand length fields.
\r <p>
\r<dt> <var>msgh_seqno</var>
\r<dd>
\rThe sequence number of this message relative to the port from which it
\ris received.
\r <p>
\r<dt> <var>msgh_sender</var>
\r<dd>
\rThe security ID of the sender of the message.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_msg_header</strong> structure defines the fixed size header of a Mach
\rmessage. The header is followed by a message body containing data and port
\rdescriptors and zero or more data bytes.
\r<p>
\rIf the <strong>MACH_MSGH_BITS_COMPLEX</strong> flag in the <var>msgh_bits</var> field is not set,
\rthen this is a simple message described by <strong>mach_msg_header_t</strong>.
\rIn this case, the header is immediately followed by untyped data.
\r<p>
\rIf the complex flag is set, then this is a "complex" message consisting of a
\r<strong>mach_msg_header_t</strong> structure followed by a <strong>mach_msg_body_t</strong> structure
\rcontaining a count followed by an array of descriptors specifying
\rthe disposition
\r(processing) to be performed for the out-of-line memory regions and additional
\rport rights.
\r<p>
\rFollowing the header (and any kernel processed descriptors), at natural
\ralignment can be additional (un-typed) data, up to the size of the message
\r(<var>msgh_size</var>). This extra data typically carries information
\rused to decode the data stream and out-of-line data.
\r<p>
\rAt the next natural boundary following the message data is the message trailer
\r(<strong>mach_msg_trailer_t</strong>). This structure indicates the type and length of the
\rtrailer. If the length is greater than sizeof (<strong>mach_msg_trailer_t</strong>),
\radditional fields
\rfollow providing kernel-generated message attributes.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>.
\r<p>
\rData Structures:
\r<a href="mach_msg_descriptor.html"><strong>mach_msg_descriptor</strong></a>.
\r\r\ No newline at end of file
+<h2>mach_msg_header</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Specifies the content of an IPC message header.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>typedef struct</strong>
+<strong>{</strong>
+ <strong>mach_msg_bits_t </strong> <var>msgh_bits</var><strong>;</strong>
+ <strong>mach_msg_size_t</strong> <var>msgh_size</var><strong>;</strong>
+ <strong>mach_port_t</strong> <var>msgh_remote_port</var><strong>;</strong>
+ <strong>mach_port_t</strong> <var>msgh_local_port</var><strong>;</strong>
+ <strong>mach_msg_size_t</strong> <var>msgh_reserved</var><strong>;</strong>
+ <strong>mach_msg_id_t</strong> <var>msgh_id</var><strong>;</strong>
+<strong>} mach_msg_header_t;</strong>
+
+<strong>typedef struct</strong>
+<strong>{</strong>
+ <strong>mach_msg_size_t</strong> <var>msgh_descriptor_count</var><strong>;</strong>
+<strong>} mach_msg_body_t;</strong>
+
+<strong>typedef struct</strong>
+<strong>{</strong>
+ <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong>
+ <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong>
+<strong>} mach_msg_trailer_t;</strong>
+
+<strong>typedef struct</strong>
+<strong>{</strong>
+ <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong>
+ <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong>
+ <strong>mach_port_seqno_t</strong> <var>msgh_seqno</var><strong>;</strong>
+<strong>} mach_msg_seqno_trailer_t;</strong>
+
+<strong>typedef struct</strong>
+<strong>{</strong>
+ <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong>
+ <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong>
+ <strong>mach_port_seqno_t</strong> <var>msgh_seqno</var><strong>;</strong>
+ <strong>security_token_t</strong> <var>msgh_sender</var><strong>;</strong>
+<strong>} mach_msg_security_trailer_t;</strong>
+
+<strong>typedef struct</strong>
+<strong>{</strong>
+ <strong>mach_msg_trailer_type_t</strong> <var>msgh_trailer_type</var><strong>;</strong>
+ <strong>mach_msg_trailer_size_t</strong> <var>msgh_trailer_size</var><strong>;</strong>
+ <strong>mach_port_seqno_t</strong> <var>msgh_seqno</var><strong>;</strong>
+ <strong>security_token_t</strong> <var>msgh_sender</var><strong>;</strong>
+ <strong>unsigned int</strong> <var>dipc_sender_kmsg</var><strong>;</strong>
+<strong>} mach_msg_dipc_trailer_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>msgh_bits</var>
+<dd>
+This field specifies the following properties of the message:
+<dl>
+ <p>
+<dt> <strong>MACH_MSGH_BITS_REMOTE_MASK</strong>
+<dd>
+Encodes <var>mach_msg_type_name_t</var> values that specify the port
+rights in the <var>msgh_remote_port</var> field. The value must specify
+a send or send-once right for the destination of the message.
+ <p>
+<dt> <strong>MACH_MSGH_BITS_LOCAL_MASK</strong>
+<dd>
+Encodes <var>mach_msg_type_name_t</var> values that specify the port
+rights in the <var>msgh_local_port</var> field. If the value doesn't
+specify a send or send-once right for the message's reply port, it
+must be zero and <var>msgh_local_port</var> must be <strong>MACH_PORT_NULL</strong>.
+ <p>
+<dt> <strong>MACH_MSGH_BITS_COMPLEX</strong>
+<dd>
+The complex bit must be specified if the message body
+contains additional port rights or out-of-line memory regions.
+ <p>
+<dt> <strong>MACH_MSGH_BITS_REMOTE</strong>(<var>bits</var>)
+<dd>
+This macro returns the appropriate <var>mach_msg_type_name_t</var>
+values, given a <var>msgh_bits</var> value.
+ <p>
+<dt> <strong>MACH_MSGH_BITS_LOCAL</strong>(<var>bits</var>)
+<dd>
+This macro returns the appropriate <var>mach_msg_type_name_t</var>
+values, given a <var>msgh_bits</var> value.
+ <p>
+<dt> <strong>MACH_MSGH_BITS</strong>(<var>remote</var>, <var>local</var>)
+<dd>
+This macro constructs a value for <var>msgh_bits</var>, given two
+<var>mach_msg_type_name_t</var> values.
+</dl>
+<p>
+<dt> <var>msgh_size</var>
+<dd>
+This field is ignored on send (the size to send is specified by the
+<var>send_size</var> parameter to <strong>mach_msg</strong>); the field is set on
+receive to the sum of
+the message header and body sizes (in bytes). Note that this value may
+be different from the send size specified by the sender if the sender and
+receiver machines have differing sizes for port names, memory
+addresses or memory range sizes.
+ <p>
+<dt> <var>msgh_remote_port</var>
+<dd>
+When sending, specifies the destination port of the message. The field
+must carry a legitimate send or send-once right for a port. When
+received, this field is swapped with <var>msgh_local_port</var>.
+ <p>
+<dt> <var>msgh_local_port</var>
+<dd>
+When sending, specifies an auxiliary port right, which is
+conventionally used as a reply port by the recipient of the message.
+The field must
+carry a send right, a send-once right, <strong>MACH_PORT_NULL</strong>, or
+<strong>MACH_PORT_DEAD</strong>. When received, this field is swapped with
+<var>msgh_remote_port</var>.
+ <p>
+<dt> <var>msgh_id</var>
+<dd>
+Not set or read by the <strong>mach_msg</strong> call. The conventional meaning is to
+convey an operation or function ID.
+ <p>
+<dt> <var>msgh_descriptor_count</var>
+<dd>
+The number of descriptors of kernel processed data (port rights and
+out-of-line data).
+ <p>
+<dt> <var>msgh_trailer_type</var>
+<dd>
+An identifier of the trailer version. Different values indicate not
+necessarily compatible trailer formats. The current (and only) trailer format
+is <strong>MACH_MSG_TRAILER_FORMAT_0</strong>. There is currently only one
+attribute defined within this trailer type: the sender's identity.
+ <p>
+<dt> <var>msgh_trailer_size</var>
+<dd>
+The length, in bytes, of the message trailer, including the trailer type
+and length fields.
+ <p>
+<dt> <var>msgh_seqno</var>
+<dd>
+The sequence number of this message relative to the port from which it
+is received.
+ <p>
+<dt> <var>msgh_sender</var>
+<dd>
+The security ID of the sender of the message.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_msg_header</strong> structure defines the fixed size header of a Mach
+message. The header is followed by a message body containing data and port
+descriptors and zero or more data bytes.
+<p>
+If the <strong>MACH_MSGH_BITS_COMPLEX</strong> flag in the <var>msgh_bits</var> field is not set,
+then this is a simple message described by <strong>mach_msg_header_t</strong>.
+In this case, the header is immediately followed by untyped data.
+<p>
+If the complex flag is set, then this is a "complex" message consisting of a
+<strong>mach_msg_header_t</strong> structure followed by a <strong>mach_msg_body_t</strong> structure
+containing a count followed by an array of descriptors specifying
+the disposition
+(processing) to be performed for the out-of-line memory regions and additional
+port rights.
+<p>
+Following the header (and any kernel processed descriptors), at natural
+alignment can be additional (un-typed) data, up to the size of the message
+(<var>msgh_size</var>). This extra data typically carries information
+used to decode the data stream and out-of-line data.
+<p>
+At the next natural boundary following the message data is the message trailer
+(<strong>mach_msg_trailer_t</strong>). This structure indicates the type and length of the
+trailer. If the length is greater than sizeof (<strong>mach_msg_trailer_t</strong>),
+additional fields
+follow providing kernel-generated message attributes.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_msg.html"><strong>mach_msg</strong></a>.
+<p>
+Data Structures:
+<a href="mach_msg_descriptor.html"><strong>mach_msg_descriptor</strong></a>.
+
-<h2>mach_port_allocate</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Create caller-specified type of port right.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_allocate</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_right_t</strong> <var>right</var>,
\r <strong>mach_port_name_t</strong> <var>*name</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task acquiring the port right.
\r<p>
\r<dt> <var>right</var>
\r<dd>
\r[in scalar]
\rThe kind of entity to be created. This is one of the following:
\r<dl>
\r<p>
\r<dt> <strong>MACH_PORT_RIGHT_RECEIVE</strong>
\r<dd>
\r<strong>mach_port_allocate</strong> creates a port. The new port is not a
\rmember of any port set. It doesn't have any extant send or
\rsend-once rights. Its make-send count is zero, its sequence
\rnumber is zero, its queue limit is <strong>MACH_PORT_QLIMIT_DEFAULT</strong>, and
\rit has no queued messages. <var>name</var> denotes the
\rreceive right for the new port.
\r<var>task</var> does not hold send rights for the new port, only the
\rreceive right. <strong>mach_port_insert_right</strong> and
\r<strong>mach_port_extract_right</strong> can be used to convert the receive right into a
\rcombined send/receive right.
\r<p>
\r<dt> <strong>MACH_PORT_RIGHT_PORT_SET</strong>
\r<dd>
\r<strong>mach_port_allocate</strong> creates a port set. The new port set has
\rno members.
\r<p>
\r<dt> <strong>MACH_PORT_RIGHT_DEAD_NAME</strong>
\r<dd>
\r<strong>mach_port_allocate</strong> creates a dead name. The new dead
\rname has one user reference.
\r</dl>
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[out scalar]
\rThe task's name for the port right. This can be any name
\rthat wasn't in use.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_allocate</strong> function creates a new right
\rin the specified task. The new right's name is returned in name.
\r<p>
\rPorts that are allocated via this call do not support the full set of
\rMach port semantics; in particular, the kernel will not provide no-more-senders
\rnotification service requests on such ports. Any attempt to request no-more-senders
\rnotification service
\rwill generate an error. Use the <strong>mach_port_allocate_full</strong>
\rinterface to allocate ports that support the full set of Mach port semantics.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_NO_SPACE</strong>
\r<dd>
\rThere was no room in task's IPC name space for another right.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>,
\r<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>,
\r<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>,
\r<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_allocate</h2>
+<hr>
+<p>
+<strong>Function</strong> - Create caller-specified type of port right.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_allocate</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_right_t</strong> <var>right</var>,
+ <strong>mach_port_name_t</strong> <var>*name</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task acquiring the port right.
+<p>
+<dt> <var>right</var>
+<dd>
+[in scalar]
+The kind of entity to be created. This is one of the following:
+<dl>
+<p>
+<dt> <strong>MACH_PORT_RIGHT_RECEIVE</strong>
+<dd>
+<strong>mach_port_allocate</strong> creates a port. The new port is not a
+member of any port set. It doesn't have any extant send or
+send-once rights. Its make-send count is zero, its sequence
+number is zero, its queue limit is <strong>MACH_PORT_QLIMIT_DEFAULT</strong>, and
+it has no queued messages. <var>name</var> denotes the
+receive right for the new port.
+<var>task</var> does not hold send rights for the new port, only the
+receive right. <strong>mach_port_insert_right</strong> and
+<strong>mach_port_extract_right</strong> can be used to convert the receive right into a
+combined send/receive right.
+<p>
+<dt> <strong>MACH_PORT_RIGHT_PORT_SET</strong>
+<dd>
+<strong>mach_port_allocate</strong> creates a port set. The new port set has
+no members.
+<p>
+<dt> <strong>MACH_PORT_RIGHT_DEAD_NAME</strong>
+<dd>
+<strong>mach_port_allocate</strong> creates a dead name. The new dead
+name has one user reference.
+</dl>
+<p>
+<dt> <var>name</var>
+<dd>
+[out scalar]
+The task's name for the port right. This can be any name
+that wasn't in use.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_allocate</strong> function creates a new right
+in the specified task. The new right's name is returned in name.
+<p>
+Ports that are allocated via this call do not support the full set of
+Mach port semantics; in particular, the kernel will not provide no-more-senders
+notification service requests on such ports. Any attempt to request no-more-senders
+notification service
+will generate an error. Use the <strong>mach_port_allocate_full</strong>
+interface to allocate ports that support the full set of Mach port semantics.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_NO_SPACE</strong>
+<dd>
+There was no room in task's IPC name space for another right.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>,
+<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>,
+<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>,
+<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>.
-<h2>mach_port_allocate_full</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Create a port right with full Mach port semantics.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_allocate_full</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_right_t</strong> <var>right</var>,
\r <strong>subsystem_t</strong> <var>subsystem</var>,
\r <strong>mach_port_qos_t</strong> <var>qos</var>,
\r <strong>task</strong> <var>name</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right] The task acquiring the port right.
\r<p>
\r<dt> <var>right</var>
\r<dd>
\r[in scalar] The kind of entity to be created. This is one of the following:
\r<dl>
\r<p>
\r<dt> <strong>MACH_PORT_RIGHT_RECEIVE</strong>
\r<dd>
\r<strong>mach_port_allocate_full</strong> creates a port. The new port is not a member
\rof any port set. It doesn't have any extant send or send-once
\rrights. Its make-send count is zero, its sequence number is zero, its
\rqueue limit is MACH_PORT_QLIMIT_DEFAULT, and it has no queued
\rmessages. The <var>name</var> parameter
\rdenotes the receive right for the new port.
\rThe owning task does not hold send rights for the new port, only the receive
\rright. The <strong>mach_port_insert_right</strong>
\rand <strong>mach_port_extract_right</strong> interfaces can be used
\rto convert the receive right to a combined send/receive right.
\r<p>
\r<dt> <strong>MACH_PORT_RIGHT_PORT_SET</strong>
\r<dd>
\r<strong>mach_port_allocate_full</strong> creates a port set. The new port set
\rhas no members.
\r<p>
\r<dt> <strong>MACH_PORT_RIGHT_DEAD_NAME</strong>
\r<dd>
\r<strong>mach_port_allocate_full</strong> creates a dead name. The new dead
\rname has one user reference.
\r</dl>
\r<p>
\r<dt> <var>subsystem</var>
\r<dd>
\r[in scalar] The port right naming the subsystem the newly created port
\ris to be associated with.
\r<p>
\r<p>
\r<dt> <var>qos</var>
\r<dd>
\r[pointer to an in/out structure] Structure used to specify
\rthe desired "quality of service." This structure may be used
\rto mandate the name of the returned port right and/or the port's "quality
\rof service" attribute. The current implementation recognizes two such
\rattributes: regular and realtime.
\r<dt> <var>name</var>
\r<dd>
\r[out scalar] The task's name for the port right. This can be any name
\rthat wasn't in use.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_allocate_full</strong> function creates a new right in the
\rspecified task. The new right's name is returned via the <var>name</var> parameter.
\rThe new port supports the full set of Mach port semantics (i.e. no_more_senders
\rdetection will work, if requested).
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port
\rname parameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_NO_SPACE</strong>
\r<dd>
\rThere was no room in task's IPC name space for another right.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>,
\r<a href="mach_port_allocate.html"><strong>mach_port_allocate_qos</strong></a>,
\r<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>,
\r<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>,
\r<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>,
\r<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>.
\r<p>
\rStructures:
\r<a href="mach_port_qos.html"><strong>mach_port_qos</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_allocate_full</h2>
+<hr>
+<p>
+<strong>Function</strong> - Create a port right with full Mach port semantics.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_allocate_full</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_right_t</strong> <var>right</var>,
+ <strong>subsystem_t</strong> <var>subsystem</var>,
+ <strong>mach_port_qos_t</strong> <var>qos</var>,
+ <strong>task</strong> <var>name</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right] The task acquiring the port right.
+<p>
+<dt> <var>right</var>
+<dd>
+[in scalar] The kind of entity to be created. This is one of the following:
+<dl>
+<p>
+<dt> <strong>MACH_PORT_RIGHT_RECEIVE</strong>
+<dd>
+<strong>mach_port_allocate_full</strong> creates a port. The new port is not a member
+of any port set. It doesn't have any extant send or send-once
+rights. Its make-send count is zero, its sequence number is zero, its
+queue limit is MACH_PORT_QLIMIT_DEFAULT, and it has no queued
+messages. The <var>name</var> parameter
+denotes the receive right for the new port.
+The owning task does not hold send rights for the new port, only the receive
+right. The <strong>mach_port_insert_right</strong>
+and <strong>mach_port_extract_right</strong> interfaces can be used
+to convert the receive right to a combined send/receive right.
+<p>
+<dt> <strong>MACH_PORT_RIGHT_PORT_SET</strong>
+<dd>
+<strong>mach_port_allocate_full</strong> creates a port set. The new port set
+has no members.
+<p>
+<dt> <strong>MACH_PORT_RIGHT_DEAD_NAME</strong>
+<dd>
+<strong>mach_port_allocate_full</strong> creates a dead name. The new dead
+name has one user reference.
+</dl>
+<p>
+<dt> <var>subsystem</var>
+<dd>
+[in scalar] The port right naming the subsystem the newly created port
+is to be associated with.
+<p>
+<p>
+<dt> <var>qos</var>
+<dd>
+[pointer to an in/out structure] Structure used to specify
+the desired "quality of service." This structure may be used
+to mandate the name of the returned port right and/or the port's "quality
+of service" attribute. The current implementation recognizes two such
+attributes: regular and realtime.
+<dt> <var>name</var>
+<dd>
+[out scalar] The task's name for the port right. This can be any name
+that wasn't in use.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_allocate_full</strong> function creates a new right in the
+specified task. The new right's name is returned via the <var>name</var> parameter.
+The new port supports the full set of Mach port semantics (i.e. no_more_senders
+detection will work, if requested).
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port
+name parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_NO_SPACE</strong>
+<dd>
+There was no room in task's IPC name space for another right.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>,
+<a href="mach_port_allocate.html"><strong>mach_port_allocate_qos</strong></a>,
+<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>,
+<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>,
+<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>,
+<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>.
+<p>
+Structures:
+<a href="mach_port_qos.html"><strong>mach_port_qos</strong></a>.
-<h2>mach_port_allocate_name</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Create a port right with the caller-specified name.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_allocate_name</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_right_t</strong> <var>right</var>,
\r <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task acquiring the port right.
\r<p>
\r<dt> <var>right</var>
\r<dd>
\r[in scalar]
\rThe kind of entity to be created. This is one of the following:
\r<dl>
\r<p>
\r<dt> <strong>MACH_PORT_RIGHT_RECEIVE</strong>
\r<dd>
\r<strong>mach_port_allocate_name</strong> creates a port. The new port is
\rnot a member of any port set. It doesn't have any extant send
\ror send-once rights. Its make-send count is zero, its sequence
\rnumber is zero, its queue limit is <strong>MACH_PORT_QLIMIT_DEFAULT</strong>,
\rand it has no queued messages.
\r<var>name</var> denotes the receive right for the new port.
\r<var>task</var> does not hold send rights for the new port, only the
\rreceive right. <strong>mach_port_insert_right</strong> and
\r<strong>mach_port_extract_right</strong> can be used to convert the receive right into a
\rcombined send/receive right.
\r<p>
\r<dt> <strong>MACH_PORT_RIGHT_PORT_SET</strong>
\r<dd>
\r<strong>mach_port_allocate_name</strong> creates a port set. The new port
\rset has no members.
\r<p>
\r<dt> <strong>MACH_PORT_RIGHT_DEAD_NAME</strong>
\r<dd>
\r<strong>mach_port_allocate_name</strong> creates a dead name. The new
\rdead name has one user reference.
\r</dl>
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\rThe task's name for the port right. name must not already be
\rin use for some right, and it can't be the reserved values
\r<strong>MACH_PORT_NULL</strong> and <strong>MACH_PORT_DEAD</strong>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_allocate_name</strong> function creates a new
\rright in the specified
\rtask, with a specified name for the new right.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_NAME_EXISTS</strong>
\r<dd>
\rname was already in use for a port right.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>,
\r<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>,
\r<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>,
\r<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_allocate_name</h2>
+<hr>
+<p>
+<strong>Function</strong> - Create a port right with the caller-specified name.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_allocate_name</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_right_t</strong> <var>right</var>,
+ <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task acquiring the port right.
+<p>
+<dt> <var>right</var>
+<dd>
+[in scalar]
+The kind of entity to be created. This is one of the following:
+<dl>
+<p>
+<dt> <strong>MACH_PORT_RIGHT_RECEIVE</strong>
+<dd>
+<strong>mach_port_allocate_name</strong> creates a port. The new port is
+not a member of any port set. It doesn't have any extant send
+or send-once rights. Its make-send count is zero, its sequence
+number is zero, its queue limit is <strong>MACH_PORT_QLIMIT_DEFAULT</strong>,
+and it has no queued messages.
+<var>name</var> denotes the receive right for the new port.
+<var>task</var> does not hold send rights for the new port, only the
+receive right. <strong>mach_port_insert_right</strong> and
+<strong>mach_port_extract_right</strong> can be used to convert the receive right into a
+combined send/receive right.
+<p>
+<dt> <strong>MACH_PORT_RIGHT_PORT_SET</strong>
+<dd>
+<strong>mach_port_allocate_name</strong> creates a port set. The new port
+set has no members.
+<p>
+<dt> <strong>MACH_PORT_RIGHT_DEAD_NAME</strong>
+<dd>
+<strong>mach_port_allocate_name</strong> creates a dead name. The new
+dead name has one user reference.
+</dl>
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+The task's name for the port right. name must not already be
+in use for some right, and it can't be the reserved values
+<strong>MACH_PORT_NULL</strong> and <strong>MACH_PORT_DEAD</strong>.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_allocate_name</strong> function creates a new
+right in the specified
+task, with a specified name for the new right.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_NAME_EXISTS</strong>
+<dd>
+name was already in use for a port right.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>,
+<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>,
+<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>,
+<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>.
-<h2>mach_port_allocate_qos</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Allocate a port with specified "quality of service."
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_allocate_qos</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_right_t</strong> <var>right</var>,
\r <strong>mach_port_qos_t</strong> <var>qos</var>,
\r <strong>mach_port_name_t*</strong> <var>name</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right] The task acquiring the port right to the allocated port.
\r<dt> <var>right</var>
\r<dd>
\r[in scalar] The type of port right to map to the allocated port.
\r<dt> <var>qos</var>
\r<dd>
\r[pointer to an in/out structure] Structure used to specify
\rthe desired "quality of service." This structure indicates whether
\r or not the caller is providing a name for the port and whether or not
\r the port will exhibit realtime behavior.
\r<dt> <var>name</var>
\r<dd>
\r[in/out scalar] The name of the installed port right, either specified by the
\r caller or chosen by the system.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_allocate_qos</strong> function allocates a port with
\rcaller-specified "quality of service" characteristics with or without a
\rcaller-specified name; in other words, the caller may specify a desired name
\ror it may let the kernel generate the name. The new port is capable of
\rsupporting full Mach port semantics (i.e no-more-senders notification can be
\rrequested on the port).
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port
\rname parameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<dt> <strong>KERN_NO_SPACE</strong>
\r<dd>
\rThere was no room in task's IPC name space for another right.
\r<dt> <strong>KERN_INVALID_VALUE</strong>
\r<dd>
\rThe type of right specified by <var>right</var> is either invalid or conflicts
\rwith the requested "quality of service" as specified via <var>qos</var>.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>,
\r<a href="mach_port_allocate_full.html"><strong>mach_port_allocate_full</strong></a>,
\r<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>,
\r<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>,
\r<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>,
\r<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>.
\r<p>
\rStructures:
\r<a href="mach_port_qos.html"><strong>mach_port_qos</strong></a>.
\ No newline at end of file
+<h2>mach_port_allocate_qos</h2>
+<hr>
+<p>
+<strong>Function</strong> - Allocate a port with specified "quality of service."
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_allocate_qos</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_right_t</strong> <var>right</var>,
+ <strong>mach_port_qos_t</strong> <var>qos</var>,
+ <strong>mach_port_name_t*</strong> <var>name</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>task</var>
+<dd>
+[in task send right] The task acquiring the port right to the allocated port.
+<dt> <var>right</var>
+<dd>
+[in scalar] The type of port right to map to the allocated port.
+<dt> <var>qos</var>
+<dd>
+[pointer to an in/out structure] Structure used to specify
+the desired "quality of service." This structure indicates whether
+ or not the caller is providing a name for the port and whether or not
+ the port will exhibit realtime behavior.
+<dt> <var>name</var>
+<dd>
+[in/out scalar] The name of the installed port right, either specified by the
+ caller or chosen by the system.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_allocate_qos</strong> function allocates a port with
+caller-specified "quality of service" characteristics with or without a
+caller-specified name; in other words, the caller may specify a desired name
+or it may let the kernel generate the name. The new port is capable of
+supporting full Mach port semantics (i.e no-more-senders notification can be
+requested on the port).
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port
+name parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<dt> <strong>KERN_NO_SPACE</strong>
+<dd>
+There was no room in task's IPC name space for another right.
+<dt> <strong>KERN_INVALID_VALUE</strong>
+<dd>
+The type of right specified by <var>right</var> is either invalid or conflicts
+with the requested "quality of service" as specified via <var>qos</var>.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>,
+<a href="mach_port_allocate_full.html"><strong>mach_port_allocate_full</strong></a>,
+<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>,
+<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>,
+<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>,
+<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>.
+<p>
+Structures:
+<a href="mach_port_qos.html"><strong>mach_port_qos</strong></a>.
\ No newline at end of file
-<h2>mach_port_deallocate</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Decrement the target port right's user reference count.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_deallocate</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task holding the right.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\rThe task's name for the right.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_deallocate</strong> function releases a user reference
\rfor a right. It is
\ran alternate form of <strong>mach_port_mod_refs</strong> that allows
\ra task to release a user
\rreference for a send or send-once right without failing if the
\rport has died and
\rthe right is now actually a dead name.
\r<p>
\rIf <var>name</var> denotes a dead name, send right, or send-once right,
\rthen the right loses
\rone user reference. If it only had one user reference, then
\rthe right is destroyed.
\rIf <var>name</var> does not denote an element in the port name space, the
\rfunction returns
\rsuccess.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_RIGHT</strong>
\r<dd>
\rThe <var>name</var> parameter denoted an invalid right.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>,
\r<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>,
\r<a href="mach_port_mod_refs.html"><strong>mach_port_mod_refs</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_deallocate</h2>
+<hr>
+<p>
+<strong>Function</strong> - Decrement the target port right's user reference count.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_deallocate</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task holding the right.
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+The task's name for the right.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_deallocate</strong> function releases a user reference
+for a right. It is
+an alternate form of <strong>mach_port_mod_refs</strong> that allows
+a task to release a user
+reference for a send or send-once right without failing if the
+port has died and
+the right is now actually a dead name.
+<p>
+If <var>name</var> denotes a dead name, send right, or send-once right,
+then the right loses
+one user reference. If it only had one user reference, then
+the right is destroyed.
+If <var>name</var> does not denote an element in the port name space, the
+function returns
+success.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_RIGHT</strong>
+<dd>
+The <var>name</var> parameter denoted an invalid right.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>,
+<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>,
+<a href="mach_port_mod_refs.html"><strong>mach_port_mod_refs</strong></a>.
-<h2>mach_port_destroy</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Deallocate all port rights associated with specified name.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_destroy</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task holding the right.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\rThe task's name for the right.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_destroy</strong> function de-allocates all rights
\rdenoted by a name.
\rThe name becomes immediately available for reuse.
\r<p>
\rFor most purposes,
\r<strong>mach_port_mod_refs</strong> and <strong>mach_port_deallocate</strong> are
\rpreferable.
\r<p>
\rIf <var>name</var> denotes a port set, then all members of the port set are implicitly
\rremoved from the port set.
\r<p>
\rIf <var>name</var> denotes a receive right that is a member of a port set,
\rthe receive right is
\rimplicitly removed from the port set. Remaining messages queued to the port
\rare destroyed and extant send and send-once rights turn into dead names. If
\rthose send and send-once rights have dead-name requests registered, then
\rdead-name notifications are generated for them.
\r<p>
\rIf <var>name</var> denotes a send-once right, then
\rthe destruction of the send-once right
\rproduces a send-once notification for the port.
\r<p>
\rIf <var>name</var> denotes a send-once, send, and/or receive right, and
\rit has a dead-name
\rrequest registered, then a port-deleted notification is generated
\r(as opposed to a
\rdead-name notification).
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_NAME</strong>
\r<dd>
\rThe <var>name</var> parameter did not denote a right.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>,
\r<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>,
\r<a href="mach_port_mod_refs.html"><strong>mach_port_mod_refs</strong></a>,
\r<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>,
\r<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_destroy</h2>
+<hr>
+<p>
+<strong>Function</strong> - Deallocate all port rights associated with specified name.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_destroy</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_name_t</strong> <var>name</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task holding the right.
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+The task's name for the right.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_destroy</strong> function de-allocates all rights
+denoted by a name.
+The name becomes immediately available for reuse.
+<p>
+For most purposes,
+<strong>mach_port_mod_refs</strong> and <strong>mach_port_deallocate</strong> are
+preferable.
+<p>
+If <var>name</var> denotes a port set, then all members of the port set are implicitly
+removed from the port set.
+<p>
+If <var>name</var> denotes a receive right that is a member of a port set,
+the receive right is
+implicitly removed from the port set. Remaining messages queued to the port
+are destroyed and extant send and send-once rights turn into dead names. If
+those send and send-once rights have dead-name requests registered, then
+dead-name notifications are generated for them.
+<p>
+If <var>name</var> denotes a send-once right, then
+the destruction of the send-once right
+produces a send-once notification for the port.
+<p>
+If <var>name</var> denotes a send-once, send, and/or receive right, and
+it has a dead-name
+request registered, then a port-deleted notification is generated
+(as opposed to a
+dead-name notification).
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_NAME</strong>
+<dd>
+The <var>name</var> parameter did not denote a right.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>,
+<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>,
+<a href="mach_port_mod_refs.html"><strong>mach_port_mod_refs</strong></a>,
+<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>,
+<a href="MP_request_notification.html"><strong>mach_port_request_notification</strong></a>.
-<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
\r<html>
\r<head>
\r <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
\r <meta name="GENERATOR" content="Mozilla/4.73 (Macintosh; U; PPC) [Netscape]">
\r <title>mach_port_insert_member.html</title>
\r</head>
\r<body>
\r\r<h2>
\rmach_port_extract_member</h2>
\r\r<hr>
\r<p><b>Function</b> - Extract the specified receive right from the specified
\rport set.
\r<h3>
\rSYNOPSIS</h3>
\r\r<pre><b>kern_return_t mach_port_extract_member
\r</b> <b>(ipc_space_t</b> <i>task</i>,
\r <b>mach_port_name_t</b> <i>member</i>,
\r <b>mach_port_name_t</b> set<b>);</b></pre>
\r\r<h3>
\rPARAMETERS</h3>
\r\r<dl>
\r<dt>
\r<i>task</i></dt>
\r\r<dd>
\r[in task send right] The task holding the port set and receive right.</dd>
\r\r<dt>
\r<i>member</i></dt>
\r\r<dd>
\r[in scalar] The task's name for the receive right.</dd>
\r\r<dt>
\r<i>set</i></dt>
\r\r<dd>
\r[in scalar] The task's name for the port set.</dd>
\r</dl>
\r\r<h3>
\rDESCRIPTION</h3>
\rThe <b>mach_port_extract_member</b> function removes a receive right from
\ra port set. Any other port set memberships for the receive right are not
\raffected. A receive right can be a member of any number of portsets
\rsimultaneously.
\r<h3>
\rNOTES</h3>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>
\rRETURN VALUES</h3>
\r\r<dl>
\r<dt>
\r<b>KERN_INVALID_NAME</b></dt>
\r\r<dd>
\r<i>member</i> or <i>set</i> did not denote a right.</dd>
\r\r<dt>
\r<b>KERN_INVALID_RIGHT</b></dt>
\r\r<dd>
\r<i>member</i> denoted a right, but not a receive right, or <i>set</i> denoted
\ra right, but not a port set.</dd>
\r\r<dt>
\r<b>KERN_NOT_IN_SET</b></dt>
\r\r<dd>
\r<i>member</i> was not in <i>set</i>.</dd>
\r</dl>
\r\r<h3>
\rRELATED INFORMATION</h3>
\rFunctions:
\r<b><a href="../HTML/mach_port_extract_member.html">mach_port_extract_member</a></b>,
\r<b><a href="../HTML/mach_port_move_member.html">mach_port_move_member</a></b>,
\r<b><a href="../HTML/mach_port_get_set_status.html">mach_port_get_set_status</a></b>,
\r<b><a href="../HTML/mach_port_get_attributes.html">mach_port_get_attributes</a></b>.
\r</body>
\r</html>
\r\ No newline at end of file
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <meta name="GENERATOR" content="Mozilla/4.73 (Macintosh; U; PPC) [Netscape]">
+ <title>mach_port_insert_member.html</title>
+</head>
+<body>
+
+<h2>
+mach_port_extract_member</h2>
+
+<hr>
+<p><b>Function</b> - Extract the specified receive right from the specified
+port set.
+<h3>
+SYNOPSIS</h3>
+
+<pre><b>kern_return_t mach_port_extract_member
+</b> <b>(ipc_space_t</b> <i>task</i>,
+ <b>mach_port_name_t</b> <i>member</i>,
+ <b>mach_port_name_t</b> set<b>);</b></pre>
+
+<h3>
+PARAMETERS</h3>
+
+<dl>
+<dt>
+<i>task</i></dt>
+
+<dd>
+[in task send right] The task holding the port set and receive right.</dd>
+
+<dt>
+<i>member</i></dt>
+
+<dd>
+[in scalar] The task's name for the receive right.</dd>
+
+<dt>
+<i>set</i></dt>
+
+<dd>
+[in scalar] The task's name for the port set.</dd>
+</dl>
+
+<h3>
+DESCRIPTION</h3>
+The <b>mach_port_extract_member</b> function removes a receive right from
+a port set. Any other port set memberships for the receive right are not
+affected. A receive right can be a member of any number of portsets
+simultaneously.
+<h3>
+NOTES</h3>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>
+RETURN VALUES</h3>
+
+<dl>
+<dt>
+<b>KERN_INVALID_NAME</b></dt>
+
+<dd>
+<i>member</i> or <i>set</i> did not denote a right.</dd>
+
+<dt>
+<b>KERN_INVALID_RIGHT</b></dt>
+
+<dd>
+<i>member</i> denoted a right, but not a receive right, or <i>set</i> denoted
+a right, but not a port set.</dd>
+
+<dt>
+<b>KERN_NOT_IN_SET</b></dt>
+
+<dd>
+<i>member</i> was not in <i>set</i>.</dd>
+</dl>
+
+<h3>
+RELATED INFORMATION</h3>
+Functions:
+<b><a href="../HTML/mach_port_extract_member.html">mach_port_extract_member</a></b>,
+<b><a href="../HTML/mach_port_move_member.html">mach_port_move_member</a></b>,
+<b><a href="../HTML/mach_port_get_set_status.html">mach_port_get_set_status</a></b>,
+<b><a href="../HTML/mach_port_get_attributes.html">mach_port_get_attributes</a></b>.
+</body>
+</html>
-<h2>mach_port_extract_right</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Remove the specified right from the target task and return it to the caller.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_extract_right</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_name_t</strong> <var>name</var>,
\r <strong>mach_msg_type_name_t</strong> <var>desired_type</var>,
\r <strong>mach_port_poly_t</strong> <var>*right</var>,
\r <strong>mach_msg_type_name_</strong> <var>*acquired_type</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task holding the port right.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\rThe task's name for the port right.
\r<p>
\r<dt> <var>desired_type</var>
\r<dd>
\r[in scalar]
\rIPC type, specifying how the right should be extracted.
\r<p>
\r<dt> <var>right</var>
\r<dd>
\r[out random right]
\rThe extracted right.
\r<p>
\r<dt> <var>acquired_type</var>
\r<dd>
\r[out scalar]
\rThe type of the extracted right.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_extract_right</strong> function extracts a port
\rright from the target
\rtask and returns it to the caller as if the task sent the right
\rvoluntarily, using
\r<var>desired_type</var> as the disposition for the right. See <strong>mach_msg</strong>.
\r<p>
\rThe returned value of <var>acquired_type</var> will be
\r<strong>MACH_MSG_TYPE_PORT_SEND</strong> if a send right is extracted,
\r<strong>MACH_MSG_TYPE_PORT_RECEIVE</strong> if a
\rreceive right is extracted, and <strong>MACH_MSG_TYPE_PORT_SEND_ONCE</strong> if a
\rsend-once right is extracted.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_NAME</strong>
\r<dd>
\r<var>name</var> did not denote a right.
\r<p>
\r<dt> <strong>KERN_INVALID_RIGHT</strong>
\r<dd>
\r<var>name</var> denoted an invalid right.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>,
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_extract_right</h2>
+<hr>
+<p>
+<strong>Function</strong> - Remove the specified right from the target task and return it to the caller.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_extract_right</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_name_t</strong> <var>name</var>,
+ <strong>mach_msg_type_name_t</strong> <var>desired_type</var>,
+ <strong>mach_port_poly_t</strong> <var>*right</var>,
+ <strong>mach_msg_type_name_</strong> <var>*acquired_type</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task holding the port right.
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+The task's name for the port right.
+<p>
+<dt> <var>desired_type</var>
+<dd>
+[in scalar]
+IPC type, specifying how the right should be extracted.
+<p>
+<dt> <var>right</var>
+<dd>
+[out random right]
+The extracted right.
+<p>
+<dt> <var>acquired_type</var>
+<dd>
+[out scalar]
+The type of the extracted right.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_extract_right</strong> function extracts a port
+right from the target
+task and returns it to the caller as if the task sent the right
+voluntarily, using
+<var>desired_type</var> as the disposition for the right. See <strong>mach_msg</strong>.
+<p>
+The returned value of <var>acquired_type</var> will be
+<strong>MACH_MSG_TYPE_PORT_SEND</strong> if a send right is extracted,
+<strong>MACH_MSG_TYPE_PORT_RECEIVE</strong> if a
+receive right is extracted, and <strong>MACH_MSG_TYPE_PORT_SEND_ONCE</strong> if a
+send-once right is extracted.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_NAME</strong>
+<dd>
+<var>name</var> did not denote a right.
+<p>
+<dt> <strong>KERN_INVALID_RIGHT</strong>
+<dd>
+<var>name</var> denoted an invalid right.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_insert_right.html"><strong>mach_port_insert_right</strong></a>,
+<a href="mach_msg.html"><strong>mach_msg</strong></a>.
-<h2>mach_port_get_attributes</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return information about target port as specified by the caller.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_get_attributes</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_name_t</strong> <var>name</var>,
\r <strong>mach_port_flavor_t</strong> <var>flavor</var>,
\r <strong>mach_port_info_t</strong> <var>port_info</var>,
\r <strong>mach_msg_type_number_t</strong> <var>*port_info_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task holding a receive right to the port in
\rquestion.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\r<var>task</var>'s name for the port.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of information to be returned. Valid values are:
\r<dl>
\r<p>
\r<dt> <strong>MACH_PORT_LIMITS_INFO</strong>
\r<dd>
\rReturns the resource limits for the port. The declaration of
\rthis data is found in structure <strong>mach_port_limits</strong>.
\r<p>
\r<dt> <strong>MACH_PORT_RECEIVE_STATUS</strong>
\r<dd>
\rReturns random information about the rights and messages
\rassociated with the port. The declaration of this data is found in
\rstructure <strong>mach_port_status</strong>.
\r</dl>
\r<p>
\r<dt> <var>port_info</var>
\r<dd>
\r[out structure]
\rInformation about the specified port.
\r<p>
\r<dt> <var>port_info_count</var>
\r<dd>
\r[in/out scalar]
\rOn input, the maximum size of the buffer; on output, the
\rsize returned (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_get_attributes</strong> function returns an information
\rstructure of type <var>flavor</var>.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter in the <strong>MACH_PORT_RECEIVE_STATUS</strong> structure return.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_NAME</strong>
\r<dd>
\r<var>name</var> did not denote a right.
\r<p>
\r<dt> <strong>KERN_INVALID_RIGHT</strong>
\r<dd>
\r<var>name</var> denoted a right, but not a receive right.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>,
\r<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>,
\r<a href="mach_port_set_attributes.html"><strong>mach_port_set_attributes</strong></a>.
\r<p>
\rData Structures:
\r<a href="mach_port_limits.html"><strong>mach_port_limits</strong></a>,
\r<a href="mach_port_status.html"><strong>mach_port_status</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_get_attributes</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return information about target port as specified by the caller.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_get_attributes</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_name_t</strong> <var>name</var>,
+ <strong>mach_port_flavor_t</strong> <var>flavor</var>,
+ <strong>mach_port_info_t</strong> <var>port_info</var>,
+ <strong>mach_msg_type_number_t</strong> <var>*port_info_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task holding a receive right to the port in
+question.
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+<var>task</var>'s name for the port.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of information to be returned. Valid values are:
+<dl>
+<p>
+<dt> <strong>MACH_PORT_LIMITS_INFO</strong>
+<dd>
+Returns the resource limits for the port. The declaration of
+this data is found in structure <strong>mach_port_limits</strong>.
+<p>
+<dt> <strong>MACH_PORT_RECEIVE_STATUS</strong>
+<dd>
+Returns random information about the rights and messages
+associated with the port. The declaration of this data is found in
+structure <strong>mach_port_status</strong>.
+</dl>
+<p>
+<dt> <var>port_info</var>
+<dd>
+[out structure]
+Information about the specified port.
+<p>
+<dt> <var>port_info_count</var>
+<dd>
+[in/out scalar]
+On input, the maximum size of the buffer; on output, the
+size returned (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_get_attributes</strong> function returns an information
+structure of type <var>flavor</var>.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter in the <strong>MACH_PORT_RECEIVE_STATUS</strong> structure return.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_NAME</strong>
+<dd>
+<var>name</var> did not denote a right.
+<p>
+<dt> <strong>KERN_INVALID_RIGHT</strong>
+<dd>
+<var>name</var> denoted a right, but not a receive right.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>,
+<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>,
+<a href="mach_port_set_attributes.html"><strong>mach_port_set_attributes</strong></a>.
+<p>
+Data Structures:
+<a href="mach_port_limits.html"><strong>mach_port_limits</strong></a>,
+<a href="mach_port_status.html"><strong>mach_port_status</strong></a>.
-<h2>mach_port_get_refs</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return the current count of user references on the target port right.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_get_refs</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_name_t</strong> <var>name</var>,
\r <strong>mach_port_right_t</strong> <var>right</var>,
\r <strong>mach_port_urefs_t</strong> <var>*refs</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task holding the right.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\rThe task's name for the right.
\r<p>
\r<dt> <var>right</var>
\r<dd>
\r[in scalar]
\rThe type of right/entity being examined:
\r<dl>
\r<p>
\r<dt> <dd>
\r<strong>MACH_PORT_RIGHT_SEND</strong>
\r<p>
\r<dt> <dd>
\r<strong>MACH_PORT_RIGHT_RECEIVE</strong>
\r<p>
\r<dt> <dd>
\r<strong>MACH_PORT_RIGHT_SEND_ONCE</strong>
\r<p>
\r<dt> <dd>
\r<strong>MACH_PORT_RIGHT_PORT_SET</strong>
\r<p>
\r<dt> <dd>
\r<strong>MACH_PORT_RIGHT_DEAD_NAME</strong>
\r</dl>
\r<p>
\r<dt> <var>refs</var>
\r<dd>
\r[out scalar]
\rNumber of user references.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_get_refs</strong> function returns the number
\rof user references a task
\rhas for a right.
\r<p>
\rIf <var>name</var> denotes a right, but not the type of right specified,
\rthen zero is returned.
\rOtherwise a positive number of user references is returned. Note a name may
\rsimultaneously denote send and receive rights. The number of references for
\rsend-once rights is always one.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_NAME</strong>
\r<dd>
\r<var>name</var> did not denote a right.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_mod_refs.html"><strong>mach_port_mod_refs</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_get_refs</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return the current count of user references on the target port right.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_get_refs</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_name_t</strong> <var>name</var>,
+ <strong>mach_port_right_t</strong> <var>right</var>,
+ <strong>mach_port_urefs_t</strong> <var>*refs</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task holding the right.
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+The task's name for the right.
+<p>
+<dt> <var>right</var>
+<dd>
+[in scalar]
+The type of right/entity being examined:
+<dl>
+<p>
+<dt> <dd>
+<strong>MACH_PORT_RIGHT_SEND</strong>
+<p>
+<dt> <dd>
+<strong>MACH_PORT_RIGHT_RECEIVE</strong>
+<p>
+<dt> <dd>
+<strong>MACH_PORT_RIGHT_SEND_ONCE</strong>
+<p>
+<dt> <dd>
+<strong>MACH_PORT_RIGHT_PORT_SET</strong>
+<p>
+<dt> <dd>
+<strong>MACH_PORT_RIGHT_DEAD_NAME</strong>
+</dl>
+<p>
+<dt> <var>refs</var>
+<dd>
+[out scalar]
+Number of user references.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_get_refs</strong> function returns the number
+of user references a task
+has for a right.
+<p>
+If <var>name</var> denotes a right, but not the type of right specified,
+then zero is returned.
+Otherwise a positive number of user references is returned. Note a name may
+simultaneously denote send and receive rights. The number of references for
+send-once rights is always one.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_NAME</strong>
+<dd>
+<var>name</var> did not denote a right.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_mod_refs.html"><strong>mach_port_mod_refs</strong></a>.
-<h2>mach_port_get_set_status</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return the port right names contained in the target port set.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_get_set_status</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_name_t</strong> <var>name</var>,
\r <strong>mach_port_name_array_t</strong> <var>*members</var>,
\r <strong>task</strong> <var>count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task holding the port set.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\rThe task's name for the port set.
\r<p>
\r<dt> <var>members</var>
\r<dd>
\r[out pointer to dynamic array of <var>mach_port_name_t</var>]
\rThe task's names
\rfor the port set's members.
\r<p>
\r<dt> <var>count</var>
\r<dd>
\r[out scalar]
\rThe number of member names returned.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_get_set_status</strong> function returns the individual port
\rright names for all port rights contained in the specified port set.
\rThe <var>members</var> parameter is an array that is automatically
\rallocated when the reply message is received. Note that
\r<strong>vm_deallocate</strong> should be used to free the array.
\r<p>
\rNote that this interface, unlike others such as <strong>task_threads</strong>,
\rreturns a collection of port right names, NOT a collection of port rights themselves.
\rIn other words, this function does not insert port rights into the caller's
\rport right name space; consequently, a call to <strong>mach_port_get_set_status</strong>
\rdoes not affect the reference count of each port right within the target port set.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter and the returned port names.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_NAME</strong>
\r<dd>
\r<var>name</var> did not denote a right.
\r<p>
\r<dt> <strong>KERN_INVALID_RIGHT</strong>
\r<dd>
\r<var>name</var> denoted a right, but not a port set.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_insert_member.html"><strong>mach_port_insert_member</strong></a>,
\r<a href="mach_port_extract_member.html"><strong>mach_port_extract_member</strong></a>,
\r<a href="mach_port_move_member.html"><strong>mach_port_move_member</strong></a>,
\r<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_get_set_status</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return the port right names contained in the target port set.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_get_set_status</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_name_t</strong> <var>name</var>,
+ <strong>mach_port_name_array_t</strong> <var>*members</var>,
+ <strong>task</strong> <var>count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task holding the port set.
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+The task's name for the port set.
+<p>
+<dt> <var>members</var>
+<dd>
+[out pointer to dynamic array of <var>mach_port_name_t</var>]
+The task's names
+for the port set's members.
+<p>
+<dt> <var>count</var>
+<dd>
+[out scalar]
+The number of member names returned.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_get_set_status</strong> function returns the individual port
+right names for all port rights contained in the specified port set.
+The <var>members</var> parameter is an array that is automatically
+allocated when the reply message is received. Note that
+<strong>vm_deallocate</strong> should be used to free the array.
+<p>
+Note that this interface, unlike others such as <strong>task_threads</strong>,
+returns a collection of port right names, NOT a collection of port rights themselves.
+In other words, this function does not insert port rights into the caller's
+port right name space; consequently, a call to <strong>mach_port_get_set_status</strong>
+does not affect the reference count of each port right within the target port set.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter and the returned port names.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_NAME</strong>
+<dd>
+<var>name</var> did not denote a right.
+<p>
+<dt> <strong>KERN_INVALID_RIGHT</strong>
+<dd>
+<var>name</var> denoted a right, but not a port set.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_insert_member.html"><strong>mach_port_insert_member</strong></a>,
+<a href="mach_port_extract_member.html"><strong>mach_port_extract_member</strong></a>,
+<a href="mach_port_move_member.html"><strong>mach_port_move_member</strong></a>,
+<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>.
-<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
\r<html>
\r<head>
\r <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
\r <meta name="GENERATOR" content="Mozilla/4.73 (Macintosh; U; PPC) [Netscape]">
\r <title>mach_port_insert_member.html</title>
\r</head>
\r<body>
\r\r<h2>
\rmach_port_insert_member</h2>
\r\r<hr>
\r<p><b>Function</b> - Move the specified receive right into or out of the
\rspecified port set.
\r<h3>
\rSYNOPSIS</h3>
\r\r<pre><b>kern_return_t mach_port_insert_member
\r</b> <b>(ipc_space_t</b> <i>task</i>,
\r <b>mach_port_name_t</b> <i>member</i>,
\r <b>mach_port_name_t</b> <i>set</i><b>);</b></pre>
\r\r<h3>
\rPARAMETERS</h3>
\r\r<dl>
\r<dt>
\r<i>task</i></dt>
\r\r<dd>
\r[in task send right] The task holding the port set and receive right.</dd>
\r\r<dt>
\r<i>member</i></dt>
\r\r<dd>
\r[in scalar] The task's name for the receive right.</dd>
\r\r<dt>
\r<i>set</i></dt>
\r\r<dd>
\r[in scalar] The task's name for the port set.</dd>
\r</dl>
\r\r<h3>
\rDESCRIPTION</h3>
\rThe <b>mach_port_insert_member</b> function adds a receive right to a port
\rset. If the receive right is already a member of another port set, that
\rrelationship is unafected by this operation. A receive right can
\rbe in multiple port sets simultaneously.
\r<h3>
\rNOTES</h3>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>
\rRETURN VALUES</h3>
\r\r<dl>
\r<dt>
\r<b>KERN_INVALID_NAME</b></dt>
\r\r<dd>
\r<i>member</i> or <i>set</i> did not denote a right.</dd>
\r\r<dt>
\r<b>KERN_INVALID_RIGHT</b></dt>
\r\r<dd>
\r<i>member</i> denoted a right, but not a receive right, or <i>set</i> denoted
\ra right, but not a port set.</dd>
\r</dl>
\r\r<h3>
\rRELATED INFORMATION</h3>
\rFunctions:
\r<b><a href="HTML/mach_port_extract_member.html">mach_port_extract_member</a></b>,
\r<b><a href="HTML/mach_port_move_member.html">mach_port_move_member</a></b>,
\r<b><a href="HTML/mach_port_get_set_status.html">mach_port_get_set_status</a></b>,
\r<b><a href="HTML/mach_port_get_attributes.html">mach_port_get_attributes</a></b>.
\r</body>
\r</html>
\r\ No newline at end of file
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <meta name="GENERATOR" content="Mozilla/4.73 (Macintosh; U; PPC) [Netscape]">
+ <title>mach_port_insert_member.html</title>
+</head>
+<body>
+
+<h2>
+mach_port_insert_member</h2>
+
+<hr>
+<p><b>Function</b> - Move the specified receive right into or out of the
+specified port set.
+<h3>
+SYNOPSIS</h3>
+
+<pre><b>kern_return_t mach_port_insert_member
+</b> <b>(ipc_space_t</b> <i>task</i>,
+ <b>mach_port_name_t</b> <i>member</i>,
+ <b>mach_port_name_t</b> <i>set</i><b>);</b></pre>
+
+<h3>
+PARAMETERS</h3>
+
+<dl>
+<dt>
+<i>task</i></dt>
+
+<dd>
+[in task send right] The task holding the port set and receive right.</dd>
+
+<dt>
+<i>member</i></dt>
+
+<dd>
+[in scalar] The task's name for the receive right.</dd>
+
+<dt>
+<i>set</i></dt>
+
+<dd>
+[in scalar] The task's name for the port set.</dd>
+</dl>
+
+<h3>
+DESCRIPTION</h3>
+The <b>mach_port_insert_member</b> function adds a receive right to a port
+set. If the receive right is already a member of another port set, that
+relationship is unafected by this operation. A receive right can
+be in multiple port sets simultaneously.
+<h3>
+NOTES</h3>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>
+RETURN VALUES</h3>
+
+<dl>
+<dt>
+<b>KERN_INVALID_NAME</b></dt>
+
+<dd>
+<i>member</i> or <i>set</i> did not denote a right.</dd>
+
+<dt>
+<b>KERN_INVALID_RIGHT</b></dt>
+
+<dd>
+<i>member</i> denoted a right, but not a receive right, or <i>set</i> denoted
+a right, but not a port set.</dd>
+</dl>
+
+<h3>
+RELATED INFORMATION</h3>
+Functions:
+<b><a href="HTML/mach_port_extract_member.html">mach_port_extract_member</a></b>,
+<b><a href="HTML/mach_port_move_member.html">mach_port_move_member</a></b>,
+<b><a href="HTML/mach_port_get_set_status.html">mach_port_get_set_status</a></b>,
+<b><a href="HTML/mach_port_get_attributes.html">mach_port_get_attributes</a></b>.
+</body>
+</html>
-<h2>mach_port_insert_right</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Insert the specified port right into the target task.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_insert_right</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_name_t</strong> <var>name</var>,
\r <strong>mach_port_poly_t</strong> <var>right</var>,
\r <strong>mach_msg_type_name_t</strong> <var>right_type</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task which gets the caller's right.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\rThe name by which <var>task</var> will know the right.
\r<p>
\r<dt> <var>right</var>
\r<dd>
\r[in random right]
\rThe port right.
\r<p>
\r<dt> <var>right_type</var>
\r<dd>
\r[in scalar]
\rIPC type of the sent right; e.g.,
\r<strong>MACH_MSG_TYPE_COPY_SEND</strong> or <strong>MACH_MSG_TYPE_MOVE_RECEIVE</strong>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_insert_right</strong> function inserts into <var>task</var>
\rthe caller's right for a
\rport, using a specified name for the right in the target task.
\r<p>
\rThe specified <var>name</var> can't be one of the reserved values <strong>MACH_PORT_NULL</strong>
\ror <strong>MACH_PORT_DEAD</strong>. The <var>right</var> can't be <strong>MACH_PORT_NULL</strong> or
\r<strong>MACH_PORT_DEAD</strong>.
\r<p>
\rThe argument <var>right_type</var> specifies a right to be inserted and how that right
\rshould be extracted from the caller. It should be a value appropriate for
\r<strong>mach_msg</strong>.
\r<p>
\rIf <var>right_type</var> is <strong>MACH_MSG_TYPE_MAKE_SEND</strong>, <strong>MACH_MSG_TYPE_MOVE_SEND</strong>,
\ror
\r<strong>MACH_MSG_TYPE_COPY_SEND</strong>, then a send right is inserted. If the target
\ralready holds send or receive rights for the port, then <var>name</var>
\rshould denote those rights in the target. Otherwise, <var>name</var> should
\rbe unused in
\rthe target. If the target already has send rights, then those
\rsend rights gain an
\radditional user reference. Otherwise, the target gains a send
\rright, with a user
\rreference count of one.
\r<p>
\rIf <var>right_type</var> is <strong>MACH_MSG_TYPE_MAKE_SEND_ONCE</strong> or
\r<strong>MACH_MSG_TYPE_MOVE_SEND_ONCE</strong>, then a send-once right is inserted.
\rThe <var>name</var> should be unused in the target. The
\rtarget gains a send-once right.
\r<p>
\rIf <var>right_type</var> is <strong>MACH_MSG_TYPE_MOVE_RECEIVE</strong>, then a receive right is
\rinserted. If the target already holds send rights for the port,
\rthen <var>name</var> should
\rdenote those rights in the target. Otherwise, <var>name</var> should be
\runused in the target.
\rThe receive right is moved into the target task.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_NAME_EXISTS</strong>
\r<dd>
\r<var>name</var> already denoted a right.
\r<p>
\r<dt> <strong>KERN_INVALID_CAPABILITY</strong>
\r<dd>
\r<var>right</var> was null or dead.
\r<p>
\r<dt> <strong>KERN_UREFS_OVERFLOW</strong>
\r<dd>
\rInserting the right would overflow <var>name</var>'s user-reference count.
\r<p>
\r<dt> <strong>KERN_RIGHT_EXISTS</strong>
\r<dd>
\r<var>task</var> already had rights for the port, with a different name.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>,
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_insert_right</h2>
+<hr>
+<p>
+<strong>Function</strong> - Insert the specified port right into the target task.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_insert_right</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_name_t</strong> <var>name</var>,
+ <strong>mach_port_poly_t</strong> <var>right</var>,
+ <strong>mach_msg_type_name_t</strong> <var>right_type</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task which gets the caller's right.
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+The name by which <var>task</var> will know the right.
+<p>
+<dt> <var>right</var>
+<dd>
+[in random right]
+The port right.
+<p>
+<dt> <var>right_type</var>
+<dd>
+[in scalar]
+IPC type of the sent right; e.g.,
+<strong>MACH_MSG_TYPE_COPY_SEND</strong> or <strong>MACH_MSG_TYPE_MOVE_RECEIVE</strong>.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_insert_right</strong> function inserts into <var>task</var>
+the caller's right for a
+port, using a specified name for the right in the target task.
+<p>
+The specified <var>name</var> can't be one of the reserved values <strong>MACH_PORT_NULL</strong>
+or <strong>MACH_PORT_DEAD</strong>. The <var>right</var> can't be <strong>MACH_PORT_NULL</strong> or
+<strong>MACH_PORT_DEAD</strong>.
+<p>
+The argument <var>right_type</var> specifies a right to be inserted and how that right
+should be extracted from the caller. It should be a value appropriate for
+<strong>mach_msg</strong>.
+<p>
+If <var>right_type</var> is <strong>MACH_MSG_TYPE_MAKE_SEND</strong>, <strong>MACH_MSG_TYPE_MOVE_SEND</strong>,
+or
+<strong>MACH_MSG_TYPE_COPY_SEND</strong>, then a send right is inserted. If the target
+already holds send or receive rights for the port, then <var>name</var>
+should denote those rights in the target. Otherwise, <var>name</var> should
+be unused in
+the target. If the target already has send rights, then those
+send rights gain an
+additional user reference. Otherwise, the target gains a send
+right, with a user
+reference count of one.
+<p>
+If <var>right_type</var> is <strong>MACH_MSG_TYPE_MAKE_SEND_ONCE</strong> or
+<strong>MACH_MSG_TYPE_MOVE_SEND_ONCE</strong>, then a send-once right is inserted.
+The <var>name</var> should be unused in the target. The
+target gains a send-once right.
+<p>
+If <var>right_type</var> is <strong>MACH_MSG_TYPE_MOVE_RECEIVE</strong>, then a receive right is
+inserted. If the target already holds send rights for the port,
+then <var>name</var> should
+denote those rights in the target. Otherwise, <var>name</var> should be
+unused in the target.
+The receive right is moved into the target task.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_NAME_EXISTS</strong>
+<dd>
+<var>name</var> already denoted a right.
+<p>
+<dt> <strong>KERN_INVALID_CAPABILITY</strong>
+<dd>
+<var>right</var> was null or dead.
+<p>
+<dt> <strong>KERN_UREFS_OVERFLOW</strong>
+<dd>
+Inserting the right would overflow <var>name</var>'s user-reference count.
+<p>
+<dt> <strong>KERN_RIGHT_EXISTS</strong>
+<dd>
+<var>task</var> already had rights for the port, with a different name.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_extract_right.html"><strong>mach_port_extract_right</strong></a>,
+<a href="mach_msg.html"><strong>mach_msg</strong></a>.
-<h2>mach_port_limits</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Specifies a port's resource and message queue limits.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct mach_port_limits</strong>
\r<strong>{</strong>
\r <strong>mach_port_msgcount_t</strong> <var>queue_limit</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct mach_port_limits* mach_port_limits_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>queue_limit</var>
\r<dd>
\rNumber of messages allowed to be on the message queue at any given
\rtime. Attempts to queue more messages than this limit will block.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_limits</strong> structure defines various limits
\rgoverning the messages that can be sent through the port. (In the current
\rimplementation, the structure maintains only a queue length limit.)
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>,
\r<a href="mach_port_set_attributes.html"><strong>mach_port_set_attributes</strong></a>.
\r<p>
\rStructures:
\r<a href="mach_port_qos.html"><strong>mach_port_qos</strong></a>.
\r\r\ No newline at end of file
+<h2>mach_port_limits</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Specifies a port's resource and message queue limits.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct mach_port_limits</strong>
+<strong>{</strong>
+ <strong>mach_port_msgcount_t</strong> <var>queue_limit</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct mach_port_limits* mach_port_limits_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>queue_limit</var>
+<dd>
+Number of messages allowed to be on the message queue at any given
+time. Attempts to queue more messages than this limit will block.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_limits</strong> structure defines various limits
+governing the messages that can be sent through the port. (In the current
+implementation, the structure maintains only a queue length limit.)
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>,
+<a href="mach_port_set_attributes.html"><strong>mach_port_set_attributes</strong></a>.
+<p>
+Structures:
+<a href="mach_port_qos.html"><strong>mach_port_qos</strong></a>.
+
-<h2>mach_port_mod_refs</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Modify the specified port right's count of user references.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_mod_refs</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_name_t</strong> <var>name</var>,
\r <strong>mach_port_right_t</strong> <var>right</var>,
\r <strong>mach_port_delta_t</strong> <var>delta</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task holding the right.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\rThe task's name for the right.
\r<p>
\r<dt> <var>right</var>
\r<dd>
\r[in scalar]
\rThe type of right/entity being modified:
\r<dl>
\r<p>
\r<dt>
\r<strong>MACH_PORT_RIGHT_SEND</strong>
\r<p>
\r<dt>
\r<strong>MACH_PORT_RIGHT_RECEIVE</strong>
\r<p>
\r<dt>
\r<strong>MACH_PORT_RIGHT_SEND_ONCE</strong>
\r<p>
\r<dt>
\r<strong>MACH_PORT_RIGHT_PORT_SET</strong>
\r<p>
\r<dt>
\r<strong>MACH_PORT_RIGHT_DEAD_NAME</strong>
\r</dl>
\r<p>
\r<dt> <var>delta</var>
\r<dd>
\r[in scalar]
\rSigned change to the number of user references.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_mod_refs</strong> function requests that the number
\rof user references a task has for a right be changed. This results
\rin the right
\rbeing destroyed, if the
\rnumber of user references is changed to zero.
\r<p>
\rThe <var>name</var> parameter
\rshould denote the specified right. The number of user references for
\rthe right is changed by the amount <var>delta</var>, subject to the following
\rrestrictions:
\rport sets, receive rights, and send-once rights may only have
\rone user reference.
\rThe resulting number of user references can't be negative. If the resulting
\rnumber of user references is zero, the effect is to de-allocate
\rthe right. For dead
\rnames and send rights, there is an implementation-defined maximum number of
\ruser references.
\r<p>
\rIf the call destroys the right, then the effect is as described for
\r<strong>mach_port_destroy</strong>, with the exception that
\r<strong>mach_port_destroy</strong>
\rsimultaneously destroys all
\rthe rights denoted by a name, while <strong>mach_port_mod_refs</strong>
\rcan only destroy
\rone right. The name will be available for reuse if it only denoted
\rthe one right.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_NAME</strong>
\r<dd>
\r<var>name</var> did not denote a right.
\r<p>
\r<dt> <strong>KERN_INVALID_RIGHT</strong>
\r<dd>
\r<var>name</var> denoted a right, but not the specified right.
\r<p>
\r<dt> <strong>KERN_INVALID_VALUE</strong>
\r<dd>
\rThe user-reference count would become negative.
\r<p>
\r<dt> <strong>KERN_UREFS_OVERFLOW</strong>
\r<dd>
\rThe user-reference count would overflow.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_destroy.html"><strong>mach_port_destroy</strong></a>,
\r<a href="mach_port_get_refs.html"><strong>mach_port_get_refs</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_mod_refs</h2>
+<hr>
+<p>
+<strong>Function</strong> - Modify the specified port right's count of user references.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_mod_refs</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_name_t</strong> <var>name</var>,
+ <strong>mach_port_right_t</strong> <var>right</var>,
+ <strong>mach_port_delta_t</strong> <var>delta</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task holding the right.
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+The task's name for the right.
+<p>
+<dt> <var>right</var>
+<dd>
+[in scalar]
+The type of right/entity being modified:
+<dl>
+<p>
+<dt>
+<strong>MACH_PORT_RIGHT_SEND</strong>
+<p>
+<dt>
+<strong>MACH_PORT_RIGHT_RECEIVE</strong>
+<p>
+<dt>
+<strong>MACH_PORT_RIGHT_SEND_ONCE</strong>
+<p>
+<dt>
+<strong>MACH_PORT_RIGHT_PORT_SET</strong>
+<p>
+<dt>
+<strong>MACH_PORT_RIGHT_DEAD_NAME</strong>
+</dl>
+<p>
+<dt> <var>delta</var>
+<dd>
+[in scalar]
+Signed change to the number of user references.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_mod_refs</strong> function requests that the number
+of user references a task has for a right be changed. This results
+in the right
+being destroyed, if the
+number of user references is changed to zero.
+<p>
+The <var>name</var> parameter
+should denote the specified right. The number of user references for
+the right is changed by the amount <var>delta</var>, subject to the following
+restrictions:
+port sets, receive rights, and send-once rights may only have
+one user reference.
+The resulting number of user references can't be negative. If the resulting
+number of user references is zero, the effect is to de-allocate
+the right. For dead
+names and send rights, there is an implementation-defined maximum number of
+user references.
+<p>
+If the call destroys the right, then the effect is as described for
+<strong>mach_port_destroy</strong>, with the exception that
+<strong>mach_port_destroy</strong>
+simultaneously destroys all
+the rights denoted by a name, while <strong>mach_port_mod_refs</strong>
+can only destroy
+one right. The name will be available for reuse if it only denoted
+the one right.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_NAME</strong>
+<dd>
+<var>name</var> did not denote a right.
+<p>
+<dt> <strong>KERN_INVALID_RIGHT</strong>
+<dd>
+<var>name</var> denoted a right, but not the specified right.
+<p>
+<dt> <strong>KERN_INVALID_VALUE</strong>
+<dd>
+The user-reference count would become negative.
+<p>
+<dt> <strong>KERN_UREFS_OVERFLOW</strong>
+<dd>
+The user-reference count would overflow.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_destroy.html"><strong>mach_port_destroy</strong></a>,
+<a href="mach_port_get_refs.html"><strong>mach_port_get_refs</strong></a>.
-<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
\r<html>
\r<head>
\r <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
\r <meta name="GENERATOR" content="Mozilla/4.73 (Macintosh; U; PPC) [Netscape]">
\r <title>mach_port_insert_member.html</title>
\r</head>
\r<body>
\r\r<h2>
\rmach_port_move_member</h2>
\r\r<hr>
\r<p><b>Function</b> - Move the specified receive right into or out of the
\rspecified port set.
\r<h3>
\rSYNOPSIS</h3>
\r\r<pre><b>kern_return_t mach_port_move_member
\r</b> <b>(ipc_space_t</b> <i>task</i>,
\r <b>mach_port_name_t</b> <i>member</i>,
\r <b>mach_port_name_t</b> <i>after</i><b>);</b></pre>
\r\r<h3>
\rPARAMETERS</h3>
\r\r<dl>
\r<dt>
\r<i>task</i></dt>
\r\r<dd>
\r[in task send right] The task holding the port set and receive right.</dd>
\r\r<dt>
\r<i>member</i></dt>
\r\r<dd>
\r[in scalar] The task's name for the receive right.</dd>
\r\r<dt>
\r<i>after</i></dt>
\r\r<dd>
\r[in scalar] The task's name for the port set.</dd>
\r</dl>
\r\r<h3>
\rDESCRIPTION</h3>
\rThe <b>mach_port_move_member</b> function moves a receive right into a
\rport set. If the receive right is already a member of any other port sets,
\rit is removed from those sets first. If the port set is <b>MACH_PORT_NULL</b>,
\rthen the receive right is not put into a port set, but removed from all
\rits current port sets.
\r<h3>
\rNOTES</h3>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>
\rRETURN VALUES</h3>
\r\r<dl>
\r<dt>
\r<b>KERN_INVALID_NAME</b></dt>
\r\r<dd>
\r<i>member</i> or <i>after</i> did not denote a right.</dd>
\r\r<dt>
\r<b>KERN_INVALID_RIGHT</b></dt>
\r\r<dd>
\r<i>member</i> denoted a right, but not a receive right, or <i>after</i>
\rdenoted a right, but not a port set.</dd>
\r\r<dt>
\r<b>KERN_NOT_IN_SET</b></dt>
\r\r<dd>
\r<i>after</i> was <b>MACH_PORT_NULL</b>, but <i>member</i> wasn't currently
\rin a port set.</dd>
\r</dl>
\r\r<h3>
\rRELATED INFORMATION</h3>
\r\r<p>
\rFunctions:
\r<b><a href="../HTML/mach_port_insert_member.html">mach_port_insert_member</a></b>,
\r<b><a href="../HTML/mach_port_extract_member.html">mach_port_extract_member</b></a>,
\r<b><a href="../HTML/mach_port_get_set_status.html">mach_port_get_set_status</a></b>,
\r<b><a href="../HTML/mach_port_get_attributes.html">mach_port_get_attributes</a></b>.
\r</p>
\r\r</body>
\r</html>
\r\ No newline at end of file
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <meta name="GENERATOR" content="Mozilla/4.73 (Macintosh; U; PPC) [Netscape]">
+ <title>mach_port_insert_member.html</title>
+</head>
+<body>
+
+<h2>
+mach_port_move_member</h2>
+
+<hr>
+<p><b>Function</b> - Move the specified receive right into or out of the
+specified port set.
+<h3>
+SYNOPSIS</h3>
+
+<pre><b>kern_return_t mach_port_move_member
+</b> <b>(ipc_space_t</b> <i>task</i>,
+ <b>mach_port_name_t</b> <i>member</i>,
+ <b>mach_port_name_t</b> <i>after</i><b>);</b></pre>
+
+<h3>
+PARAMETERS</h3>
+
+<dl>
+<dt>
+<i>task</i></dt>
+
+<dd>
+[in task send right] The task holding the port set and receive right.</dd>
+
+<dt>
+<i>member</i></dt>
+
+<dd>
+[in scalar] The task's name for the receive right.</dd>
+
+<dt>
+<i>after</i></dt>
+
+<dd>
+[in scalar] The task's name for the port set.</dd>
+</dl>
+
+<h3>
+DESCRIPTION</h3>
+The <b>mach_port_move_member</b> function moves a receive right into a
+port set. If the receive right is already a member of any other port sets,
+it is removed from those sets first. If the port set is <b>MACH_PORT_NULL</b>,
+then the receive right is not put into a port set, but removed from all
+its current port sets.
+<h3>
+NOTES</h3>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>
+RETURN VALUES</h3>
+
+<dl>
+<dt>
+<b>KERN_INVALID_NAME</b></dt>
+
+<dd>
+<i>member</i> or <i>after</i> did not denote a right.</dd>
+
+<dt>
+<b>KERN_INVALID_RIGHT</b></dt>
+
+<dd>
+<i>member</i> denoted a right, but not a receive right, or <i>after</i>
+denoted a right, but not a port set.</dd>
+
+<dt>
+<b>KERN_NOT_IN_SET</b></dt>
+
+<dd>
+<i>after</i> was <b>MACH_PORT_NULL</b>, but <i>member</i> wasn't currently
+in a port set.</dd>
+</dl>
+
+<h3>
+RELATED INFORMATION</h3>
+
+<p>
+Functions:
+<b><a href="../HTML/mach_port_insert_member.html">mach_port_insert_member</a></b>,
+<b><a href="../HTML/mach_port_extract_member.html">mach_port_extract_member</b></a>,
+<b><a href="../HTML/mach_port_get_set_status.html">mach_port_get_set_status</a></b>,
+<b><a href="../HTML/mach_port_get_attributes.html">mach_port_get_attributes</a></b>.
+</p>
+
+</body>
+</html>
-<h2>mach_port_names</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return information about a task's port name space.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_names</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_name_array_t</strong> <var>*names</var>,
\r <strong>mach_msg_type_number_t</strong> <var>*namesCnt</var>,
\r <strong>mach_port_type_array_</strong> <var>*types</var>,
\r <strong>mach_msg_type_number_t</strong> <var>*typesCnt</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task whose port name space is queried.
\r<p>
\r<dt> <var>names</var>
\r<dd>
\r[out pointer to dynamic array of <var>mach_port_name_t</var>]
\rThe names of the
\rports, port sets, and dead names in the task's port name space, in no
\rparticular order.
\r<p>
\r<dt> <var>namesCnt</var>
\r<dd>
\r[out scalar]
\rThe number of names returned.
\r<p>
\r<dt> <var>types</var>
\r<dd>
\r[out pointer to dynamic array of <var>mach_port_type_t</var>]
\rThe type of each
\rcorresponding name. Indicates what kind of rights the task holds with
\rthat name.
\r<p>
\r<dt> <var>typesCnt</var>
\r<dd>
\r[out scalar]
\rThe number of types returned.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_names</strong> returns information about <var>task</var>'s
\rport name space. It
\rreturns task's currently active names, which represent some port,
\rport set, or dead
\rname right. For each name, it also returns what type of rights
\r<var>task</var> holds (the
\rsame information returned by <strong>mach_port_type</strong>).
\r<p>
\rNote that when a call to <strong>mach_port_names</strong> returns, the
\rnumber of entries in the two output arrays (<var>names</var> and <var>types</var>)
\rare equal (<var>namesCnt</var> equals <var>typesCnt</var>). The fact that this
\rinterface returns two separate counts is an artifact of the Mach Interface Generator.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter and the returned port names.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_type.html"><strong>mach_port_type</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_names</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return information about a task's port name space.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_names</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_name_array_t</strong> <var>*names</var>,
+ <strong>mach_msg_type_number_t</strong> <var>*namesCnt</var>,
+ <strong>mach_port_type_array_</strong> <var>*types</var>,
+ <strong>mach_msg_type_number_t</strong> <var>*typesCnt</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task whose port name space is queried.
+<p>
+<dt> <var>names</var>
+<dd>
+[out pointer to dynamic array of <var>mach_port_name_t</var>]
+The names of the
+ports, port sets, and dead names in the task's port name space, in no
+particular order.
+<p>
+<dt> <var>namesCnt</var>
+<dd>
+[out scalar]
+The number of names returned.
+<p>
+<dt> <var>types</var>
+<dd>
+[out pointer to dynamic array of <var>mach_port_type_t</var>]
+The type of each
+corresponding name. Indicates what kind of rights the task holds with
+that name.
+<p>
+<dt> <var>typesCnt</var>
+<dd>
+[out scalar]
+The number of types returned.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_names</strong> returns information about <var>task</var>'s
+port name space. It
+returns task's currently active names, which represent some port,
+port set, or dead
+name right. For each name, it also returns what type of rights
+<var>task</var> holds (the
+same information returned by <strong>mach_port_type</strong>).
+<p>
+Note that when a call to <strong>mach_port_names</strong> returns, the
+number of entries in the two output arrays (<var>names</var> and <var>types</var>)
+are equal (<var>namesCnt</var> equals <var>typesCnt</var>). The fact that this
+interface returns two separate counts is an artifact of the Mach Interface Generator.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter and the returned port names.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_type.html"><strong>mach_port_type</strong></a>.
-<h2>mach_port_qos</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Specifies a port's attributes with respect to "Quality Of Service."
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>typedef struct mach_port_qos</strong>
\r <strong>{</strong>
\r <strong>boolean_t</strong> <var>name</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>rt</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>pad1</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>pad2</var><strong>;</strong>
\r <strong>} mach_port_qos_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>name</var>
\r<dd>
\r If TRUE, the system will bestow the user-specified name on the newly allocated port.
\r Otherwise, the system will choose the port's name.
\r <p>
\r <dt> <var>rt</var>
\r<dd>
\r If TRUE, this field causes a realtime port to be allocated.
\r Otherwise, a regular port will be allocated.
\r<p>
\r <dt> <var>pad1</var>
\r<dd>
\r A 30 bit padding field.
\r<p>
\r <dt> <var>pad2</var>
\r<dd>
\rA 32 bit padding field; with the <var>pad1</var> field, lengthens the
\r structure to 64 bits.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_qos</strong> structure is used to specify a port's
\r"quality of service" attributes when allocating the port via the
\r<strong>mach_port_allocate_qos</strong> interface.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_allocate_qos.html"><strong>mach_port_allocate_qos</strong></a>,
\r<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>,
\r<a href="mach_port_set_attributes.html"><strong>mach_port_set_attributes</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_qos</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Specifies a port's attributes with respect to "Quality Of Service."
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>typedef struct mach_port_qos</strong>
+ <strong>{</strong>
+ <strong>boolean_t</strong> <var>name</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>rt</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>pad1</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>pad2</var><strong>;</strong>
+ <strong>} mach_port_qos_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>name</var>
+<dd>
+ If TRUE, the system will bestow the user-specified name on the newly allocated port.
+ Otherwise, the system will choose the port's name.
+ <p>
+ <dt> <var>rt</var>
+<dd>
+ If TRUE, this field causes a realtime port to be allocated.
+ Otherwise, a regular port will be allocated.
+<p>
+ <dt> <var>pad1</var>
+<dd>
+ A 30 bit padding field.
+<p>
+ <dt> <var>pad2</var>
+<dd>
+A 32 bit padding field; with the <var>pad1</var> field, lengthens the
+ structure to 64 bits.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_qos</strong> structure is used to specify a port's
+"quality of service" attributes when allocating the port via the
+<strong>mach_port_allocate_qos</strong> interface.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_allocate_qos.html"><strong>mach_port_allocate_qos</strong></a>,
+<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>,
+<a href="mach_port_set_attributes.html"><strong>mach_port_set_attributes</strong></a>.
-<h2>mach_port_set_attributes</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set the target port's attributes.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_set_attributes</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_name_t</strong> <var>name</var>,
\r <strong>mach_port_flavor_t</strong> <var>flavor</var>,
\r <strong>mach_port_info_t</strong> <var>port_info</var>,
\r <strong>mach_msg_type_number_t</strong> <var>port_info_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task holding a receive right to the port in
\rquestion.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\r<var>task</var>'s name for the port.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of attributes to be set. Valid values are:
\r<dl>
\r<p>
\r<dt> <strong>MACH_PORT_LIMITS_INFO</strong>
\r<dd>
\rSets resource limits (queue limits) for the port. The declaration
\rof this data is found in structure <strong>mach_port_limits</strong>.
\r</dl>
\r<p>
\r<dt> <var>port_info</var>
\r<dd>
\r[pointer to in structure]
\rAttributes for the specified port.
\r<p>
\r<dt> <var>port_info_count</var>
\r<dd>
\r[in scalar]
\rThe size of the buffer (in natural-sized units).
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_set_attributes</strong> function sets attributes of type
\r<var>flavor</var>.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_NAME</strong>
\r<dd>
\r<var>name</var> did not denote a right.
\r<p>
\r<dt> <strong>KERN_INVALID_RIGHT</strong>
\r<dd>
\r<var>name</var> denoted a right, but not a receive right.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>,
\r<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>,
\r<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>.
\r<p>
\rData Structures:
\r<a href="mach_port_limits.html"><strong>mach_port_limits</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_set_attributes</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set the target port's attributes.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_set_attributes</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_name_t</strong> <var>name</var>,
+ <strong>mach_port_flavor_t</strong> <var>flavor</var>,
+ <strong>mach_port_info_t</strong> <var>port_info</var>,
+ <strong>mach_msg_type_number_t</strong> <var>port_info_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task holding a receive right to the port in
+question.
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+<var>task</var>'s name for the port.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of attributes to be set. Valid values are:
+<dl>
+<p>
+<dt> <strong>MACH_PORT_LIMITS_INFO</strong>
+<dd>
+Sets resource limits (queue limits) for the port. The declaration
+of this data is found in structure <strong>mach_port_limits</strong>.
+</dl>
+<p>
+<dt> <var>port_info</var>
+<dd>
+[pointer to in structure]
+Attributes for the specified port.
+<p>
+<dt> <var>port_info_count</var>
+<dd>
+[in scalar]
+The size of the buffer (in natural-sized units).
+</dl>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_set_attributes</strong> function sets attributes of type
+<var>flavor</var>.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_NAME</strong>
+<dd>
+<var>name</var> did not denote a right.
+<p>
+<dt> <strong>KERN_INVALID_RIGHT</strong>
+<dd>
+<var>name</var> denoted a right, but not a receive right.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>,
+<a href="mach_port_allocate_name.html"><strong>mach_port_allocate_name</strong></a>,
+<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>.
+<p>
+Data Structures:
+<a href="mach_port_limits.html"><strong>mach_port_limits</strong></a>.
-<h2>mach_port_set_mscount</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Change the target port's make-send count.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_set_mscount</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_name_t</strong> <var>name</var>,
\r <strong>mach_port_mscount_t</strong> <var>mscount</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task owning the receive right.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\r<var>task</var>'s name for the receive right.
\r<p>
\r<dt> <var>mscount</var>
\r<dd>
\r[in scalar]
\rNew value for the make-send count for the receive right.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_set_mscount</strong> function changes the make-send
\rcount of <var>task</var>'s
\rreceive right named <var>name</var>.
\rA port's make-send count specifies the number of send rights that have
\rbeen generated via the port's receive right. A port's make-send count
\ris set to zero when the port is first allocated; the count is reset to
\rzero each time the port's receive right is transferred via a Mach message.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_NAME</strong>
\r<dd>
\r<var>name</var> did not denote a right.
\r<p>
\r<dt> <strong>KERN_INVALID_RIGHT</strong>
\r<dd>
\r<var>name</var> denoted a right, but not a receive right.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_set_mscount</h2>
+<hr>
+<p>
+<strong>Function</strong> - Change the target port's make-send count.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_set_mscount</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_name_t</strong> <var>name</var>,
+ <strong>mach_port_mscount_t</strong> <var>mscount</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task owning the receive right.
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+<var>task</var>'s name for the receive right.
+<p>
+<dt> <var>mscount</var>
+<dd>
+[in scalar]
+New value for the make-send count for the receive right.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_set_mscount</strong> function changes the make-send
+count of <var>task</var>'s
+receive right named <var>name</var>.
+A port's make-send count specifies the number of send rights that have
+been generated via the port's receive right. A port's make-send count
+is set to zero when the port is first allocated; the count is reset to
+zero each time the port's receive right is transferred via a Mach message.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_NAME</strong>
+<dd>
+<var>name</var> did not denote a right.
+<p>
+<dt> <strong>KERN_INVALID_RIGHT</strong>
+<dd>
+<var>name</var> denoted a right, but not a receive right.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>.
-<h2>mach_port_set_seqno</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Change the current value of the target port's sequence number.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_set_seqno</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_name_t</strong> <var>name</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task owning the receive right.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\r<var>task</var>'s name for the receive right.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number that the next message received from
\rthe port will have.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_set_seqno</strong> function changes the sequence
\rnumber of <var>task</var>'s
\rreceive right named <var>name</var>.
\r<p>
\r(Each port is associated with a sequence number attribute that can be
\rused to track the order in which messages sent to the port are received.
\rA port's sequence number is initially set to zero and is incremented each
\rtime a message is received from the port. A port's sequence number is
\rautomatically reset to zero each time the port's receive right migrates.)
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_NAME</strong>
\r<dd>
\r<var>name</var> did not denote a right.
\r<p>
\r<dt> <strong>KERN_INVALID_RIGHT</strong>
\r<dd>
\r<var>name</var> denoted a right, but not a receive right.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_set_seqno</h2>
+<hr>
+<p>
+<strong>Function</strong> - Change the current value of the target port's sequence number.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_set_seqno</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_name_t</strong> <var>name</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task owning the receive right.
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+<var>task</var>'s name for the receive right.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number that the next message received from
+the port will have.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_set_seqno</strong> function changes the sequence
+number of <var>task</var>'s
+receive right named <var>name</var>.
+<p>
+(Each port is associated with a sequence number attribute that can be
+used to track the order in which messages sent to the port are received.
+A port's sequence number is initially set to zero and is incremented each
+time a message is received from the port. A port's sequence number is
+automatically reset to zero each time the port's receive right migrates.)
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_NAME</strong>
+<dd>
+<var>name</var> did not denote a right.
+<p>
+<dt> <strong>KERN_INVALID_RIGHT</strong>
+<dd>
+<var>name</var> denoted a right, but not a receive right.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>.
-<h2>mach_port_status</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Used to present a port's current status with respect to various important attributes.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct mach_port_status</strong>
\r<strong>{</strong>
\r <strong>natural_t</strong> <var>mps_pset_count</var><strong>;</strong>
\r <strong>mach_port_seqno_t</strong> <var>mps_seqno</var><strong>;</strong>
\r <strong>mach_port_mscount_t</strong> <var>mps_mscount</var><strong>;</strong>
\r <strong>mach_port_msgcount_t</strong> <var>mps_qlimit</var><strong>;</strong>
\r <strong>mach_port_msgcount_t</strong> <var>mps_msgcount</var><strong>;</strong>
\r <strong>mach_port_rights_t</strong> <var>mps_sorights</var><strong>;</strong>
\r <strong>mach_port_srights_t</strong> <var>mps_srights</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>mps_pdrequest</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>mps_nsrequest</var><strong>;</strong>
\r <strong>unsigned int</strong> <var>mps_flags</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct mach_port_status mach_port_status_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>mps_pset</var>
\r<dd>
\rContaining port set.
\r <p>
\r<dt> <var>mps_seqno</var>
\r<dd>
\rCurrent sequence number for the port.
\r <p>
\r <dt> <var>mps_mscount</var>
\r <dd>
\r Make-send count.
\r <p>
\r<dt> <var>mps_msgcount</var>
\r<dd>
\rUpper limit for the number of messages that may be queued to the port
\r before the system blocks send operations.
\r <p>
\r <dt> <var>mps_msgcount</var>
\r<dd>
\r Number of messages currently queued on the port.
\r <p>
\r<dt> <var>mps_sorights</var>
\r<dd>
\rHow many send-once rights.
\r <p>
\r<dt> <var>mps_srights</var>
\r<dd>
\rSpecifies whether or not send rights exist. Valid values are as follows:
\r <dl>
\r <p>
\r <dt> MPS_FALSE
\r <dd>
\r No send rights currently in existence.
\r <p>
\r <dt> MPS_TRUE
\r <dd>
\r Send rights exist and no-more-senders notification is enabled.
\r <p>
\r <dt> MPS_UNKNOWN
\r <dd>
\r The port does not permit no-more-senders notification requests;
\r consequently, the system does not know whether or not send rights
\r exist.
\r </dl>
\r <p>
\r<dt> <var>mps_pdrequest</var>
\r<dd>
\r Specifies whether or not a port-deleted notification has been requested.
\r <p>
\r<dt> <var>mps_nsrequest</var>
\r<dd>
\rTrue if no-senders requested.
\r <p>
\r<dt> <var>mps_flags</var>
\r<dd>
\r Flags associated with the port.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_status</strong> structure is used to provide
\rinformation about a port in response to an invocation of the
\r<strong>mach_port_get_attributes</strong> interface.
\r<h3>NOTES</h3>
\r<p>
\rThis structure is machine word length sensitive due
\rto the presence of the port
\rset name.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_status</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Used to present a port's current status with respect to various important attributes.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct mach_port_status</strong>
+<strong>{</strong>
+ <strong>natural_t</strong> <var>mps_pset_count</var><strong>;</strong>
+ <strong>mach_port_seqno_t</strong> <var>mps_seqno</var><strong>;</strong>
+ <strong>mach_port_mscount_t</strong> <var>mps_mscount</var><strong>;</strong>
+ <strong>mach_port_msgcount_t</strong> <var>mps_qlimit</var><strong>;</strong>
+ <strong>mach_port_msgcount_t</strong> <var>mps_msgcount</var><strong>;</strong>
+ <strong>mach_port_rights_t</strong> <var>mps_sorights</var><strong>;</strong>
+ <strong>mach_port_srights_t</strong> <var>mps_srights</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>mps_pdrequest</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>mps_nsrequest</var><strong>;</strong>
+ <strong>unsigned int</strong> <var>mps_flags</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct mach_port_status mach_port_status_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>mps_pset</var>
+<dd>
+Containing port set.
+ <p>
+<dt> <var>mps_seqno</var>
+<dd>
+Current sequence number for the port.
+ <p>
+ <dt> <var>mps_mscount</var>
+ <dd>
+ Make-send count.
+ <p>
+<dt> <var>mps_msgcount</var>
+<dd>
+Upper limit for the number of messages that may be queued to the port
+ before the system blocks send operations.
+ <p>
+ <dt> <var>mps_msgcount</var>
+<dd>
+ Number of messages currently queued on the port.
+ <p>
+<dt> <var>mps_sorights</var>
+<dd>
+How many send-once rights.
+ <p>
+<dt> <var>mps_srights</var>
+<dd>
+Specifies whether or not send rights exist. Valid values are as follows:
+ <dl>
+ <p>
+ <dt> MPS_FALSE
+ <dd>
+ No send rights currently in existence.
+ <p>
+ <dt> MPS_TRUE
+ <dd>
+ Send rights exist and no-more-senders notification is enabled.
+ <p>
+ <dt> MPS_UNKNOWN
+ <dd>
+ The port does not permit no-more-senders notification requests;
+ consequently, the system does not know whether or not send rights
+ exist.
+ </dl>
+ <p>
+<dt> <var>mps_pdrequest</var>
+<dd>
+ Specifies whether or not a port-deleted notification has been requested.
+ <p>
+<dt> <var>mps_nsrequest</var>
+<dd>
+True if no-senders requested.
+ <p>
+<dt> <var>mps_flags</var>
+<dd>
+ Flags associated with the port.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_status</strong> structure is used to provide
+information about a port in response to an invocation of the
+<strong>mach_port_get_attributes</strong> interface.
+<h3>NOTES</h3>
+<p>
+This structure is machine word length sensitive due
+to the presence of the port
+set name.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>.
-<h2>mach_port_type</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return the characteristics of the target port name.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_port_type</strong>
\r <strong>(ipc_space_t</strong> <var>task</var>,
\r <strong>mach_port_name_t</strong> <var>name</var>,
\r <strong>mach_port_type_t</strong> <var>ptype</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task whose port name space is queried.
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\rThe name being queried.
\r<p>
\r<dt> <var>ptype</var>
\r<dd>
\r[out scalar]
\rThe type of the name. Indicates what kind of right the task
\rholds for the port, port set, or dead name.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_port_type</strong> function returns information about <var>task</var>'s
\rrights for a specific name in its port name space. The returned
\r<var>ptype</var> is a bit-mask indicating what rights <var>task</var>
\rholds with this name.
\rThe bit-mask is composed of the following bits:
\r<dl>
\r<dt> <strong>MACH_PORT_TYPE_SEND</strong>
\r<dd>
\rThe name denotes send rights.
\r<p>
\r<dt> <strong>MACH_PORT_TYPE_RECEIVE</strong>
\r<dd>
\rThe name denotes a receive right.
\r<p>
\r<dt> <strong>MACH_PORT_TYPE_SEND_ONCE</strong>
\r<dd>
\rThe name denotes a send-once right.
\r<p>
\r<dt> <strong>MACH_PORT_TYPE_PORT_SET</strong>
\r<dd>
\rThe name denotes a port set.
\r<p>
\r<dt> <strong>MACH_PORT_TYPE_DEAD_NAME</strong>
\r<dd>
\rThe name is a dead name.
\r<p>
\r<dt> <strong>MACH_PORT_TYPE_DNREQUEST</strong>
\r<dd>
\rA dead-name request has been registered for the right.
\r</dl>
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the port name
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_NAME</strong>
\r<dd>
\r<var>name</var> did not denote a right.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_names.html"><strong>mach_port_names</strong></a>,
\r<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>,
\r<a href="mach_port_get_set_status.html"><strong>mach_port_get_set_status</strong></a>.
\r\ No newline at end of file
+<h2>mach_port_type</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return the characteristics of the target port name.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_port_type</strong>
+ <strong>(ipc_space_t</strong> <var>task</var>,
+ <strong>mach_port_name_t</strong> <var>name</var>,
+ <strong>mach_port_type_t</strong> <var>ptype</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task whose port name space is queried.
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+The name being queried.
+<p>
+<dt> <var>ptype</var>
+<dd>
+[out scalar]
+The type of the name. Indicates what kind of right the task
+holds for the port, port set, or dead name.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_port_type</strong> function returns information about <var>task</var>'s
+rights for a specific name in its port name space. The returned
+<var>ptype</var> is a bit-mask indicating what rights <var>task</var>
+holds with this name.
+The bit-mask is composed of the following bits:
+<dl>
+<dt> <strong>MACH_PORT_TYPE_SEND</strong>
+<dd>
+The name denotes send rights.
+<p>
+<dt> <strong>MACH_PORT_TYPE_RECEIVE</strong>
+<dd>
+The name denotes a receive right.
+<p>
+<dt> <strong>MACH_PORT_TYPE_SEND_ONCE</strong>
+<dd>
+The name denotes a send-once right.
+<p>
+<dt> <strong>MACH_PORT_TYPE_PORT_SET</strong>
+<dd>
+The name denotes a port set.
+<p>
+<dt> <strong>MACH_PORT_TYPE_DEAD_NAME</strong>
+<dd>
+The name is a dead name.
+<p>
+<dt> <strong>MACH_PORT_TYPE_DNREQUEST</strong>
+<dd>
+A dead-name request has been registered for the right.
+</dl>
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the port name
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_NAME</strong>
+<dd>
+<var>name</var> did not denote a right.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_names.html"><strong>mach_port_names</strong></a>,
+<a href="mach_port_get_attributes.html"><strong>mach_port_get_attributes</strong></a>,
+<a href="mach_port_get_set_status.html"><strong>mach_port_get_set_status</strong></a>.
-<h2>mach_ports_lookup</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Provide caller with an array of the target task's well-known ports.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_ports_lookup</strong>
\r <strong>(task_t</strong> <var>target_task</var>,
\r <strong>mach_port_array_t</strong> <var>init_port_set</var>,
\r <strong>mach_msg_type_number_t</strong> <var>init_port_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe task whose currently registered ports are to be
\rreturned.
\r<p>
\r<dt> <var>init_port_set</var>
\r<dd>
\r[out pointer to dynamic array of registered send rights]
\rThe returned
\rarray of ports.
\r<p>
\r<dt> <var>init_port_count</var>
\r<dd>
\r[out scalar]
\rThe number of returned port rights.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_ports_lookup</strong> function returns an array of
\rthe well-known system
\rports that are currently registered for the specified task.
\rNote that the task holds
\ronly send rights for the ports.
\r<p>
\rRegistered ports are those ports that are used by the run-time
\rsystem to initialize a task. To register system ports for a task,
\ruse the <strong>mach_ports_register</strong> function.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_ports_register.html"><strong>mach_ports_register</strong></a>.
\r\ No newline at end of file
+<h2>mach_ports_lookup</h2>
+<hr>
+<p>
+<strong>Function</strong> - Provide caller with an array of the target task's well-known ports.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_ports_lookup</strong>
+ <strong>(task_t</strong> <var>target_task</var>,
+ <strong>mach_port_array_t</strong> <var>init_port_set</var>,
+ <strong>mach_msg_type_number_t</strong> <var>init_port_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The task whose currently registered ports are to be
+returned.
+<p>
+<dt> <var>init_port_set</var>
+<dd>
+[out pointer to dynamic array of registered send rights]
+The returned
+array of ports.
+<p>
+<dt> <var>init_port_count</var>
+<dd>
+[out scalar]
+The number of returned port rights.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_ports_lookup</strong> function returns an array of
+the well-known system
+ports that are currently registered for the specified task.
+Note that the task holds
+only send rights for the ports.
+<p>
+Registered ports are those ports that are used by the run-time
+system to initialize a task. To register system ports for a task,
+use the <strong>mach_ports_register</strong> function.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_ports_register.html"><strong>mach_ports_register</strong></a>.
-<h2>mach_ports_register</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Register an array of well-known ports on behalf of the target task.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_ports_register</strong>
\r <strong>(task_t</strong> <var>target_task</var>,
\r <strong>mach_port_array_t</strong> <var>init_port_set</var>,
\r <strong>target_task</strong> <var>init_port_array_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe task for which the ports are to be registered.
\r<p>
\r<dt> <var>init_port_set</var>
\r<dd>
\r[in pointer to array of registered send rights]
\rThe array of ports to
\rregister.
\r<p>
\r<dt> <var>init_port_array_count</var>
\r<dd>
\r[in scalar]
\rThe number of ports in the array. Note that while this is a
\rvariable, the kernel accepts only a limited number of ports. The
\rmaximum number of ports is defined by the global constant
\r<strong>MACH_PORTS_SLOTS_USED</strong>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_ports_register</strong> function registers an array
\rof well-known system
\rports for the specified task. The task holds only send rights
\rfor the registered
\rports. The valid well-known system ports are:
\r<ul>
\r<li>
\rThe port for the Name Server
\r<li>
\rThe port for the Environment Manager
\r<li>
\rThe port for the Service server
\r</ul>
\r<p>
\rEach port must be placed in a specific slot in the array. The slot numbers are
\rdefined (in <strong>mach.h</strong>) by the global constants <strong>NAME_SERVER_SLOT</strong>,
\r<strong>ENVIRONMENT_SLOT</strong>, and <strong>SERVICE_SLOT</strong>.
\r<p>
\rA task can retrieve the currently registered ports by using the
\r<strong>mach_ports_lookup</strong> function.
\r<h3>NOTES</h3>
\r<p>
\rWhen a new task is created (with <strong>task_create</strong>),
\rthe child task can inherit the
\rparent's registered ports. Note that child tasks do not automatically
\racquire rights
\rto these ports. They must use <strong>mach_ports_lookup</strong> to
\rget them. It is intended
\rthat port registration be used only for task initialization, and then only by
\rrun-time support modules.
\r<p>
\rA parent task has three choices when passing registered ports to child tasks:
\r<ul>
\r<li>
\rThe parent task can do nothing. In this case, all child tasks
\rinherit access to
\rthe same ports that the parent has.
\r<li>
\rThe parent task can use <strong>mach_ports_register</strong> to modify
\rits set of registered
\rports before creating child tasks. In this case, the child tasks get access
\rto the
\rmodified set of ports. After creating its child tasks. the parent can use
\r<strong>mach_ports_register</strong> again to reset its registered ports.
\r<li>
\rThe parent task can first create a specific child task and then use
\r<strong>mach_ports_register</strong> to modify the child's inherited
\rset of ports, before starting
\rthe child's thread(s). The parent must specify the child's task port, rather
\rthan its own, on the call to <strong>mach_ports_register</strong>.
\r</ul>
\r<p>
\rTasks other than the Name Server and the Environment Manager
\rshould not need access to the Service port. The Name Server port is
\rthe same for all tasks on a given machine. The Environment port
\ris the only port
\rlikely to have different values for different tasks.
\r<p>
\rRegistered ports are restricted to those ports that are used by the run-time
\rsystem to initialize a task. A parent task can pass other ports
\rto its child tasks
\rthrough:
\r<ul>
\r<li>
\rAn initial message (see <strong>mach_msg</strong>).
\r<li>
\rThe Name Server, for public ports.
\r<li>
\rThe Environment Manager, for private ports.
\r<li>
\rThe task bootstrap port (see <strong>task_get_special_port</strong>).
\r</ul>
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>,
\r<a href="mach_ports_lookup.html"><strong>mach_ports_lookup</strong></a>.
\r\ No newline at end of file
+<h2>mach_ports_register</h2>
+<hr>
+<p>
+<strong>Function</strong> - Register an array of well-known ports on behalf of the target task.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_ports_register</strong>
+ <strong>(task_t</strong> <var>target_task</var>,
+ <strong>mach_port_array_t</strong> <var>init_port_set</var>,
+ <strong>target_task</strong> <var>init_port_array_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The task for which the ports are to be registered.
+<p>
+<dt> <var>init_port_set</var>
+<dd>
+[in pointer to array of registered send rights]
+The array of ports to
+register.
+<p>
+<dt> <var>init_port_array_count</var>
+<dd>
+[in scalar]
+The number of ports in the array. Note that while this is a
+variable, the kernel accepts only a limited number of ports. The
+maximum number of ports is defined by the global constant
+<strong>MACH_PORTS_SLOTS_USED</strong>.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_ports_register</strong> function registers an array
+of well-known system
+ports for the specified task. The task holds only send rights
+for the registered
+ports. The valid well-known system ports are:
+<ul>
+<li>
+The port for the Name Server
+<li>
+The port for the Environment Manager
+<li>
+The port for the Service server
+</ul>
+<p>
+Each port must be placed in a specific slot in the array. The slot numbers are
+defined (in <strong>mach.h</strong>) by the global constants <strong>NAME_SERVER_SLOT</strong>,
+<strong>ENVIRONMENT_SLOT</strong>, and <strong>SERVICE_SLOT</strong>.
+<p>
+A task can retrieve the currently registered ports by using the
+<strong>mach_ports_lookup</strong> function.
+<h3>NOTES</h3>
+<p>
+When a new task is created (with <strong>task_create</strong>),
+the child task can inherit the
+parent's registered ports. Note that child tasks do not automatically
+acquire rights
+to these ports. They must use <strong>mach_ports_lookup</strong> to
+get them. It is intended
+that port registration be used only for task initialization, and then only by
+run-time support modules.
+<p>
+A parent task has three choices when passing registered ports to child tasks:
+<ul>
+<li>
+The parent task can do nothing. In this case, all child tasks
+inherit access to
+the same ports that the parent has.
+<li>
+The parent task can use <strong>mach_ports_register</strong> to modify
+its set of registered
+ports before creating child tasks. In this case, the child tasks get access
+to the
+modified set of ports. After creating its child tasks. the parent can use
+<strong>mach_ports_register</strong> again to reset its registered ports.
+<li>
+The parent task can first create a specific child task and then use
+<strong>mach_ports_register</strong> to modify the child's inherited
+set of ports, before starting
+the child's thread(s). The parent must specify the child's task port, rather
+than its own, on the call to <strong>mach_ports_register</strong>.
+</ul>
+<p>
+Tasks other than the Name Server and the Environment Manager
+should not need access to the Service port. The Name Server port is
+the same for all tasks on a given machine. The Environment port
+is the only port
+likely to have different values for different tasks.
+<p>
+Registered ports are restricted to those ports that are used by the run-time
+system to initialize a task. A parent task can pass other ports
+to its child tasks
+through:
+<ul>
+<li>
+An initial message (see <strong>mach_msg</strong>).
+<li>
+The Name Server, for public ports.
+<li>
+The Environment Manager, for private ports.
+<li>
+The task bootstrap port (see <strong>task_get_special_port</strong>).
+</ul>
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_msg.html"><strong>mach_msg</strong></a>,
+<a href="mach_ports_lookup.html"><strong>mach_ports_lookup</strong></a>.
-<h2>mach_reply_port</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> - Allocate a new port and insert corresponding receive right in the calling task.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<mach/mach_traps.h></strong>
\r\r<strong>mach_port_t mach_reply_port( void )</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\rNone.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_reply_port</strong> function creates a new port for
\rthe current task and
\rreturns the name assigned by the kernel. The kernel records
\rthe name in the task's
\rport name space and grants the task receive rights for the port.
\rThe new port is
\rnot a member of any port set.
\r<p>
\rThis function is an optimized version of <strong>mach_port_allocate</strong>
\rthat uses no port
\rreferences. Its main purpose is to allocate a reply port for
\rthe task when the task
\ris starting, for example, before it has any ports to use as reply
\rports for any IPC-based system functions.
\r<p>
\rIf the task's task self port is null (thereby deactivating basic Mach
\rmanipulations by the task), this call returns null.
\r<h3>CAUTIONS</h3>
\r<p>
\rAlthough the created port can be used for any purpose, the implementation may
\roptimize its use as a reply port.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<dt> <strong>MACH_PORT_NULL</strong>
\r<dd>
\rNo port was allocated.
\r <p>
\r<dt> [reply receive right]
\r<dd>
\rAny other value indicates success.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>.
\r\ No newline at end of file
+<h2>mach_reply_port</h2>
+<hr>
+<p>
+<strong>System Trap</strong> - Allocate a new port and insert corresponding receive right in the calling task.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<mach/mach_traps.h></strong>
+
+<strong>mach_port_t mach_reply_port( void )</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+None.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_reply_port</strong> function creates a new port for
+the current task and
+returns the name assigned by the kernel. The kernel records
+the name in the task's
+port name space and grants the task receive rights for the port.
+The new port is
+not a member of any port set.
+<p>
+This function is an optimized version of <strong>mach_port_allocate</strong>
+that uses no port
+references. Its main purpose is to allocate a reply port for
+the task when the task
+is starting, for example, before it has any ports to use as reply
+ports for any IPC-based system functions.
+<p>
+If the task's task self port is null (thereby deactivating basic Mach
+manipulations by the task), this call returns null.
+<h3>CAUTIONS</h3>
+<p>
+Although the created port can be used for any purpose, the implementation may
+optimize its use as a reply port.
+<h3>RETURN VALUES</h3>
+<dl>
+<dt> <strong>MACH_PORT_NULL</strong>
+<dd>
+No port was allocated.
+ <p>
+<dt> [reply receive right]
+<dd>
+Any other value indicates success.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>.
-<h2>mach_rpc_return_trap</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> - Real-Time RPC trap return location.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<mach/rpc.h></strong>
\r\r<strong>mach_rpc_return_t mach_rpc_return_trap( void )</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<p>
\rNone.
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_rpc_return_trap</strong> is the system entry point
\rused by the reply side of the Mach RPC service and is used by RPC
\rservers to return control to invoking clients.
\rFor a complete description of this functionality, refer to: Burke,
\rEdward, Michael Condict, David Mitchell, Franklin Reynolds, Peter
\rWatkins, William Willcox, "RPC Design for Real-Time Mach," OSF
\rResearch Institute, Cambridge, MA.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is experimental and therefore subject to change.
\r<h3>RETURN VALUES</h3>
\r<p>
\rThe return value is specific to the server function actually executed
\rvia the <strong>mach_rpc_return_trap</strong> call.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_rpc_trap.html"><strong>mach_rpc_trap</strong></a>.
\r\ No newline at end of file
+<h2>mach_rpc_return_trap</h2>
+<hr>
+<p>
+<strong>System Trap</strong> - Real-Time RPC trap return location.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<mach/rpc.h></strong>
+
+<strong>mach_rpc_return_t mach_rpc_return_trap( void )</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<p>
+None.
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_rpc_return_trap</strong> is the system entry point
+used by the reply side of the Mach RPC service and is used by RPC
+servers to return control to invoking clients.
+For a complete description of this functionality, refer to: Burke,
+Edward, Michael Condict, David Mitchell, Franklin Reynolds, Peter
+Watkins, William Willcox, "RPC Design for Real-Time Mach," OSF
+Research Institute, Cambridge, MA.
+<h3>NOTES</h3>
+<p>
+This interface is experimental and therefore subject to change.
+<h3>RETURN VALUES</h3>
+<p>
+The return value is specific to the server function actually executed
+via the <strong>mach_rpc_return_trap</strong> call.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_rpc_trap.html"><strong>mach_rpc_trap</strong></a>.
-<h2>mach_rpc_trap</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> - Real-Time RPC trap.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<mach/rpc.h></strong>
\r\r<strong>mach_rpc_return_t mach_rpc_trap</strong>
\r <strong>(mach_port_t</strong> <var>dest_port</var>,
\r <strong>mach_rpc_id_t</strong> <var>routine_num</var>,
\r <strong>mach_rpc_signature_t</strong> <var>signature_ptr</var>,
\r <strong>mach_rpc_size_t</strong> <var>signature_size</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>dest_port</var>
\r<dd>
\r[in send right] The port representing the destination of the RPC
\r (usually a registered subsystem established by a call to
\r <strong>mach_port_allocate_subsystem</strong>).
\r<p>
\r<dt> <var>routine_num</var>
\r<dd>
\r[in scalar] Identifier of the server work function.
\r<p>
\r<dt> <var>signature_ptr</var>
\r<dd>
\r[in pointer] Pointer to the call's <strong>mach_rpc_signature</strong> structure.
\r<p>
\r<dt> <var>signature_size</var>
\r<dd>
\r[in scalar] Size, in bytes, of the call's <strong>mach_rpc_signature</strong> structure.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_rpc_trap</strong> system trap is the entry point for the
\rinvoke side of the Mach RPC service used to transfer control to an RPC server.
\rThe trap is accessed via the MIG generated
\r<strong>MACH_RPC</strong> macro
\rwhich is invoked transparently when the <strong>mach_rpc</strong> feature is enabled.
\rThis function is not designed for use directly by the user. It is
\rautomatically generated by MIG to handle a function call.
\r<p>
\rFor a
\rcomplete description of this functionality, refer to: Burke, Edward,
\rMichael Condict, David Mitchell, Franklin Reynolds, Peter Watkins,
\rWilliam Willcox, "RPC Design for Real-Time Mach," OSF Research
\rInstitute, Cambridge, MA.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is experimental and therefore subject to change.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_FAILURE</strong>
\r<dd>
\rEither the argument copyin failed, there were too many arguments, or
\rthe argument copyout failed.
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe dest_port, signature_ptr, and/or the subsystem associated with the
\rdest_port is invalid; the siganture_size is less than, or equal to, zero.
\r<p>
\r<dt> <strong>KERN_NO_ACCESS</strong>
\r<dd>
\rThe kernel port associated with the dest_port name is a norma proxy
\rport.
\r<p>
\r<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
\r<dd>
\rThe kernel could not allocate storage for an internal rpc state
\rstructure.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_rpc_return_trap.html"><strong>mach_rpc_return_trap</strong></a>,
\r<a href="thread_activation_create.html"><strong>thread_activation_create</strong></a>,
\r<a href="MP_allocate_subsystem.html"><strong>mach_port_allocate_subsystem</strong></a>,
\r<a href="mach_subsystem_create.html"><strong>mach_subsystem_create</strong></a>.
\r\ No newline at end of file
+<h2>mach_rpc_trap</h2>
+<hr>
+<p>
+<strong>System Trap</strong> - Real-Time RPC trap.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<mach/rpc.h></strong>
+
+<strong>mach_rpc_return_t mach_rpc_trap</strong>
+ <strong>(mach_port_t</strong> <var>dest_port</var>,
+ <strong>mach_rpc_id_t</strong> <var>routine_num</var>,
+ <strong>mach_rpc_signature_t</strong> <var>signature_ptr</var>,
+ <strong>mach_rpc_size_t</strong> <var>signature_size</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>dest_port</var>
+<dd>
+[in send right] The port representing the destination of the RPC
+ (usually a registered subsystem established by a call to
+ <strong>mach_port_allocate_subsystem</strong>).
+<p>
+<dt> <var>routine_num</var>
+<dd>
+[in scalar] Identifier of the server work function.
+<p>
+<dt> <var>signature_ptr</var>
+<dd>
+[in pointer] Pointer to the call's <strong>mach_rpc_signature</strong> structure.
+<p>
+<dt> <var>signature_size</var>
+<dd>
+[in scalar] Size, in bytes, of the call's <strong>mach_rpc_signature</strong> structure.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_rpc_trap</strong> system trap is the entry point for the
+invoke side of the Mach RPC service used to transfer control to an RPC server.
+The trap is accessed via the MIG generated
+<strong>MACH_RPC</strong> macro
+which is invoked transparently when the <strong>mach_rpc</strong> feature is enabled.
+This function is not designed for use directly by the user. It is
+automatically generated by MIG to handle a function call.
+<p>
+For a
+complete description of this functionality, refer to: Burke, Edward,
+Michael Condict, David Mitchell, Franklin Reynolds, Peter Watkins,
+William Willcox, "RPC Design for Real-Time Mach," OSF Research
+Institute, Cambridge, MA.
+<h3>NOTES</h3>
+<p>
+This interface is experimental and therefore subject to change.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_FAILURE</strong>
+<dd>
+Either the argument copyin failed, there were too many arguments, or
+the argument copyout failed.
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The dest_port, signature_ptr, and/or the subsystem associated with the
+dest_port is invalid; the siganture_size is less than, or equal to, zero.
+<p>
+<dt> <strong>KERN_NO_ACCESS</strong>
+<dd>
+The kernel port associated with the dest_port name is a norma proxy
+port.
+<p>
+<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
+<dd>
+The kernel could not allocate storage for an internal rpc state
+structure.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_rpc_return_trap.html"><strong>mach_rpc_return_trap</strong></a>,
+<a href="thread_activation_create.html"><strong>thread_activation_create</strong></a>,
+<a href="MP_allocate_subsystem.html"><strong>mach_port_allocate_subsystem</strong></a>,
+<a href="mach_subsystem_create.html"><strong>mach_subsystem_create</strong></a>.
-<h2>mach_subsystem_create</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Register information about an RPC subsystem.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t mach_subsystem_create</strong>
\r <strong>(task_t</strong> <var>target_task</var>,
\r <strong>user_subsystem_t</strong> <var>user_subsys</var>,
\r <strong>mach_msg_type_number_t</strong> <var>user_subsysCnt</var>,
\r <strong>subsystem_t</strong> <var>subsystem_t</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\rThe task for which the subsystem is registered; normally the calling
\rtask, but not necessarily.
\r<p>
\r<dt> <var>user_subsys</var>
\r<dd>
\rThe MIG-generated data structure describing the exported routines and
\rtheir input/output characteristics (e.g. arguments and return values).
\r<p>
\r<dt> <var>user_subsysCnt</var>
\r<dd>
\rThe size of the user_subsys data structure argument, in bytes.
\r<p>
\r<dt> <var>subsys</var>
\r<dd>
\rThe port returned that names the registered subsystem.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_subsystem_create</strong> function is used by a server to register
\rinformation about an RPC subsystem with the kernel.
\rMIG automatically generates, in the server source file, a
\r<strong>user_subsystem_t</strong> data structure that is appropriate for registering
\rthe subsystem. This data structure includes a per-routine array that
\rspecifies:
\r<ul>
\r<li>
\rThe address of the server function that performs the work.
\r<li>
\rThe address of the MIG-generated server-side marshalling stub, to be
\rused with <strong>mach_msg</strong>.
\r<li>
\rThe argument signature (i.e. NDR-style argument format) of the
\rroutine.
\r</ul>
\r<p>
\rUpon successful completion, <strong>mach_subsystem_create</strong> returns,
\rvia the <var>subsys</var> parameter, a port naming the registered subsystem.
\r<p>
\rEach port on which the server is to receive short-circuited RPC's (or
\ra <strong>mach_rpc</strong> call) must be associated with a registered subsystem, by
\rcalling <strong>mach_port_allocate_subsystem</strong>.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALD_ADDRESS</strong>
\r<dd>
\rOne or more of the addresses in the range specified by the subsystem
\raddress and size are not valid addresses in the caller, or some of the
\rinternal pointers in the subsystem do not point to places within the
\raddress range (all of the data of the subsystem is required to be
\rcontiguous, even the parts that are pointed to by other parts).
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe port name specified by <var>target_task</var> is not a send right naming a task,
\ror the subsystem size is too small to be valid.
\r<p>
\r<dt> <strong>KERN_INVALID_TASK</strong>
\r<dd>
\rThe target task is dead.
\r<p>
\r<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
\r<dd>
\rThe kernel cannot allocate the subsystem due to insufficient available
\rmemory.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="MP_allocate_subsystem.html"><strong>mach_port_allocate_subsystem</strong></a>,
\r<a href="thread_activation_create.html"><strong>thread_activation_create</strong></a>.
\r\ No newline at end of file
+<h2>mach_subsystem_create</h2>
+<hr>
+<p>
+<strong>Function</strong> - Register information about an RPC subsystem.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t mach_subsystem_create</strong>
+ <strong>(task_t</strong> <var>target_task</var>,
+ <strong>user_subsystem_t</strong> <var>user_subsys</var>,
+ <strong>mach_msg_type_number_t</strong> <var>user_subsysCnt</var>,
+ <strong>subsystem_t</strong> <var>subsystem_t</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+The task for which the subsystem is registered; normally the calling
+task, but not necessarily.
+<p>
+<dt> <var>user_subsys</var>
+<dd>
+The MIG-generated data structure describing the exported routines and
+their input/output characteristics (e.g. arguments and return values).
+<p>
+<dt> <var>user_subsysCnt</var>
+<dd>
+The size of the user_subsys data structure argument, in bytes.
+<p>
+<dt> <var>subsys</var>
+<dd>
+The port returned that names the registered subsystem.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_subsystem_create</strong> function is used by a server to register
+information about an RPC subsystem with the kernel.
+MIG automatically generates, in the server source file, a
+<strong>user_subsystem_t</strong> data structure that is appropriate for registering
+the subsystem. This data structure includes a per-routine array that
+specifies:
+<ul>
+<li>
+The address of the server function that performs the work.
+<li>
+The address of the MIG-generated server-side marshalling stub, to be
+used with <strong>mach_msg</strong>.
+<li>
+The argument signature (i.e. NDR-style argument format) of the
+routine.
+</ul>
+<p>
+Upon successful completion, <strong>mach_subsystem_create</strong> returns,
+via the <var>subsys</var> parameter, a port naming the registered subsystem.
+<p>
+Each port on which the server is to receive short-circuited RPC's (or
+a <strong>mach_rpc</strong> call) must be associated with a registered subsystem, by
+calling <strong>mach_port_allocate_subsystem</strong>.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALD_ADDRESS</strong>
+<dd>
+One or more of the addresses in the range specified by the subsystem
+address and size are not valid addresses in the caller, or some of the
+internal pointers in the subsystem do not point to places within the
+address range (all of the data of the subsystem is required to be
+contiguous, even the parts that are pointed to by other parts).
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The port name specified by <var>target_task</var> is not a send right naming a task,
+or the subsystem size is too small to be valid.
+<p>
+<dt> <strong>KERN_INVALID_TASK</strong>
+<dd>
+The target task is dead.
+<p>
+<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
+<dd>
+The kernel cannot allocate the subsystem due to insufficient available
+memory.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="MP_allocate_subsystem.html"><strong>mach_port_allocate_subsystem</strong></a>,
+<a href="thread_activation_create.html"><strong>thread_activation_create</strong></a>.
-<h2>mach_task_self</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> - Return a send right to the caller's task_self port.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<mach/mach_traps.h></strong>
\r\r<strong>mach_port_t mach_task_self (void)</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<p>
\rNone.
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_task_self</strong> function returns send rights to
\rthe task's kernel port.
\r<h3>NOTES</h3>
\r<p>
\rThis function call is redefined in the <strong>mach_init.h</strong> file
\rto return the caller's <strong>mach_task_self_</strong> environment variable,
\rwhich is cached on behalf of the caller's task at runtime.
\r(The <strong>mach_init.h</strong> file is itself included via the
\r<strong>mach.h</strong> file.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>.
\r\ No newline at end of file
+<h2>mach_task_self</h2>
+<hr>
+<p>
+<strong>System Trap</strong> - Return a send right to the caller's task_self port.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<mach/mach_traps.h></strong>
+
+<strong>mach_port_t mach_task_self (void)</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<p>
+None.
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_task_self</strong> function returns send rights to
+the task's kernel port.
+<h3>NOTES</h3>
+<p>
+This function call is redefined in the <strong>mach_init.h</strong> file
+to return the caller's <strong>mach_task_self_</strong> environment variable,
+which is cached on behalf of the caller's task at runtime.
+(The <strong>mach_init.h</strong> file is itself included via the
+<strong>mach.h</strong> file.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>.
-<h2>mach_thread_self</h2>
\r<hr>
\r<p>
\r<strong>System Trap</strong> - Returns the thread self port.
\r\r<h3>SYNOPSIS</h3>
\r<p>
\r<strong>#include <mach/mach_traps.h></strong>
\r<pre>
\r<strong>thread_port_t mach_thread_self( void );</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<p>
\rNone.
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mach_thread_self</strong> function returns send rights
\rto the thread's own kernel port.
\r<h3>RETURN VALUES</h3>
\r<p>
\r[thread-self send right] Send rights to the thread's port.
\r<h3>RELATED INFORMATION<h3>
\r<p>
\rFunctions:
\r<a href="thread_info.html"><strong>thread_info</strong></a>,
\r<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>.
\r\r\ No newline at end of file
+<h2>mach_thread_self</h2>
+<hr>
+<p>
+<strong>System Trap</strong> - Returns the thread self port.
+
+<h3>SYNOPSIS</h3>
+<p>
+<strong>#include <mach/mach_traps.h></strong>
+<pre>
+<strong>thread_port_t mach_thread_self( void );</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<p>
+None.
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mach_thread_self</strong> function returns send rights
+to the thread's own kernel port.
+<h3>RETURN VALUES</h3>
+<p>
+[thread-self send right] Send rights to the thread's port.
+<h3>RELATED INFORMATION<h3>
+<p>
+Functions:
+<a href="thread_info.html"><strong>thread_info</strong></a>,
+<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>.
+
-<h2>mapped_tvalspec</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Specifies the format the kernel uses to maintain a mapped clock's time.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct mapped_tvalspec</strong>
\r<strong>{</strong>
\r <strong>tvalspec_t</strong> <var>mtv_time</var><strong>;</strong>
\r <strong>unsigned int</strong> <var>mtv_csec</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct mapped_tvalspec mapped_tvalspec_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>mtv_time</var>
\r<dd>
\rClock time.
\r<p>
\r<dt> <var>mtv_csec</var>
\r<dd>
\rA field used to synchronize with the kernel's setting of the time.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>mapped_tvalspec</strong> structure defines the format of the
\rcurrent-time structure
\rmaintained by the kernel and visible through a mapped clock
\r(<strong>clock_map_time</strong>). The data in this structure is updated at the
\rclock's current resolution and contains the same <strong>tvalspec</strong> value that
\rwould be returned by <strong>clock_get_time</strong>.
\r<h3>NOTES</h3>
\r<p>
\rBecause of the race between the referencing of the multiple fields
\rin the clock
\rvalue and the kernel's setting them, they should be referenced as follows:
\r<p>
\r<pre>
\r <strong>tvalspec_t* ts;</strong>
\r <strong>do</strong>
\r <strong>{</strong>
\r <strong>ts-> tv_sec = mtime -> mtv_time.tv_sec;</strong>
\r <strong>ts -> tv_nsec = mtime -> mtv_time.tv_nsec;</strong>
\r <strong>} while (ts -> tv_sec != mtime -> mtv_csec);</strong>
\r</pre>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="clock_map_time.html"><strong>clock_map_time</strong></a>,
\r<a href="clock_get_time.html"><strong>clock_get_time</strong></a>.
\r<p>
\rData Structures:
\r<a href="tvalspec.html"><strong>tvalspec</strong></a>.
\r\ No newline at end of file
+<h2>mapped_tvalspec</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Specifies the format the kernel uses to maintain a mapped clock's time.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct mapped_tvalspec</strong>
+<strong>{</strong>
+ <strong>tvalspec_t</strong> <var>mtv_time</var><strong>;</strong>
+ <strong>unsigned int</strong> <var>mtv_csec</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct mapped_tvalspec mapped_tvalspec_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>mtv_time</var>
+<dd>
+Clock time.
+<p>
+<dt> <var>mtv_csec</var>
+<dd>
+A field used to synchronize with the kernel's setting of the time.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>mapped_tvalspec</strong> structure defines the format of the
+current-time structure
+maintained by the kernel and visible through a mapped clock
+(<strong>clock_map_time</strong>). The data in this structure is updated at the
+clock's current resolution and contains the same <strong>tvalspec</strong> value that
+would be returned by <strong>clock_get_time</strong>.
+<h3>NOTES</h3>
+<p>
+Because of the race between the referencing of the multiple fields
+in the clock
+value and the kernel's setting them, they should be referenced as follows:
+<p>
+<pre>
+ <strong>tvalspec_t* ts;</strong>
+ <strong>do</strong>
+ <strong>{</strong>
+ <strong>ts-> tv_sec = mtime -> mtv_time.tv_sec;</strong>
+ <strong>ts -> tv_nsec = mtime -> mtv_time.tv_nsec;</strong>
+ <strong>} while (ts -> tv_sec != mtime -> mtv_csec);</strong>
+</pre>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="clock_map_time.html"><strong>clock_map_time</strong></a>,
+<a href="clock_get_time.html"><strong>clock_get_time</strong></a>.
+<p>
+Data Structures:
+<a href="tvalspec.html"><strong>tvalspec</strong></a>.
-<h2>memory_object_attr_info</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Specifies memory object's behavior attributes.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct memory_object_attr_info</strong>
\r<strong>{</strong>
\r <strong>memory_object_copy_strategy_t</strong> <var>copy_strategy</var><strong>;</strong>
\r <strong>vm_offset_t</strong> <var>cluster_size</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>may_cache</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>temporary</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct memory_object_attr_info* memory_object_attr_info_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>copy_strategy</var>
\r<dd>
\rHow the kernel should handle copying of regions associated with the
\rmemory object. The copy strategy cannot be changed once an object is
\rinitialized. Valid values are:
\r<dl>
\r<p>
\r<dt> <strong>MEMORY_OBJECT_COPY_NONE</strong>
\r<dd>
\rUse normal procedure when copying the memory object's
\rdata. Normally, the kernel requests each page with read
\raccess, copies the data, and then (optionally) flushes the data.
\r<p>
\r<dt> <strong>MEMORY_OBJECT_COPY_CALL</strong>
\r<dd>
\rCall the memory manager when a copy operation is necessary.
\r<p>
\r<dt> <strong>MEMORY_OBJECT_COPY_DELAY</strong>
\r<dd>
\rUse copy-on-write technique. This strategy allows the kernel
\rto efficiently copy large amounts of data and guarantees that
\rthe memory manager will not externally modify the data. It is
\rthe most commonly used copy strategy.
\r<p>
\r<dt> <strong>MEMORY_OBJECT_COPY_TEMPORARY</strong>
\r<dd>
\rAll changes are made in memory and the memory manager does not need
\rto see them.
\r<p>
\r<dt> <strong>MEMORY_OBJECT_COPY_SYMMETRIC</strong>
\r<dd>
\rThe memory manager does not change the data, does not need to see
\rany changes to the data, and will prevent the object from being
\rmapped more than once. Currently, this strategy should be restricted
\rto use by the kernel.
\r</dl>
\r<p>
\r<dt> <var>cluster_size</var>
\r<dd>
\rThe memory object's perferred cluster size (in bytes). This value may affect
\rthe number of pages transferred in a given paging operation.
\r<p>
\r<dt> <var>may_cache</var>
\r<dd>
\rCache indicator. If true, the kernel can cache data associated with the
\rmemory object (keep the memory object active) even if no virtual
\rmemory references to it remain.
\r<p>
\r<dt> <var>temporary</var>
\r<dd>
\rIf TRUE, when the last mapping to the object is released,
\rthe kernel destroys the object without returning any resident pages.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>memory_object_attr_info</strong> structure defines behavior and
\rperformance relevant memory object attributes.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="MO_get_attributes.html"><strong>memory_object_get_attributes</strong></a>,
\r<a href="MO_change_attributes.html"><strong>memory_object_change_attributes</strong></a>,
\r<a href="vm_region.html"><strong>vm_region</strong></a>,
\r<a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>,
\r<a href="VSD_memory_manager.html"><strong>vm_set_default_memory_manager</strong></a>,
\r<a href="vm_msync.html"><strong>vm_msync</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_attr_info</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Specifies memory object's behavior attributes.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct memory_object_attr_info</strong>
+<strong>{</strong>
+ <strong>memory_object_copy_strategy_t</strong> <var>copy_strategy</var><strong>;</strong>
+ <strong>vm_offset_t</strong> <var>cluster_size</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>may_cache</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>temporary</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct memory_object_attr_info* memory_object_attr_info_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>copy_strategy</var>
+<dd>
+How the kernel should handle copying of regions associated with the
+memory object. The copy strategy cannot be changed once an object is
+initialized. Valid values are:
+<dl>
+<p>
+<dt> <strong>MEMORY_OBJECT_COPY_NONE</strong>
+<dd>
+Use normal procedure when copying the memory object's
+data. Normally, the kernel requests each page with read
+access, copies the data, and then (optionally) flushes the data.
+<p>
+<dt> <strong>MEMORY_OBJECT_COPY_CALL</strong>
+<dd>
+Call the memory manager when a copy operation is necessary.
+<p>
+<dt> <strong>MEMORY_OBJECT_COPY_DELAY</strong>
+<dd>
+Use copy-on-write technique. This strategy allows the kernel
+to efficiently copy large amounts of data and guarantees that
+the memory manager will not externally modify the data. It is
+the most commonly used copy strategy.
+<p>
+<dt> <strong>MEMORY_OBJECT_COPY_TEMPORARY</strong>
+<dd>
+All changes are made in memory and the memory manager does not need
+to see them.
+<p>
+<dt> <strong>MEMORY_OBJECT_COPY_SYMMETRIC</strong>
+<dd>
+The memory manager does not change the data, does not need to see
+any changes to the data, and will prevent the object from being
+mapped more than once. Currently, this strategy should be restricted
+to use by the kernel.
+</dl>
+<p>
+<dt> <var>cluster_size</var>
+<dd>
+The memory object's perferred cluster size (in bytes). This value may affect
+the number of pages transferred in a given paging operation.
+<p>
+<dt> <var>may_cache</var>
+<dd>
+Cache indicator. If true, the kernel can cache data associated with the
+memory object (keep the memory object active) even if no virtual
+memory references to it remain.
+<p>
+<dt> <var>temporary</var>
+<dd>
+If TRUE, when the last mapping to the object is released,
+the kernel destroys the object without returning any resident pages.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>memory_object_attr_info</strong> structure defines behavior and
+performance relevant memory object attributes.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="MO_get_attributes.html"><strong>memory_object_get_attributes</strong></a>,
+<a href="MO_change_attributes.html"><strong>memory_object_change_attributes</strong></a>,
+<a href="vm_region.html"><strong>vm_region</strong></a>,
+<a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>,
+<a href="VSD_memory_manager.html"><strong>vm_set_default_memory_manager</strong></a>,
+<a href="vm_msync.html"><strong>vm_msync</strong></a>.
-<h2>memory_object_create</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Request that the default pager handle management requests on the specified memory object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_create</strong>
\r <strong>(memory_object_t</strong> <var>pager</var>,
\r <strong>memory_object_t</strong> <var>new_memory_object</var>,
\r <strong>vm_size_t</strong> <var>new_object_size</var>,
\r <strong>memory_object_control_t</strong> <var>new_control</var>,
\r <strong>vm_size_t</strong> <var>new_page_size</var><strong>);</strong>
\r\r\r<strong>kern_return_t seqnos_memory_object_create</strong>
\r <strong>(memory_object_t</strong> <var>pager</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>memory_object_t</strong> <var>new_memory_object</var>,
\r <strong>vm_size_t</strong> <var>new_object_size</var>,
\r <strong>memory_object_control_t</strong> <var>new_control</var>,
\r <strong>vm_size_t</strong> <var>new_page_size</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>pager</var>
\r<dd>
\r[in default-pager (receive) right]
\rThe default memory manager service
\rport.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the pager
\rport.
\r<p>
\r<dt> <var>new_memory_object</var>
\r<dd>
\r[in abstract-memory-object receive right]
\rThe port representing the
\rnew abstract memory object created by the kernel.
\r<p>
\r<dt> <var>new_object_size</var>
\r<dd>
\r[in scalar]
\rThe expected size for the new object, in bytes.
\r<p>
\r<dt> <var>new_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used by the memory manager when making cache management
\rrequests for the new object.
\r<p>
\r<dt> <var>new_page_size</var>
\r<dd>
\r[in scalar]
\rThe page size used by the kernel. All calls involving this
\rkernel must use data sizes that are integral multiples of this page size.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>memory_object_create</strong> function is called as the result
\rof a message from the
\rkernel requesting that the default memory manager accept responsibility
\rfor the
\rnew memory object created by the kernel. The kernel makes this
\rcall only to the
\rsystem default memory manager.
\r<p>
\rThe new memory object initially consists of zero-filled pages. Only memory
\rpages that are actually written are provided to the memory manager. When
\rprocessing <strong>memory_object_data_request</strong> calls from the
\rkernel, the default
\rmemory manager must use <strong>memory_object_data_unavailable</strong>
\rfor any pages that have not been written previously.
\r<p>
\rThe kernel does not expect a reply to this call. The kernel assumes that the
\rdefault memory manager will be ready to handle data requests to this object and
\rdoes not need the confirmation of a <strong>memory_object_change_attributes</strong> call.
\r<h3>NOTES</h3>
\r<p>
\rThe kernel requires memory objects to provide temporary backing storage for
\rzero-filled memory created by <strong>vm_allocate</strong> calls, issued
\rby both user tasks and
\rthe kernel itself. The kernel allocates an abstract memory object port to
\rrepresent the temporary backing storage and uses <strong>memory_object_create</strong>
\rto pass the
\rnew memory object to the default memory manager, which provides the storage.
\r<p>
\rThe default memory manager is a trusted system component that is identified to
\rthe kernel at system initialization time. The default memory manager can also
\rbe changed at run time using the <strong>host_default_memory_manager</strong> call.
\r<p>
\rThe contents of a kernel-created (as opposed to a user-created) memory object
\rcan be modified only in main memory. The default memory manager must not
\rchange the contents of a temporary memory object, or allow unrelated tasks to
\raccess the memory object, control, or name port.
\r<p>
\rThe kernel provides the size of a temporary memory object based on the
\rallocated size. Since the object is not mapped by other tasks,
\rthe object will not grow
\rby explicit action. However, the kernel may coalesce adjacent
\rtemporary objects
\rin such a way that this object may appear to grow. As such,
\rthe supplied object
\rsize is merely a hint as to the maximum size.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="DP_object_create.html"><strong>default_pager_object_create</strong></a>,
\r<a href="MO_data_initialize.html"><strong>memory_object_data_initialize</strong></a>,
\r<a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>,
\r<a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>,
\r<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_create</h2>
+<hr>
+<p>
+<strong>Function</strong> - Request that the default pager handle management requests on the specified memory object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_create</strong>
+ <strong>(memory_object_t</strong> <var>pager</var>,
+ <strong>memory_object_t</strong> <var>new_memory_object</var>,
+ <strong>vm_size_t</strong> <var>new_object_size</var>,
+ <strong>memory_object_control_t</strong> <var>new_control</var>,
+ <strong>vm_size_t</strong> <var>new_page_size</var><strong>);</strong>
+
+
+<strong>kern_return_t seqnos_memory_object_create</strong>
+ <strong>(memory_object_t</strong> <var>pager</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>memory_object_t</strong> <var>new_memory_object</var>,
+ <strong>vm_size_t</strong> <var>new_object_size</var>,
+ <strong>memory_object_control_t</strong> <var>new_control</var>,
+ <strong>vm_size_t</strong> <var>new_page_size</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>pager</var>
+<dd>
+[in default-pager (receive) right]
+The default memory manager service
+port.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the pager
+port.
+<p>
+<dt> <var>new_memory_object</var>
+<dd>
+[in abstract-memory-object receive right]
+The port representing the
+new abstract memory object created by the kernel.
+<p>
+<dt> <var>new_object_size</var>
+<dd>
+[in scalar]
+The expected size for the new object, in bytes.
+<p>
+<dt> <var>new_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used by the memory manager when making cache management
+requests for the new object.
+<p>
+<dt> <var>new_page_size</var>
+<dd>
+[in scalar]
+The page size used by the kernel. All calls involving this
+kernel must use data sizes that are integral multiples of this page size.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>memory_object_create</strong> function is called as the result
+of a message from the
+kernel requesting that the default memory manager accept responsibility
+for the
+new memory object created by the kernel. The kernel makes this
+call only to the
+system default memory manager.
+<p>
+The new memory object initially consists of zero-filled pages. Only memory
+pages that are actually written are provided to the memory manager. When
+processing <strong>memory_object_data_request</strong> calls from the
+kernel, the default
+memory manager must use <strong>memory_object_data_unavailable</strong>
+for any pages that have not been written previously.
+<p>
+The kernel does not expect a reply to this call. The kernel assumes that the
+default memory manager will be ready to handle data requests to this object and
+does not need the confirmation of a <strong>memory_object_change_attributes</strong> call.
+<h3>NOTES</h3>
+<p>
+The kernel requires memory objects to provide temporary backing storage for
+zero-filled memory created by <strong>vm_allocate</strong> calls, issued
+by both user tasks and
+the kernel itself. The kernel allocates an abstract memory object port to
+represent the temporary backing storage and uses <strong>memory_object_create</strong>
+to pass the
+new memory object to the default memory manager, which provides the storage.
+<p>
+The default memory manager is a trusted system component that is identified to
+the kernel at system initialization time. The default memory manager can also
+be changed at run time using the <strong>host_default_memory_manager</strong> call.
+<p>
+The contents of a kernel-created (as opposed to a user-created) memory object
+can be modified only in main memory. The default memory manager must not
+change the contents of a temporary memory object, or allow unrelated tasks to
+access the memory object, control, or name port.
+<p>
+The kernel provides the size of a temporary memory object based on the
+allocated size. Since the object is not mapped by other tasks,
+the object will not grow
+by explicit action. However, the kernel may coalesce adjacent
+temporary objects
+in such a way that this object may appear to grow. As such,
+the supplied object
+size is merely a hint as to the maximum size.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="DP_object_create.html"><strong>default_pager_object_create</strong></a>,
+<a href="MO_data_initialize.html"><strong>memory_object_data_initialize</strong></a>,
+<a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>,
+<a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>,
+<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>.
-<h2>memory_object_data_error</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - An error prevents the supply of previously requested data.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_data_error</strong>
\r <strong>(memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>kern_return_t</strong> <var>reason</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used by the memory manager for cache management requests.
\rThis port is provided by the kernel in a <strong>memory_object_create</strong> call.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar]
\rThe offset within the memory object, in bytes.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes of data (starting at <var>offset</var>). The number
\rmust convert to an integral number of memory object pages.
\r<p>
\r<dt> <var>reason</var>
\r<dd>
\r[in scalar]
\rReason for the error.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>memory_object_data_error</strong> function indicates that
\rthe memory manager
\rcannot provide the kernel with the data requested for the given region,
\rspecifying a reason for the error.
\r<p>
\rWhen the kernel issues a <strong>memory_object_data_request</strong> call, the memory
\rmanager can respond with a <strong>memory_object_data_error</strong>
\rcall to indicate that the
\rpage cannot be retrieved, and that a memory failure exception should be raised
\rin any client threads that are waiting for the page. Clients
\rare permitted to catch
\rthese exceptions and retry their page faults. As a result, this
\rcall can be used to
\rreport transient errors as well as permanent ones. A memory manager can use
\rthis call for both hardware errors (for example, disk failures) and software
\rerrors (for example, accessing data that does not exist or is protected).
\r<h3>NOTES</h3>
\r<p>
\rIf reason has a system code of <var>err_kern</var>, the kernel will substitute
\ran error value
\rof <strong>KERN_MEMORY_ERROR</strong>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_data_request.html"><strong>memory_object_data_request</strong></a>,
\r<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>,
\r<a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_data_error</h2>
+<hr>
+<p>
+<strong>Function</strong> - An error prevents the supply of previously requested data.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_data_error</strong>
+ <strong>(memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>kern_return_t</strong> <var>reason</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used by the memory manager for cache management requests.
+This port is provided by the kernel in a <strong>memory_object_create</strong> call.
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar]
+The offset within the memory object, in bytes.
+<p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The number of bytes of data (starting at <var>offset</var>). The number
+must convert to an integral number of memory object pages.
+<p>
+<dt> <var>reason</var>
+<dd>
+[in scalar]
+Reason for the error.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>memory_object_data_error</strong> function indicates that
+the memory manager
+cannot provide the kernel with the data requested for the given region,
+specifying a reason for the error.
+<p>
+When the kernel issues a <strong>memory_object_data_request</strong> call, the memory
+manager can respond with a <strong>memory_object_data_error</strong>
+call to indicate that the
+page cannot be retrieved, and that a memory failure exception should be raised
+in any client threads that are waiting for the page. Clients
+are permitted to catch
+these exceptions and retry their page faults. As a result, this
+call can be used to
+report transient errors as well as permanent ones. A memory manager can use
+this call for both hardware errors (for example, disk failures) and software
+errors (for example, accessing data that does not exist or is protected).
+<h3>NOTES</h3>
+<p>
+If reason has a system code of <var>err_kern</var>, the kernel will substitute
+an error value
+of <strong>KERN_MEMORY_ERROR</strong>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_data_request.html"><strong>memory_object_data_request</strong></a>,
+<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>,
+<a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>.
-<h2>memory_object_data_request</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Request that memory manager page-in specified data.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_data_request</strong>
\r <strong>(memory_object_t</strong> <var>memory_object</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>vm_size_t</strong> <var>length</var>,
\r <strong>vm_prot_t</strong> <var>desired_access</var><strong>);</strong>
\r\r\r<strong>kern_return_t seqnos_memory_object_data_request</strong>
\r <strong>(memory_object_t</strong> <var>memory_object</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>vm_size_t</strong> <var>length</var>,
\r <strong>vm_prot_t</strong> <var>desired_access</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>memory_object</var>
\r<dd>
\r[in abstract-memory-object (receive) right]
\rThe abstract memory
\robject port that represents the memory object data.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the abstract
\rmemory object port.
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used for a response by the memory manager. If the memory
\robject has been supplied to more than one kernel, this parameter
\ridentifies the kernel that is making the call.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar]
\rThe offset within the memory object.
\r<p>
\r<dt> <var>length</var>
\r<dd>
\r[in scalar]
\rThe number of bytes requested, starting at <var>offset</var>. The
\rnumber converts to an integral number of virtual pages.
\r<p>
\r<dt> <var>desired_access</var>
\r<dd>
\r[in scalar]
\rThe memory access modes to be allowed for the cached
\rdata. Possible values are obtained by or'ing together the following
\rvalues:
\r<dl>
\r<p>
\r<dt> <strong>VM_PROT_READ</strong>
\r<dd>
\rAllows read access.
\r<p>
\r<dt> <strong>VM_PROT_WRITE</strong>
\r<dd>
\rAllows write access.
\r<p>
\r<dt> <strong>VM_PROT_EXECUTE</strong>
\r<dd>
\rAllows execute access.
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>memory_object_data_request</strong> function is called as
\rthe result of a kernel
\rmessage requesting data from the specified memory object, for at least the
\raccess specified.
\r<p>
\rThe kernel issues this call after a cache miss (that is, a page
\rfault for which the
\rkernel does not have the data). The kernel requests only amounts
\rof data that are
\rmultiples of the page size included in the
\r<strong>memory_object_init</strong> or <strong>memory_object_create</strong> call.
\r<p>
\rThe memory manager is expected to use <strong>memory_object_data_supply</strong> to
\rreturn at least the specified data, with as much access as it
\rcan allow. If the
\rmemory manager cannot provide the data (for example, because
\rof a hardware error),
\rit can use the <strong>memory_object_data_error</strong> call. The
\rmemory manager can also
\ruse <strong>memory_object_data_unavailable</strong> to tell the kernel
\rto supply zero-filled
\rmemory for the region.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_data_error.html"><strong>memory_object_data_error</strong></a>,
\r<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>,
\r<a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>,
\r<a href="memory_object_server.html"><strong>memory_object_server</strong></a>,
\r<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>.
\r\r\ No newline at end of file
+<h2>memory_object_data_request</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Request that memory manager page-in specified data.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_data_request</strong>
+ <strong>(memory_object_t</strong> <var>memory_object</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>vm_size_t</strong> <var>length</var>,
+ <strong>vm_prot_t</strong> <var>desired_access</var><strong>);</strong>
+
+
+<strong>kern_return_t seqnos_memory_object_data_request</strong>
+ <strong>(memory_object_t</strong> <var>memory_object</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>vm_size_t</strong> <var>length</var>,
+ <strong>vm_prot_t</strong> <var>desired_access</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>memory_object</var>
+<dd>
+[in abstract-memory-object (receive) right]
+The abstract memory
+object port that represents the memory object data.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the abstract
+memory object port.
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used for a response by the memory manager. If the memory
+object has been supplied to more than one kernel, this parameter
+identifies the kernel that is making the call.
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar]
+The offset within the memory object.
+<p>
+<dt> <var>length</var>
+<dd>
+[in scalar]
+The number of bytes requested, starting at <var>offset</var>. The
+number converts to an integral number of virtual pages.
+<p>
+<dt> <var>desired_access</var>
+<dd>
+[in scalar]
+The memory access modes to be allowed for the cached
+data. Possible values are obtained by or'ing together the following
+values:
+<dl>
+<p>
+<dt> <strong>VM_PROT_READ</strong>
+<dd>
+Allows read access.
+<p>
+<dt> <strong>VM_PROT_WRITE</strong>
+<dd>
+Allows write access.
+<p>
+<dt> <strong>VM_PROT_EXECUTE</strong>
+<dd>
+Allows execute access.
+</dl>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>memory_object_data_request</strong> function is called as
+the result of a kernel
+message requesting data from the specified memory object, for at least the
+access specified.
+<p>
+The kernel issues this call after a cache miss (that is, a page
+fault for which the
+kernel does not have the data). The kernel requests only amounts
+of data that are
+multiples of the page size included in the
+<strong>memory_object_init</strong> or <strong>memory_object_create</strong> call.
+<p>
+The memory manager is expected to use <strong>memory_object_data_supply</strong> to
+return at least the specified data, with as much access as it
+can allow. If the
+memory manager cannot provide the data (for example, because
+of a hardware error),
+it can use the <strong>memory_object_data_error</strong> call. The
+memory manager can also
+use <strong>memory_object_data_unavailable</strong> to tell the kernel
+to supply zero-filled
+memory for the region.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_data_error.html"><strong>memory_object_data_error</strong></a>,
+<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>,
+<a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>,
+<a href="memory_object_server.html"><strong>memory_object_server</strong></a>,
+<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>.
+
-<h2>memory_object_data_return</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Return memory object data to the appropriate memory manager.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_data_return</strong>
\r <strong>(memory_object_t</strong> <var>memory_object</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>pointer_t</strong> <var>data</var>,
\r <strong>boolean_t</strong> <var>dirty</var>,
\r <strong>boolean_t</strong> <var>kernel_copy</var><strong>);</strong>
\r\r\r<strong>kern_return_t seqnos_memory_object_data_return</strong>
\r <strong>(memory_object_t</strong> <var>memory_object</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>pointer_t</strong> <var>data</var>,
\r <strong>boolean_t</strong> <var>dirty</var>,
\r <strong>boolean_t</strong> <var>kernel_copy</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>memory_object</var>
\r<dd>
\r[in abstract-memory-object (receive) right]
\rThe abstract memory
\robject port that represents the memory object data.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the abstract
\rmemory object port.
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used for a response by the memory manager. If the memory
\robject has been supplied to more than one kernel, this parameter
\ridentifies the kernel that is making the call.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar]
\rThe offset within the memory object.
\r<p>
\r<dt> <var>data</var>
\r<dd>
\r[in pointer to dynamic array of bytes]
\rThe data that has been evicted
\rfrom the physical memory cache.
\r<p>
\r<dt> <var>dirty</var>
\r<dd>
\r[in scalar]
\rIf <strong>TRUE</strong>, the pages returned have been modified.
\r<p>
\r<dt> <var>kernel_copy</var>
\r<dd>
\r[in scalar]
\rIf <strong>TRUE</strong>, the kernel has kept a copy of the page.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>memory_object_data_return</strong> function is called as the
\rresult of a kernel
\rmessage providing the memory manager with data that has been evicted from the
\rphysical memory cache.
\r<p>
\rThe kernel writes back only data that has been modified or is precious. When
\rthe memory manager no longer needs the data (for example, after the data has
\rbeen written to permanent storage), it should use <strong>vm_deallocate</strong>
\rto release the
\rmemory resources.
\r<h3>NOTES</h3>
\r<p>
\rThe kernel can flush clean (that is, un-modified) non-precious
\rpages at its own
\rdiscretion. As a result, the memory manager cannot rely on the
\rkernel to keep a
\rcopy of its data or even to provide notification that its data
\rhas been discarded.
\r<p>
\rThe kernel may re-request the returned data at any time following this message
\r(including immediately).
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>,
\r<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>,
\r<a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>,
\r<a href="memory_object_server.html"><strong>memory_object_server</strong></a>,
\r<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_data_return</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Return memory object data to the appropriate memory manager.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_data_return</strong>
+ <strong>(memory_object_t</strong> <var>memory_object</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>pointer_t</strong> <var>data</var>,
+ <strong>boolean_t</strong> <var>dirty</var>,
+ <strong>boolean_t</strong> <var>kernel_copy</var><strong>);</strong>
+
+
+<strong>kern_return_t seqnos_memory_object_data_return</strong>
+ <strong>(memory_object_t</strong> <var>memory_object</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>pointer_t</strong> <var>data</var>,
+ <strong>boolean_t</strong> <var>dirty</var>,
+ <strong>boolean_t</strong> <var>kernel_copy</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>memory_object</var>
+<dd>
+[in abstract-memory-object (receive) right]
+The abstract memory
+object port that represents the memory object data.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the abstract
+memory object port.
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used for a response by the memory manager. If the memory
+object has been supplied to more than one kernel, this parameter
+identifies the kernel that is making the call.
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar]
+The offset within the memory object.
+<p>
+<dt> <var>data</var>
+<dd>
+[in pointer to dynamic array of bytes]
+The data that has been evicted
+from the physical memory cache.
+<p>
+<dt> <var>dirty</var>
+<dd>
+[in scalar]
+If <strong>TRUE</strong>, the pages returned have been modified.
+<p>
+<dt> <var>kernel_copy</var>
+<dd>
+[in scalar]
+If <strong>TRUE</strong>, the kernel has kept a copy of the page.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>memory_object_data_return</strong> function is called as the
+result of a kernel
+message providing the memory manager with data that has been evicted from the
+physical memory cache.
+<p>
+The kernel writes back only data that has been modified or is precious. When
+the memory manager no longer needs the data (for example, after the data has
+been written to permanent storage), it should use <strong>vm_deallocate</strong>
+to release the
+memory resources.
+<h3>NOTES</h3>
+<p>
+The kernel can flush clean (that is, un-modified) non-precious
+pages at its own
+discretion. As a result, the memory manager cannot rely on the
+kernel to keep a
+copy of its data or even to provide notification that its data
+has been discarded.
+<p>
+The kernel may re-request the returned data at any time following this message
+(including immediately).
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>,
+<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>,
+<a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>,
+<a href="memory_object_server.html"><strong>memory_object_server</strong></a>,
+<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>.
-<h2>memory_object_data_supply</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Provide kernel with data previously requested by the kernel's Memory Management facility.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_data_supply</strong>
\r <strong>(mem_object_control_port_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>pointer_t</strong> <var>data</var>,
\r <strong>mach_msg_type_number_t</strong> <var>data_count</var>,
\r <strong>boolean_t</strong> <var>deallocate</var>,
\r <strong>vm_prot_t</strong> <var>lock_value</var>,
\r <strong>boolean_t</strong> <var>precious</var>,
\r <strong>mach_port_t</strong> <var>reply_port</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used by the memory manager for cache management requests.
\rThis port is provided by the kernel in a <strong>memory_object_init</strong>
\r or <strong>memory_object_create</strong> call.
\r<p>
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar]
\rThe offset within the memory object, in bytes.
\r<p>
\r<p>
\r<dt> <var>data</var>
\r<dd>
\r[pointer to page aligned in array of bytes]
\rThe address of the data
\rbeing provided to the kernel.
\r<p>
\r<p>
\r<dt> <var>data_count</var>
\r<dd>
\r[in scalar]
\rThe amount of data to be provided. The number must be an
\rintegral number of memory object pages.
\r<p>
\r<p>
\r<dt> <var>deallocate</var>
\r<dd>
\r[in scalar]
\rIf <strong>TRUE</strong>, the pages to be copied (starting at data) will be
\rdeallocated from the memory manager's address space as a result of
\rbeing copied into the message, allowing the pages to be moved into the
\rkernel instead of being physically copied.
\r<p>
\r<p>
\r<dt> <var>lock_value</var>
\r<dd>
\r[in scalar]
\rOne or more forms of access <var>not</var> permitted for the specified
\rdata. Valid values are:
\r<dl>
\r<p>
\r<p>
\r<dt> <strong>VM_PROT_NONE</strong>
\r<dd>
\rProhibits no access (that is, all forms of access are permitted).
\r<p>
\r<p>
\r<dt> <strong>VM_PROT_READ</strong>
\r<dd>
\rProhibits read access.
\r<p>
\r<p>
\r<dt> <strong>VM_PROT_WRITE</strong>
\r<dd>
\rProhibits write access.
\r<p>
\r<p>
\r<dt> <strong>VM_PROT_EXECUTE</strong>
\r<dd>
\rProhibits execute access.
\r<p>
\r<p>
\r<dt> <strong>VM_PROT_ALL</strong>
\r<dd>
\rProhibits all forms of access.
\r</dl>
\r<p>
\r<p>
\r<dt> <var>precious</var>
\r<dd>
\r[in scalar]
\rIf <strong>TRUE</strong>, the pages being supplied are "precious," that is,
\rthe memory manager is not (necessarily) retaining its own copy. These
\rpages must be returned to the manager when evicted from memory,
\reven if not modified.
\r<p>
\r<p>
\r<dt> <var>reply_port</var>
\r<dd>
\r[in reply receive (to be converted to send) right]
\rA port to which the
\rkernel should send a <strong>memory_object_supply_completed</strong> to indicate
\rthe status of the accepted data. <strong>MACH_PORT_NULL</strong> is allowed. The
\rreply message indicates which pages have been accepted.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>memory_object_data_supply</strong> function supplies the
\rkernel with a range of
\rdata for the specified memory object. A memory manager can only provide data
\rthat was requested by a <strong>memory_object_data_request</strong>
\rcall from the kernel.
\r<h3>NOTES</h3>
\r<p>
\rThe kernel accepts only integral numbers of pages. It discards
\rany partial pages
\rwithout notification.
\r<h3>CAUTIONS</h3>
\r<p>
\rA memory manager must be careful that it not attempt to provide data that has
\rnot been explicitly requested. In particular, a memory manager
\rmust ensure that
\rit does not provide writable data again before it receives back modifications
\rfrom the kernel. This may require that the memory manager remember which
\rpages it has provided, or that it exercise other cache control functions (via
\r<strong>memory_object_lock_request</strong>) before proceeding. The kernel prohibits the
\roverwriting of live data pages and will not accept pages it has not requested.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_data_error.html"><strong>memory_object_data_error</strong></a>,
\r<a href="memory_object_data_request.html"><strong>memory_object_data_request</strong></a>,
\r<a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>,
\r<a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>,
\r<a href="MO_supply_completed.html"><strong>memory_object_supply_completed</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_data_supply</h2>
+<hr>
+<p>
+<strong>Function</strong> - Provide kernel with data previously requested by the kernel's Memory Management facility.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_data_supply</strong>
+ <strong>(mem_object_control_port_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>pointer_t</strong> <var>data</var>,
+ <strong>mach_msg_type_number_t</strong> <var>data_count</var>,
+ <strong>boolean_t</strong> <var>deallocate</var>,
+ <strong>vm_prot_t</strong> <var>lock_value</var>,
+ <strong>boolean_t</strong> <var>precious</var>,
+ <strong>mach_port_t</strong> <var>reply_port</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used by the memory manager for cache management requests.
+This port is provided by the kernel in a <strong>memory_object_init</strong>
+ or <strong>memory_object_create</strong> call.
+<p>
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar]
+The offset within the memory object, in bytes.
+<p>
+<p>
+<dt> <var>data</var>
+<dd>
+[pointer to page aligned in array of bytes]
+The address of the data
+being provided to the kernel.
+<p>
+<p>
+<dt> <var>data_count</var>
+<dd>
+[in scalar]
+The amount of data to be provided. The number must be an
+integral number of memory object pages.
+<p>
+<p>
+<dt> <var>deallocate</var>
+<dd>
+[in scalar]
+If <strong>TRUE</strong>, the pages to be copied (starting at data) will be
+deallocated from the memory manager's address space as a result of
+being copied into the message, allowing the pages to be moved into the
+kernel instead of being physically copied.
+<p>
+<p>
+<dt> <var>lock_value</var>
+<dd>
+[in scalar]
+One or more forms of access <var>not</var> permitted for the specified
+data. Valid values are:
+<dl>
+<p>
+<p>
+<dt> <strong>VM_PROT_NONE</strong>
+<dd>
+Prohibits no access (that is, all forms of access are permitted).
+<p>
+<p>
+<dt> <strong>VM_PROT_READ</strong>
+<dd>
+Prohibits read access.
+<p>
+<p>
+<dt> <strong>VM_PROT_WRITE</strong>
+<dd>
+Prohibits write access.
+<p>
+<p>
+<dt> <strong>VM_PROT_EXECUTE</strong>
+<dd>
+Prohibits execute access.
+<p>
+<p>
+<dt> <strong>VM_PROT_ALL</strong>
+<dd>
+Prohibits all forms of access.
+</dl>
+<p>
+<p>
+<dt> <var>precious</var>
+<dd>
+[in scalar]
+If <strong>TRUE</strong>, the pages being supplied are "precious," that is,
+the memory manager is not (necessarily) retaining its own copy. These
+pages must be returned to the manager when evicted from memory,
+even if not modified.
+<p>
+<p>
+<dt> <var>reply_port</var>
+<dd>
+[in reply receive (to be converted to send) right]
+A port to which the
+kernel should send a <strong>memory_object_supply_completed</strong> to indicate
+the status of the accepted data. <strong>MACH_PORT_NULL</strong> is allowed. The
+reply message indicates which pages have been accepted.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>memory_object_data_supply</strong> function supplies the
+kernel with a range of
+data for the specified memory object. A memory manager can only provide data
+that was requested by a <strong>memory_object_data_request</strong>
+call from the kernel.
+<h3>NOTES</h3>
+<p>
+The kernel accepts only integral numbers of pages. It discards
+any partial pages
+without notification.
+<h3>CAUTIONS</h3>
+<p>
+A memory manager must be careful that it not attempt to provide data that has
+not been explicitly requested. In particular, a memory manager
+must ensure that
+it does not provide writable data again before it receives back modifications
+from the kernel. This may require that the memory manager remember which
+pages it has provided, or that it exercise other cache control functions (via
+<strong>memory_object_lock_request</strong>) before proceeding. The kernel prohibits the
+overwriting of live data pages and will not accept pages it has not requested.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_data_error.html"><strong>memory_object_data_error</strong></a>,
+<a href="memory_object_data_request.html"><strong>memory_object_data_request</strong></a>,
+<a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>,
+<a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>,
+<a href="MO_supply_completed.html"><strong>memory_object_supply_completed</strong></a>.
-<h2>memory_object_data_unlock</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Request that the memory manager change current access permission on the specified memory object's data.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_data_unlock</strong>
\r <strong>(memory_object_t</strong> <var>memory_object</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>vm_size_t</strong> <var>length</var>,
\r <strong>vm_prot_t</strong> <var>desired_access</var><strong>);</strong>
\r\r\r<strong>kern_return_t seqnos_memory_object_data_unlock</strong>
\r <strong>(memory_object_t</strong> <var>memory_object</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>vm_size_t</strong> <var>length</var>,
\r <strong>vm_prot_t</strong> <var>desired_access</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>memory_object</var>
\r<dd>
\r[in abstract-memory-object (receive) right]
\rThe abstract memory
\robject port that represents the memory object data.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the abstract
\rmemory object port.
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used for a response by the memory manager. If the memory
\robject has been supplied to more than one kernel, this parameter
\ridentifies the kernel that is making the call.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar]
\rThe offset within the memory object.
\r<p>
\r<dt> <var>length</var>
\r<dd>
\r[in scalar]
\rThe number of bytes to which the access applies, starting at
\r<var>offset</var>. The number converts to an integral number of memory object
\rpages.
\r<p>
\r<dt> <var>desired_access</var>
\r<dd>
\r[in scalar]
\rThe memory access modes requested for the cached data.
\rPossible values are obtained by or'ing together the following values:
\r<dl>
\r<p>
\r<dt> <strong>VM_PROT_READ</strong>
\r<dd>
\rAllows read access.
\r<p>
\r<dt> <strong>VM_PROT_WRITE</strong>
\r<dd>
\rAllows write access.
\r<p>
\r<dt> <strong>VM_PROT_EXECUTE</strong>
\r<dd>
\rAllows execute access.
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>memory_object_data_unlock</strong> function is called as the
\rresult of a kernel
\rmessage requesting the memory manager to permit at least the
\rdesired access to the
\rspecified data cached by the kernel. The memory manager is expected
\rto use the
\r<strong>memory_object_lock_request</strong> call in response.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="MO_lock_completed.html"><strong>memory_object_lock_completed</strong></a>,
\r<a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>,
\r<a href="memory_object_server.html"><strong>memory_object_server</strong></a>,
\r<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_data_unlock</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Request that the memory manager change current access permission on the specified memory object's data.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_data_unlock</strong>
+ <strong>(memory_object_t</strong> <var>memory_object</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>vm_size_t</strong> <var>length</var>,
+ <strong>vm_prot_t</strong> <var>desired_access</var><strong>);</strong>
+
+
+<strong>kern_return_t seqnos_memory_object_data_unlock</strong>
+ <strong>(memory_object_t</strong> <var>memory_object</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>vm_size_t</strong> <var>length</var>,
+ <strong>vm_prot_t</strong> <var>desired_access</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>memory_object</var>
+<dd>
+[in abstract-memory-object (receive) right]
+The abstract memory
+object port that represents the memory object data.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the abstract
+memory object port.
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used for a response by the memory manager. If the memory
+object has been supplied to more than one kernel, this parameter
+identifies the kernel that is making the call.
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar]
+The offset within the memory object.
+<p>
+<dt> <var>length</var>
+<dd>
+[in scalar]
+The number of bytes to which the access applies, starting at
+<var>offset</var>. The number converts to an integral number of memory object
+pages.
+<p>
+<dt> <var>desired_access</var>
+<dd>
+[in scalar]
+The memory access modes requested for the cached data.
+Possible values are obtained by or'ing together the following values:
+<dl>
+<p>
+<dt> <strong>VM_PROT_READ</strong>
+<dd>
+Allows read access.
+<p>
+<dt> <strong>VM_PROT_WRITE</strong>
+<dd>
+Allows write access.
+<p>
+<dt> <strong>VM_PROT_EXECUTE</strong>
+<dd>
+Allows execute access.
+</dl>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>memory_object_data_unlock</strong> function is called as the
+result of a kernel
+message requesting the memory manager to permit at least the
+desired access to the
+specified data cached by the kernel. The memory manager is expected
+to use the
+<strong>memory_object_lock_request</strong> call in response.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="MO_lock_completed.html"><strong>memory_object_lock_completed</strong></a>,
+<a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>,
+<a href="memory_object_server.html"><strong>memory_object_server</strong></a>,
+<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>.
-<h2>memory_object_destroy</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Shut down a memory object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_destroy</strong>
\r <strong>(memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>kern_return_t</strong> <var>reason</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used by the memory manager for cache management requests.
\rThis port is provided by the kernel in a <strong>memory_object_init</strong> call.
\r<p>
\r<dt> <var>reason</var>
\r<dd>
\r[in scalar]
\rAn error code indicating when the object must be destroyed.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>memory_object_destroy</strong> function tells the kernel to shut down the
\rspecified memory object. As a result of this call, the kernel
\rno longer supports
\rpaging activity or any memory object calls on the memory object.
\rThe kernel issues
\ra <strong>memory_object_terminate</strong> call to pass to the memory
\rmanager all rights to
\rthe memory object port and the memory control port.
\r<p>
\rTo ensure that any modified cached data is returned before the object is
\rterminated, the memory manager should call <strong>memory_object_lock_request</strong>
\rwith
\r<var>should_flush</var> set and a
\rlock value of <strong>VM_PROT_WRITE</strong> before it makes the
\r<strong>memory_object_destroy</strong> call.
\r<h3>NOTES</h3>
\r<p>
\rThe <var>reason</var> code is currently ignored by the kernel.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>,
\r<a href="memory_object_terminate.html"><strong>memory_object_terminate</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_destroy</h2>
+<hr>
+<p>
+<strong>Function</strong> - Shut down a memory object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_destroy</strong>
+ <strong>(memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>kern_return_t</strong> <var>reason</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used by the memory manager for cache management requests.
+This port is provided by the kernel in a <strong>memory_object_init</strong> call.
+<p>
+<dt> <var>reason</var>
+<dd>
+[in scalar]
+An error code indicating when the object must be destroyed.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>memory_object_destroy</strong> function tells the kernel to shut down the
+specified memory object. As a result of this call, the kernel
+no longer supports
+paging activity or any memory object calls on the memory object.
+The kernel issues
+a <strong>memory_object_terminate</strong> call to pass to the memory
+manager all rights to
+the memory object port and the memory control port.
+<p>
+To ensure that any modified cached data is returned before the object is
+terminated, the memory manager should call <strong>memory_object_lock_request</strong>
+with
+<var>should_flush</var> set and a
+lock value of <strong>VM_PROT_WRITE</strong> before it makes the
+<strong>memory_object_destroy</strong> call.
+<h3>NOTES</h3>
+<p>
+The <var>reason</var> code is currently ignored by the kernel.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>,
+<a href="memory_object_terminate.html"><strong>memory_object_terminate</strong></a>.
-<h2>memory_object_init</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Initializes a memory object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_init</strong>
\r <strong>(memory_object_t</strong> <var>memory_object</var>,
\r <strong>memory_object_control_t </strong><var>memory_control</var>,
\r <strong>vm_size_t</strong> <var>memory_object_page_size</var><strong>);</strong>
\r\r\r<strong>kern_return_t seqnos_memory_object_init</strong>
\r <strong>(memory_object_t</strong> <var>memory_object</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_size_t</strong> <var>memory_object_page_size</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>memory_object</var>
\r<dd>
\r[in abstract-memory-object port] The abstract memory object port that represents the memory object data, as supplied to the kernel in a vm_map call.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar] The sequence number of this message relative to the abstract memory object port.
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control port] The memory cache control port to be used by the memory manager. If the memory object has been supplied to more than one kernel, this parameter identifies the kernel that is making the call.
\r<p>
\r<dt> <var>memory_object_page_size</var>
\r<dd>
\r[in scalar] The page size used by the kernel. All calls involving this kernel must use data sizes that are integral multiples of this page size.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>memory_object_init</strong> function is called as the result
\rof a kernel message notifying a memory manager that the kernel has
\rbeen asked to map the specified memory object into a task's virtual
\raddress space. When asked to map a memory object for the first time,
\rthe kernel responds by making a <strong>memory_object_init</strong>
\rcall on the abstract memory object. This call is provided as a
\rconvenience to the memory manager, to allow it to initialize data
\rstructures and prepare to receive other requests.
\r<p>
\rIn addition to the
\rabstract memory object port itself, the call provides
\ra memory cache control port that the memory manager can use to
\rcontrol use of its data by the kernel. The memory manager gets send
\rrights for this port.
\r<p>
\rThe kernel holds send rights for the abstract memory object port, and
\rboth send and receive rights for the memory cache control port.
\rThe call also supplies the virtual page size to be used for
\rthe memory mapping. The memory manager can use this size to detect
\rmappings that use different data structures at initialization time, or
\rto allocate buffers for use in reading data.
\r<p>
\rIf a memory object is
\rmapped into the address space of more than one task on different hosts
\r(with independent kernels), the memory manager will receive a
\r<strong>memory_object_init</strong> call from each kernel, containing
\ra unique set of control and name ports. Note that each kernel may also
\ruse a different page size.
\r<h3>RETURN VALUES</h3>
\r<p>
\r\rAny return value other than <strong>KERN_SUCCESS</strong>
\ror <strong>MIG_NO_REPLY</strong>will cause
\r<strong>mach_msg_server</strong> to remove the memory cache control reference.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_terminate.html"><strong>memory_object_terminate</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_init</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Initializes a memory object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_init</strong>
+ <strong>(memory_object_t</strong> <var>memory_object</var>,
+ <strong>memory_object_control_t </strong><var>memory_control</var>,
+ <strong>vm_size_t</strong> <var>memory_object_page_size</var><strong>);</strong>
+
+
+<strong>kern_return_t seqnos_memory_object_init</strong>
+ <strong>(memory_object_t</strong> <var>memory_object</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_size_t</strong> <var>memory_object_page_size</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>memory_object</var>
+<dd>
+[in abstract-memory-object port] The abstract memory object port that represents the memory object data, as supplied to the kernel in a vm_map call.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar] The sequence number of this message relative to the abstract memory object port.
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control port] The memory cache control port to be used by the memory manager. If the memory object has been supplied to more than one kernel, this parameter identifies the kernel that is making the call.
+<p>
+<dt> <var>memory_object_page_size</var>
+<dd>
+[in scalar] The page size used by the kernel. All calls involving this kernel must use data sizes that are integral multiples of this page size.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>memory_object_init</strong> function is called as the result
+of a kernel message notifying a memory manager that the kernel has
+been asked to map the specified memory object into a task's virtual
+address space. When asked to map a memory object for the first time,
+the kernel responds by making a <strong>memory_object_init</strong>
+call on the abstract memory object. This call is provided as a
+convenience to the memory manager, to allow it to initialize data
+structures and prepare to receive other requests.
+<p>
+In addition to the
+abstract memory object port itself, the call provides
+a memory cache control port that the memory manager can use to
+control use of its data by the kernel. The memory manager gets send
+rights for this port.
+<p>
+The kernel holds send rights for the abstract memory object port, and
+both send and receive rights for the memory cache control port.
+The call also supplies the virtual page size to be used for
+the memory mapping. The memory manager can use this size to detect
+mappings that use different data structures at initialization time, or
+to allocate buffers for use in reading data.
+<p>
+If a memory object is
+mapped into the address space of more than one task on different hosts
+(with independent kernels), the memory manager will receive a
+<strong>memory_object_init</strong> call from each kernel, containing
+a unique set of control and name ports. Note that each kernel may also
+use a different page size.
+<h3>RETURN VALUES</h3>
+<p>
+
+Any return value other than <strong>KERN_SUCCESS</strong>
+or <strong>MIG_NO_REPLY</strong>will cause
+<strong>mach_msg_server</strong> to remove the memory cache control reference.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_terminate.html"><strong>memory_object_terminate</strong></a>.
-<h2>memory_object_lock_request</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Restrict access to memory object data.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_lock_request</strong>
\r <strong>(memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>memory_object_return_t</strong> <var>should_return</var>,
\r <strong>boolean_t</strong> <var>should_flush</var>,
\r <strong>vm_prot_t</strong> <var>lock_value</var>,
\r <strong>mach_port_t</strong> <var>reply_port</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used by the memory manager for cache management requests.
\rThis port is provided by the kernel in a <strong>memory_object_init</strong> call.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar]
\rThe offset within the memory object, in bytes.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes of data (starting at <var>offset</var>) to be
\raffected. The number must convert to an integral number of memory object
\rpages.
\r<p>
\r<dt> <var>should_return</var>
\r<dd>
\r[in scalar]
\rClean indicator. Values are:
\r<dl>
\r<p>
\r<dt> <strong>MEMORY_OBJECT_RETURN_NONE</strong>
\r<dd>
\rDon't return any pages. If <var>should_flush</var> is <strong>TRUE</strong>, pages will
\rbe discarded.
\r<p>
\r<dt> <strong>MEMORY_OBJECT_RETURN_DIRTY</strong>
\r<dd>
\rReturn only dirty (modified) pages. If <var>should_flush</var> is <strong>TRUE</strong>,
\rprecious pages will be discarded; otherwise, the kernel
\rmaintains responsibility for precious pages.
\r<p>
\r<dt> <strong>MEMORY_OBJECT_RETURN_ALL</strong>
\r<dd>
\rBoth dirty and precious pages are returned. If <var>should_flush</var> is
\r<strong>FALSE</strong>, the kernel maintains responsibility for the precious
\rpages.
\r<p>
\r<dt> <strong>MEMORY_OBJECT_RETURN_ANYTHING</strong>
\r<dd>
\rAny resident pages are returned. If <var>should_flush</var> is <strong>TRUE</strong>,
\rprecious pages will be discarded; otherwise, the kernel
\rmaintains responsibility for precious pages.
\r</dl>
\r<p>
\r<dt> <var>should_flush</var>
\r<dd>
\r[in scalar]
\rFlush indicator. If true, the kernel discards all pages within
\rthe range.
\r<p>
\r<dt> <var>lock_value</var>
\r<dd>
\r[in scalar]
\rOne or more forms of access <var>not</var> permitted for the specified
\rdata. Valid values are:
\r<dl>
\r<p>
\r<dt> <strong>VM_PROT_NO_CHANGE</strong>
\r<dd>
\rDo not change the protection of any pages.
\r<p>
\r<dt> <strong>VM_PROT_NONE</strong>
\r<dd>
\rProhibits no access (that is, all forms of access are permitted).
\r<p>
\r<dt> <strong>VM_PROT_READ</strong>
\r<dd>
\rProhibits read access.
\r<p>
\r<dt> <strong>VM_PROT_WRITE</strong>
\r<dd>
\rProhibits write access.
\r<p>
\r<dt> <strong>VM_PROT_EXECUTE</strong>
\r<dd>
\rProhibits execute access.
\r<p>
\r<dt> <strong>VM_PROT_ALL</strong>
\r<dd>
\rProhibits all forms of access.
\r</dl>
\r<p>
\r<dt> <var>reply_port</var>
\r<dd>
\r[in reply receive (to be converted to send) right]
\rThe response port to
\rbe used by the kernel on a call to <strong>memory_object_lock_completed</strong>,
\ror <strong>MACH_PORT_NULL</strong> if no response is required.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>memory_object_lock_request</strong> function allows the memory manager to
\rmake the following requests of the kernel:
\r<ul>
\r<li>
\rClean the pages within the specified range by writing back all changed (that
\ris, dirty) and precious pages. The kernel uses the
\r<strong>memory_object_data_return</strong> call to write back the data.
\rThe <var>should_return</var> parameter must be set to
\rnon-zero.
\r <p>
\r<li>
\rFlush all cached data within the specified range. The kernel invalidates the
\rrange of data and revokes all uses of that data. The <var>should_flush</var>
\rparameter must be set to true.
\r <p>
\r<li>
\rAlter access restrictions specified in the <strong>memory_object_data_supply</strong>
\rcall
\ror a previous <strong>memory_object_lock_request</strong> call. The
\r<var>lock_value</var> parameter
\rmust specify the new access restrictions. Note that this parameter can be
\rused to unlock previously locked data.
\r</ul>
\r<p>
\rOnce the kernel performs all of the actions requested by this
\rcall, it issues a
\r<strong>memory_object_lock_completed</strong> call using the <var>reply_to</var> port.
\r<h3>NOTES</h3>
\r<p>
\rThe <strong>memory_object_lock_request</strong> call affects only data
\rthat is cached at the
\rtime of the call. Access restrictions cannot be applied to pages
\rfor which data
\rhas not been provided.
\r<p>
\rWhen a running thread requires an access that is currently prohibited,
\rthe kernel
\rissues a <strong>memory_object_data_unlock</strong> call specifying
\rthe access required. The
\rmemory manager can then use <strong>memory_object_lock_request</strong> to relax its
\raccess restrictions on the data.
\r<p>
\rTo indicate that an unlock request is invalid (that is, requires
\rpermission that can
\rnever be granted), the memory manager must first flush the page. When the
\rkernel requests the data again with the higher permission, the
\rmemory manager can
\rindicate the error by responding with a call to
\r<strong>memory_object_data_error</strong>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>,
\r<a href="memory_object_data_unlock.html"><strong>memory_object_data_unlock</strong></a>,
\r<a href="MO_lock_completed.html"><strong>memory_object_lock_completed</strong></a>.
\r\r\ No newline at end of file
+<h2>memory_object_lock_request</h2>
+<hr>
+<p>
+<strong>Function</strong> - Restrict access to memory object data.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_lock_request</strong>
+ <strong>(memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>memory_object_return_t</strong> <var>should_return</var>,
+ <strong>boolean_t</strong> <var>should_flush</var>,
+ <strong>vm_prot_t</strong> <var>lock_value</var>,
+ <strong>mach_port_t</strong> <var>reply_port</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used by the memory manager for cache management requests.
+This port is provided by the kernel in a <strong>memory_object_init</strong> call.
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar]
+The offset within the memory object, in bytes.
+<p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The number of bytes of data (starting at <var>offset</var>) to be
+affected. The number must convert to an integral number of memory object
+pages.
+<p>
+<dt> <var>should_return</var>
+<dd>
+[in scalar]
+Clean indicator. Values are:
+<dl>
+<p>
+<dt> <strong>MEMORY_OBJECT_RETURN_NONE</strong>
+<dd>
+Don't return any pages. If <var>should_flush</var> is <strong>TRUE</strong>, pages will
+be discarded.
+<p>
+<dt> <strong>MEMORY_OBJECT_RETURN_DIRTY</strong>
+<dd>
+Return only dirty (modified) pages. If <var>should_flush</var> is <strong>TRUE</strong>,
+precious pages will be discarded; otherwise, the kernel
+maintains responsibility for precious pages.
+<p>
+<dt> <strong>MEMORY_OBJECT_RETURN_ALL</strong>
+<dd>
+Both dirty and precious pages are returned. If <var>should_flush</var> is
+<strong>FALSE</strong>, the kernel maintains responsibility for the precious
+pages.
+<p>
+<dt> <strong>MEMORY_OBJECT_RETURN_ANYTHING</strong>
+<dd>
+Any resident pages are returned. If <var>should_flush</var> is <strong>TRUE</strong>,
+precious pages will be discarded; otherwise, the kernel
+maintains responsibility for precious pages.
+</dl>
+<p>
+<dt> <var>should_flush</var>
+<dd>
+[in scalar]
+Flush indicator. If true, the kernel discards all pages within
+the range.
+<p>
+<dt> <var>lock_value</var>
+<dd>
+[in scalar]
+One or more forms of access <var>not</var> permitted for the specified
+data. Valid values are:
+<dl>
+<p>
+<dt> <strong>VM_PROT_NO_CHANGE</strong>
+<dd>
+Do not change the protection of any pages.
+<p>
+<dt> <strong>VM_PROT_NONE</strong>
+<dd>
+Prohibits no access (that is, all forms of access are permitted).
+<p>
+<dt> <strong>VM_PROT_READ</strong>
+<dd>
+Prohibits read access.
+<p>
+<dt> <strong>VM_PROT_WRITE</strong>
+<dd>
+Prohibits write access.
+<p>
+<dt> <strong>VM_PROT_EXECUTE</strong>
+<dd>
+Prohibits execute access.
+<p>
+<dt> <strong>VM_PROT_ALL</strong>
+<dd>
+Prohibits all forms of access.
+</dl>
+<p>
+<dt> <var>reply_port</var>
+<dd>
+[in reply receive (to be converted to send) right]
+The response port to
+be used by the kernel on a call to <strong>memory_object_lock_completed</strong>,
+or <strong>MACH_PORT_NULL</strong> if no response is required.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>memory_object_lock_request</strong> function allows the memory manager to
+make the following requests of the kernel:
+<ul>
+<li>
+Clean the pages within the specified range by writing back all changed (that
+is, dirty) and precious pages. The kernel uses the
+<strong>memory_object_data_return</strong> call to write back the data.
+The <var>should_return</var> parameter must be set to
+non-zero.
+ <p>
+<li>
+Flush all cached data within the specified range. The kernel invalidates the
+range of data and revokes all uses of that data. The <var>should_flush</var>
+parameter must be set to true.
+ <p>
+<li>
+Alter access restrictions specified in the <strong>memory_object_data_supply</strong>
+call
+or a previous <strong>memory_object_lock_request</strong> call. The
+<var>lock_value</var> parameter
+must specify the new access restrictions. Note that this parameter can be
+used to unlock previously locked data.
+</ul>
+<p>
+Once the kernel performs all of the actions requested by this
+call, it issues a
+<strong>memory_object_lock_completed</strong> call using the <var>reply_to</var> port.
+<h3>NOTES</h3>
+<p>
+The <strong>memory_object_lock_request</strong> call affects only data
+that is cached at the
+time of the call. Access restrictions cannot be applied to pages
+for which data
+has not been provided.
+<p>
+When a running thread requires an access that is currently prohibited,
+the kernel
+issues a <strong>memory_object_data_unlock</strong> call specifying
+the access required. The
+memory manager can then use <strong>memory_object_lock_request</strong> to relax its
+access restrictions on the data.
+<p>
+To indicate that an unlock request is invalid (that is, requires
+permission that can
+never be granted), the memory manager must first flush the page. When the
+kernel requests the data again with the higher permission, the
+memory manager can
+indicate the error by responding with a call to
+<strong>memory_object_data_error</strong>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>,
+<a href="memory_object_data_unlock.html"><strong>memory_object_data_unlock</strong></a>,
+<a href="MO_lock_completed.html"><strong>memory_object_lock_completed</strong></a>.
+
-<h2>memory_object_perf_info</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Specifies a memory object's attributes with respect to performance.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct memory_object_perf_info</strong>
\r<strong>{</strong>
\r <strong>vm_offset_t</strong> <var>cluster_size</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>may_cache_object</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct memory_object_perf_info* memory_object_perf_info_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>cluster_size</var>
\r<dd>
\rPreferred cluster size (in bytes) for the memory object. This helps to
\rdetermine how many pages are transferred in individual data request
\rand return messages.
\r<p>
\r<dt> <var>may_cache_object</var>
\r<dd>
\rCache indicator. If true, the kernel can cache data associated with the
\rmemory object (keep the memory object active) even if no virtual
\rmemory references to it remain.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>memory_object_perf_info</strong> structure
\rdefines a memory object's character with respect to performance.
\r<h3>NOTES</h3>
\r<p>
\rSharing cached data among all the clients of a memory object can have a major
\rimpact on performance, especially if it can be extended across successive, as
\rwell as concurrent, uses. For example, the memory objects that represent
\rprogram images can be used regularly by different programs.
\rBy retaining the data
\rfor these memory objects in cache, the number of secondary storage accesses
\rcan be reduced significantly.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="MO_get_attributes.html"><strong>memory_object_get_attributes</strong></a>,
\r<a href="MO_change_attributes.html"><strong>memory_object_change_attributes</strong></a>,
\r<a href="vm_region.html"><strong>vm_region</strong></a>,
\r<a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>,
\r<a href="VSD_memory_manager.html"><strong>vm_set_default_memory_manager</strong></a>,
\r<a href="vm_msync.html"><strong>vm_msync</strong></a>.
\r<p>
\rStructures:
\r<a href="memory_object_attr_info.html"><strong>memory_object_attr_info</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_perf_info</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Specifies a memory object's attributes with respect to performance.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct memory_object_perf_info</strong>
+<strong>{</strong>
+ <strong>vm_offset_t</strong> <var>cluster_size</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>may_cache_object</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct memory_object_perf_info* memory_object_perf_info_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>cluster_size</var>
+<dd>
+Preferred cluster size (in bytes) for the memory object. This helps to
+determine how many pages are transferred in individual data request
+and return messages.
+<p>
+<dt> <var>may_cache_object</var>
+<dd>
+Cache indicator. If true, the kernel can cache data associated with the
+memory object (keep the memory object active) even if no virtual
+memory references to it remain.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>memory_object_perf_info</strong> structure
+defines a memory object's character with respect to performance.
+<h3>NOTES</h3>
+<p>
+Sharing cached data among all the clients of a memory object can have a major
+impact on performance, especially if it can be extended across successive, as
+well as concurrent, uses. For example, the memory objects that represent
+program images can be used regularly by different programs.
+By retaining the data
+for these memory objects in cache, the number of secondary storage accesses
+can be reduced significantly.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="MO_get_attributes.html"><strong>memory_object_get_attributes</strong></a>,
+<a href="MO_change_attributes.html"><strong>memory_object_change_attributes</strong></a>,
+<a href="vm_region.html"><strong>vm_region</strong></a>,
+<a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>,
+<a href="VSD_memory_manager.html"><strong>vm_set_default_memory_manager</strong></a>,
+<a href="vm_msync.html"><strong>vm_msync</strong></a>.
+<p>
+Structures:
+<a href="memory_object_attr_info.html"><strong>memory_object_attr_info</strong></a>.
-<h2>memory_object_server</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Handle kernel operation request aimed at a given memory manager.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>boolean_t memory_object_server</strong>
\r <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
\r <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>in_msg</var>
\r<dd>
\r[pointer to in structure]
\rThe memory manager message received from
\rthe kernel.
\r<p>
\r<dt> <var>out_msg</var>
\r<dd>
\r[out structure]
\rA reply message. No messages to a memory manager
\rexpect a direct reply, so this field is not used.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>memory_object_server</strong> function is the MIG generated
\rserver handling
\rfunction to handle messages from the kernel targeted to a memory manager.
\r<p>
\rA \*Vmemory manager\*O
\ris a server task that responds to specific messages from the
\rkernel in order to handle memory management functions for the kernel. The
\r<strong>memory_object_server</strong> function performs all necessary
\rargument handling for
\ra kernel message and calls one of the memory manager functions to interpret
\rthe message.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>TRUE</strong>
\r<dd>
\rThe message was handled and the appropriate function was called.
\r<p>
\r<dt> <strong>FALSE</strong>
\r<dd>
\rThe message did not apply to this memory management interface and
\rno other action was taken.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="MO_default_server.html"><strong>memory_object_default_server<strong></a>,
\r<a href="memory_object_data_request.html"><strong>memory_object_data_request<strong></a>,
\r<a href="memory_object_data_return.html"><strong>memory_object_data_return<strong></a>,
\r<a href="memory_object_data_unlock.html"><strong>memory_object_data_unlock<strong></a>,
\r<a href="MO_lock_completed.html"><strong>memory_object_lock_completed<strong></a>,
\r<a href="MO_change_completed.html"><strong>memory_object_change_completed<strong></a>,
\r<a href="MO_supply_completed.html"><strong>memory_object_supply_completed<strong></a>,
\r<a href="memory_object_terminate.html"><strong>memory_object_terminate<strong></a>,
\r<a href="memory_object_synchronize.html"><strong>memory_object_synchronize<strong></a>,
\r<a href="SMO_server.html"><strong>seqnos_memory_object_server<strong></a>.
\r\ No newline at end of file
+<h2>memory_object_server</h2>
+<hr>
+<p>
+<strong>Function</strong> - Handle kernel operation request aimed at a given memory manager.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>boolean_t memory_object_server</strong>
+ <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
+ <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>in_msg</var>
+<dd>
+[pointer to in structure]
+The memory manager message received from
+the kernel.
+<p>
+<dt> <var>out_msg</var>
+<dd>
+[out structure]
+A reply message. No messages to a memory manager
+expect a direct reply, so this field is not used.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>memory_object_server</strong> function is the MIG generated
+server handling
+function to handle messages from the kernel targeted to a memory manager.
+<p>
+A \*Vmemory manager\*O
+is a server task that responds to specific messages from the
+kernel in order to handle memory management functions for the kernel. The
+<strong>memory_object_server</strong> function performs all necessary
+argument handling for
+a kernel message and calls one of the memory manager functions to interpret
+the message.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>TRUE</strong>
+<dd>
+The message was handled and the appropriate function was called.
+<p>
+<dt> <strong>FALSE</strong>
+<dd>
+The message did not apply to this memory management interface and
+no other action was taken.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="MO_default_server.html"><strong>memory_object_default_server<strong></a>,
+<a href="memory_object_data_request.html"><strong>memory_object_data_request<strong></a>,
+<a href="memory_object_data_return.html"><strong>memory_object_data_return<strong></a>,
+<a href="memory_object_data_unlock.html"><strong>memory_object_data_unlock<strong></a>,
+<a href="MO_lock_completed.html"><strong>memory_object_lock_completed<strong></a>,
+<a href="MO_change_completed.html"><strong>memory_object_change_completed<strong></a>,
+<a href="MO_supply_completed.html"><strong>memory_object_supply_completed<strong></a>,
+<a href="memory_object_terminate.html"><strong>memory_object_terminate<strong></a>,
+<a href="memory_object_synchronize.html"><strong>memory_object_synchronize<strong></a>,
+<a href="SMO_server.html"><strong>seqnos_memory_object_server<strong></a>.
-<h2>memory_object_synchronize</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Forward a client's request to synchronize data with its image in backing store.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_synchronize</strong>
\r <strong>(memory_object_t</strong> <var>memory_object</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>vm_offset_t</strong> <var>length</var>,
\r <strong>memory_object</strong> <var>sync_flags</var><strong>);</strong>
\r\r\r<strong>kern_return_t seqnos_memory_object_synchronize</strong>
\r <strong>(memory_object_t</strong> <var>memory_object</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>vm_offset_t</strong> <var>length</var>,
\r <strong>memory_object</strong> <var>sync_flags</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>memory_object</var>
\r<dd>
\r[in abstract-memory-object (receive) right]
\rThe abstract memory
\robject port that represents the memory object data.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the abstract
\rmemory object port.
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used for a response by the memory manager. If the memory
\robject has been supplied to more than one kernel, this parameter
\ridentifies the kernel that is making the call.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar]
\rThe offset within the memory object.
\r<p>
\r<dt> <var>length</var>
\r<dd>
\r[in scalar]
\rThe number of bytes cleaned or flushed, starting at <var>offset</var>.
\rThe number converts to an integral number of virtual pages.
\r<p>
\r<dt> <var>sync_flags</var>
\r<dd>
\r[in scalar]
\rThe bit-wise OR of flags affecting the synchronization.
\r<dl>
\r<p>
\r<dt> <strong>VM_SYNC_INVALIDATE</strong>
\r<dd>
\rFlushes pages in the range. Only precious pages are returned
\rto the memory manager.
\r<p>
\r<dt> <strong>VM_SYNC_SYNCHRONOUS</strong>
\r<dd>
\rWrites dirty and precious pages back to the memory manager,
\rwaits for pages to reach backing storage.
\r<p>
\r<dt> <strong>VM_SYNC_ASYNCHRONOUS</strong>
\r<dd>
\rWrites dirty and precious pages back to the memory manager,
\rreturns without waiting for pages to reach backing storage.
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>memory_object_synchronize</strong> function is called as the
\rresult of a kernel
\rmessage indicating that a client wishes to synchronize the contents
\rof a range of a
\rmemory object with its backing storage image. This message would have been
\rpreceded by <strong>memory_object_data_return</strong> messages cleaning
\ror flushing the
\rspecified range.
\r<p>
\rDepending on the client's supplied <var>sync_flags</var>, the manager waits
\rfor the pages
\rto reach the desired state and then replies with
\r<strong>memory_object_synchronize_completed</strong> at which time the
\rclient returns from its <strong>vm_msync</strong> call. Multiple
\rsynchronize requests may be outstanding at a time but they will not overlap.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_msync.html"><strong>vm_msync</strong></a>,
\r<a href="MO_SY_completed.html"><strong>memory_object_synchronize_completed</strong></a>,
\r<a href="memory_object_data_return.html"><strong>memory_object_data_return</strong></a>,
\r<a href="memory_object_server.html"><strong>memory_object_server</strong></a>,
\r<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_synchronize</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Forward a client's request to synchronize data with its image in backing store.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_synchronize</strong>
+ <strong>(memory_object_t</strong> <var>memory_object</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>vm_offset_t</strong> <var>length</var>,
+ <strong>memory_object</strong> <var>sync_flags</var><strong>);</strong>
+
+
+<strong>kern_return_t seqnos_memory_object_synchronize</strong>
+ <strong>(memory_object_t</strong> <var>memory_object</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>vm_offset_t</strong> <var>length</var>,
+ <strong>memory_object</strong> <var>sync_flags</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>memory_object</var>
+<dd>
+[in abstract-memory-object (receive) right]
+The abstract memory
+object port that represents the memory object data.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the abstract
+memory object port.
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used for a response by the memory manager. If the memory
+object has been supplied to more than one kernel, this parameter
+identifies the kernel that is making the call.
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar]
+The offset within the memory object.
+<p>
+<dt> <var>length</var>
+<dd>
+[in scalar]
+The number of bytes cleaned or flushed, starting at <var>offset</var>.
+The number converts to an integral number of virtual pages.
+<p>
+<dt> <var>sync_flags</var>
+<dd>
+[in scalar]
+The bit-wise OR of flags affecting the synchronization.
+<dl>
+<p>
+<dt> <strong>VM_SYNC_INVALIDATE</strong>
+<dd>
+Flushes pages in the range. Only precious pages are returned
+to the memory manager.
+<p>
+<dt> <strong>VM_SYNC_SYNCHRONOUS</strong>
+<dd>
+Writes dirty and precious pages back to the memory manager,
+waits for pages to reach backing storage.
+<p>
+<dt> <strong>VM_SYNC_ASYNCHRONOUS</strong>
+<dd>
+Writes dirty and precious pages back to the memory manager,
+returns without waiting for pages to reach backing storage.
+</dl>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>memory_object_synchronize</strong> function is called as the
+result of a kernel
+message indicating that a client wishes to synchronize the contents
+of a range of a
+memory object with its backing storage image. This message would have been
+preceded by <strong>memory_object_data_return</strong> messages cleaning
+or flushing the
+specified range.
+<p>
+Depending on the client's supplied <var>sync_flags</var>, the manager waits
+for the pages
+to reach the desired state and then replies with
+<strong>memory_object_synchronize_completed</strong> at which time the
+client returns from its <strong>vm_msync</strong> call. Multiple
+synchronize requests may be outstanding at a time but they will not overlap.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="vm_msync.html"><strong>vm_msync</strong></a>,
+<a href="MO_SY_completed.html"><strong>memory_object_synchronize_completed</strong></a>,
+<a href="memory_object_data_return.html"><strong>memory_object_data_return</strong></a>,
+<a href="memory_object_server.html"><strong>memory_object_server</strong></a>,
+<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>.
-<h2>memory_object_terminate</h2>
\r<hr>
\r<p>
\r<strong>Server Interface</strong> - Relinquish access to a memory object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_terminate</strong>
\r <strong>(memory_object_t</strong> <var>memory_object</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var><strong>);</strong>
\r\r\r\r<strong>kern_return_t seqnos_memory_object_terminate</strong>
\r <strong>(memory_object_t</strong> <var>memory_object</var>,
\r <strong>mach_port_seqno_t</strong> <var>seqno</var>,
\r <strong>memory_object_control_t</strong> <var>memory_control</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>memory_object</var>
\r<dd>
\r[in abstract-memory-object (receive) right]
\rThe abstract memory
\robject port that represents the memory object data.
\r<p>
\r<dt> <var>seqno</var>
\r<dd>
\r[in scalar]
\rThe sequence number of this message relative to the abstract
\rmemory object port.
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control receive right]
\rThe memory cache control
\rport to be used for a response by the memory manager. If the memory
\robject has been supplied to more than one kernel, this parameter
\ridentifies the kernel that is making the call.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>memory_object_terminate</strong> function is called as the
\rresult of a kernel
\rmessage notifying a memory manager that no mappings of the specified memory
\robject remain. The kernel makes this call to allow the memory
\rmanager to clean
\rup data structures associated with the deallocated mappings.
\rThe call provides
\rreceive rights to the memory cache control port so that the memory manager
\rcan retrieve any messages it sent into this port before knowing the memory
\robject was being terminated and then destroy the port. The kernel also
\rrelinquishes its rights for all memory object ports.
\r<p>
\rThe kernel terminates a memory object only after all address space mappings of
\rthe object have been deallocated, or upon explicit request by the memory
\rmanager.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_destroy.html"><strong>memory_object_destroy</strong></a>,
\r<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>,
\r<a href="memory_object_server.html"><strong>memory_object_server</strong></a>,
\r<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>.
\r\ No newline at end of file
+<h2>memory_object_terminate</h2>
+<hr>
+<p>
+<strong>Server Interface</strong> - Relinquish access to a memory object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_terminate</strong>
+ <strong>(memory_object_t</strong> <var>memory_object</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var><strong>);</strong>
+
+
+
+<strong>kern_return_t seqnos_memory_object_terminate</strong>
+ <strong>(memory_object_t</strong> <var>memory_object</var>,
+ <strong>mach_port_seqno_t</strong> <var>seqno</var>,
+ <strong>memory_object_control_t</strong> <var>memory_control</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>memory_object</var>
+<dd>
+[in abstract-memory-object (receive) right]
+The abstract memory
+object port that represents the memory object data.
+<p>
+<dt> <var>seqno</var>
+<dd>
+[in scalar]
+The sequence number of this message relative to the abstract
+memory object port.
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control receive right]
+The memory cache control
+port to be used for a response by the memory manager. If the memory
+object has been supplied to more than one kernel, this parameter
+identifies the kernel that is making the call.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>memory_object_terminate</strong> function is called as the
+result of a kernel
+message notifying a memory manager that no mappings of the specified memory
+object remain. The kernel makes this call to allow the memory
+manager to clean
+up data structures associated with the deallocated mappings.
+The call provides
+receive rights to the memory cache control port so that the memory manager
+can retrieve any messages it sent into this port before knowing the memory
+object was being terminated and then destroy the port. The kernel also
+relinquishes its rights for all memory object ports.
+<p>
+The kernel terminates a memory object only after all address space mappings of
+the object have been deallocated, or upon explicit request by the memory
+manager.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_destroy.html"><strong>memory_object_destroy</strong></a>,
+<a href="mach_port_deallocate.html"><strong>mach_port_deallocate</strong></a>,
+<a href="memory_object_server.html"><strong>memory_object_server</strong></a>,
+<a href="SMO_server.html"><strong>seqnos_memory_object_server</strong></a>.
-<h2>norma_get_special_port</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Acquire a send right for a specified node-specific special port.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t norma_get_special_port</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>int</strong> <var>node</var>,
\r <strong>int</strong> <var>which_port</var>,
\r <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
\r\r</pre>
\r<h4>Macro forms:</h4>
\r<pre>
\r\r<strong>#include<mach/norma_special_ports.h></strong>
\r\r<strong>kern_return_t norma_get_device_port</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>int</strong> <var>node</var>,
\r <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
\r\r<strong>kern_return_t norma_get_host_port</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>int</strong> <var>node</var>,
\r <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
\r\r<strong>kern_return_t norma_get_host_priv_port</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>int</strong> <var>node</var>,
\r <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
\r\r<strong>kern_return_t norma_get_nameserver_port</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>int</strong> <var>node</var>,
\r <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>host_priv</var>
\r<dd>
\r[in host-control send right]
\rThe control port for the host for which to
\rreturn the special port's send right.
\r<p>
\r<dt> <var>node</var>
\r<dd>
\r[in scalar]
\rThe index of the node for which the port is desired.
\r<p>
\r<dt> <var>which_port</var>
\r<dd>
\r[in scalar]
\rThe index of the special port for which the send right is
\rrequested. Valid values are:
\r <dl>
\r <p>
\r<dt> <strong>NORMA_DEVICE_PORT</strong>
\r<dd>
\r[device-master send right] The device master port for the
\rnode.
\r<p>
\r<dt> <strong>NORMA_HOST_PORT</strong>
\r<dd>
\r[host-name send right] The host name port for the node.
\r<p>
\r<dt> <strong>NORMA_HOST_PRIV_PORT</strong>
\r<dd>
\r[host-control send right] The host control port for the node.
\r<p>
\r<dt> <strong>NORMA_NAMESERVER_PORT</strong>
\r<dd>
\r[name-server send right] The registered name server port for
\rthe node.
\r</dl>
\r<p>
\r<dt> <var>special_port</var>
\r<dd>
\r[out norma-special send right]
\rThe returned value for the port.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>norma_get_special_port</strong> function returns a send
\rright for a special port belonging to <var>node</var> on <var>host_priv</var>.
\r<p>
\rEach node maintains a (small) set of node specific ports. The device master
\rport, host name, and host control ports are
\rmaintained by the kernel. The kernel also permits a small set
\rof server specified
\rnode specific ports; the name server port is an example and is given (by
\rconvention) an assigned special port index.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_host_self.html"><strong>mach_host_self</strong></a>,
\r<a href="norma_set_special_port.html"><strong>norma_get_special_port</strong></a>,
\r<a href="bootstrap_ports.html"><strong>bootstrap_ports</strong></a>.
\r\ No newline at end of file
+<h2>norma_get_special_port</h2>
+<hr>
+<p>
+<strong>Function</strong> - Acquire a send right for a specified node-specific special port.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t norma_get_special_port</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>int</strong> <var>node</var>,
+ <strong>int</strong> <var>which_port</var>,
+ <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
+
+</pre>
+<h4>Macro forms:</h4>
+<pre>
+
+<strong>#include<mach/norma_special_ports.h></strong>
+
+<strong>kern_return_t norma_get_device_port</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>int</strong> <var>node</var>,
+ <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
+
+<strong>kern_return_t norma_get_host_port</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>int</strong> <var>node</var>,
+ <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
+
+<strong>kern_return_t norma_get_host_priv_port</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>int</strong> <var>node</var>,
+ <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
+
+<strong>kern_return_t norma_get_nameserver_port</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>int</strong> <var>node</var>,
+ <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>host_priv</var>
+<dd>
+[in host-control send right]
+The control port for the host for which to
+return the special port's send right.
+<p>
+<dt> <var>node</var>
+<dd>
+[in scalar]
+The index of the node for which the port is desired.
+<p>
+<dt> <var>which_port</var>
+<dd>
+[in scalar]
+The index of the special port for which the send right is
+requested. Valid values are:
+ <dl>
+ <p>
+<dt> <strong>NORMA_DEVICE_PORT</strong>
+<dd>
+[device-master send right] The device master port for the
+node.
+<p>
+<dt> <strong>NORMA_HOST_PORT</strong>
+<dd>
+[host-name send right] The host name port for the node.
+<p>
+<dt> <strong>NORMA_HOST_PRIV_PORT</strong>
+<dd>
+[host-control send right] The host control port for the node.
+<p>
+<dt> <strong>NORMA_NAMESERVER_PORT</strong>
+<dd>
+[name-server send right] The registered name server port for
+the node.
+</dl>
+<p>
+<dt> <var>special_port</var>
+<dd>
+[out norma-special send right]
+The returned value for the port.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>norma_get_special_port</strong> function returns a send
+right for a special port belonging to <var>node</var> on <var>host_priv</var>.
+<p>
+Each node maintains a (small) set of node specific ports. The device master
+port, host name, and host control ports are
+maintained by the kernel. The kernel also permits a small set
+of server specified
+node specific ports; the name server port is an example and is given (by
+convention) an assigned special port index.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_host_self.html"><strong>mach_host_self</strong></a>,
+<a href="norma_set_special_port.html"><strong>norma_get_special_port</strong></a>,
+<a href="bootstrap_ports.html"><strong>bootstrap_ports</strong></a>.
-<h2>norma_node_self</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return the node index of the current host.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t norma_node_self</strong>
\r <strong>(host_t</strong> <var>host</var>,
\r <strong>int</strong> <var>int</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host</var>
\r<dd>
\r[in host send-right] Name of the host.
\r<p>
\r<dt> <var>node</var>
\r<dd>
\r[out scalar] Node index of the host.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe norma_node_self function returns the node index of the current host.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="norma_task_create.html"><strong>norma_task_create</strong></a>,
\r<a href="norma_task_clone.html"><strong>norma_task_clone</strong></a>,
\r\ No newline at end of file
+<h2>norma_node_self</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return the node index of the current host.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t norma_node_self</strong>
+ <strong>(host_t</strong> <var>host</var>,
+ <strong>int</strong> <var>int</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host</var>
+<dd>
+[in host send-right] Name of the host.
+<p>
+<dt> <var>node</var>
+<dd>
+[out scalar] Node index of the host.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The norma_node_self function returns the node index of the current host.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="norma_task_create.html"><strong>norma_task_create</strong></a>,
+<a href="norma_task_clone.html"><strong>norma_task_clone</strong></a>,
-<h2>norma_port_location_hint</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Guess a port's current location.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t norma_port_location_hint</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>mach_port_t</strong> <var>name</var>,
\r <strong>int</strong> <var>node</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rTask containing the right to locate
\r<p>
\r<dt> <var>name</var>
\r<dd>
\r[in scalar]
\rName of the right to locate
\r<p>
\r<dt> <var>node</var>
\r<dd>
\r[out scalar]
\rPort location hint
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>norma_port_location_hint</strong> function returns the best
\rguess of <var>name</var>'s
\rcurrent location. The hint is guaranteed to be a node where
\rthe port once was; it is
\rguaranteed to be accurate if port has never moved. This can be used to
\rdetermine residence node for hosts, tasks, threads, etc.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="norma_task_create.html"><strong>norma_task_create</strong></a>.
\r\ No newline at end of file
+<h2>norma_port_location_hint</h2>
+<hr>
+<p>
+<strong>Function</strong> - Guess a port's current location.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t norma_port_location_hint</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>mach_port_t</strong> <var>name</var>,
+ <strong>int</strong> <var>node</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+Task containing the right to locate
+<p>
+<dt> <var>name</var>
+<dd>
+[in scalar]
+Name of the right to locate
+<p>
+<dt> <var>node</var>
+<dd>
+[out scalar]
+Port location hint
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>norma_port_location_hint</strong> function returns the best
+guess of <var>name</var>'s
+current location. The hint is guaranteed to be a node where
+the port once was; it is
+guaranteed to be accurate if port has never moved. This can be used to
+determine residence node for hosts, tasks, threads, etc.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="norma_task_create.html"><strong>norma_task_create</strong></a>.
-<h2>norma_set_special_port</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set node-specific special port.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t norma_set_special_port</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>int</strong> <var>which_port</var>,
\r <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
\r\r</pre>
\r<h4>Macro forms:</h4>
\r<pre>
\r\r<strong>#include<mach/norma_special_ports.h></strong>
\r\r<strong>kern_return_t norma_set_device_port</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
\r\r<strong>kern_return_t norma_set_host_port</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
\r\r<strong>kern_return_t norma_set_host_priv_port</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>int</strong> <var>node</var>,
\r <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
\r\r<strong>kern_return_t norma_set_nameserver_port</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
\r</pre>
\r\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>host_priv</var>
\r<dd>
\r[in host-control send right]
\rThe host for which to set the special port.
\rCurrently, this must be the per-node host control port.
\r<p>
\r<dt> <var>node</var>
\r<dd>
\r[in scalar]
\rThe index of the node for which the port is to be set.
\r<p>
\r<dt> <var>which_port</var>
\r<dd>
\r[in scalar]
\rThe index of the special port to be set. Valid values are:
\r<dl>
\r<p>
\r<dt> <strong>NORMA_DEVICE_PORT</strong>
\r<dd>
\r[device-master send right] The device master port for the
\rnode.
\r<p>
\r<dt> <strong>NORMA_HOST_PORT</strong>
\r<dd>
\r[host-name send right] The host name port for the node.
\r<p>
\r<dt> <strong>NORMA_HOST_PRIV_PORT</strong>
\r<dd>
\r[host-control send right] The host control port for the node.
\r<p>
\r<dt> <strong>NORMA_NAMESERVER_PORT</strong>
\r<dd>
\r[name-server send right] The registered name server port for
\rthe node.
\r</dl>
\r<p>
\r<dt> <var>special_port</var>
\r<dd>
\r[in norma-special send right]
\rSend right to the new special port.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>norma_set_special_port</strong> function sets the special
\rport belonging to <var>node</var> on <var>host_priv</var>.
\r<p>
\rEach node maintains a (small) set of node specific ports. The device master
\rport, host name, and host control ports are maintained by the kernel.
\rThe kernel also permits
\ra small set of server specified
\rnode specific ports; the name server port is an example and is given (by
\rconvention) an assigned special port index.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_host_self.html"><strong>mach_host_self</strong></a>,
\r<a href="norma_get_special_port.html"><strong>norma_get_special_port</strong></a>.
\r\ No newline at end of file
+<h2>norma_set_special_port</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set node-specific special port.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t norma_set_special_port</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>int</strong> <var>which_port</var>,
+ <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
+
+</pre>
+<h4>Macro forms:</h4>
+<pre>
+
+<strong>#include<mach/norma_special_ports.h></strong>
+
+<strong>kern_return_t norma_set_device_port</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
+
+<strong>kern_return_t norma_set_host_port</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
+
+<strong>kern_return_t norma_set_host_priv_port</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>int</strong> <var>node</var>,
+ <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
+
+<strong>kern_return_t norma_set_nameserver_port</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
+</pre>
+
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>host_priv</var>
+<dd>
+[in host-control send right]
+The host for which to set the special port.
+Currently, this must be the per-node host control port.
+<p>
+<dt> <var>node</var>
+<dd>
+[in scalar]
+The index of the node for which the port is to be set.
+<p>
+<dt> <var>which_port</var>
+<dd>
+[in scalar]
+The index of the special port to be set. Valid values are:
+<dl>
+<p>
+<dt> <strong>NORMA_DEVICE_PORT</strong>
+<dd>
+[device-master send right] The device master port for the
+node.
+<p>
+<dt> <strong>NORMA_HOST_PORT</strong>
+<dd>
+[host-name send right] The host name port for the node.
+<p>
+<dt> <strong>NORMA_HOST_PRIV_PORT</strong>
+<dd>
+[host-control send right] The host control port for the node.
+<p>
+<dt> <strong>NORMA_NAMESERVER_PORT</strong>
+<dd>
+[name-server send right] The registered name server port for
+the node.
+</dl>
+<p>
+<dt> <var>special_port</var>
+<dd>
+[in norma-special send right]
+Send right to the new special port.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>norma_set_special_port</strong> function sets the special
+port belonging to <var>node</var> on <var>host_priv</var>.
+<p>
+Each node maintains a (small) set of node specific ports. The device master
+port, host name, and host control ports are maintained by the kernel.
+The kernel also permits
+a small set of server specified
+node specific ports; the name server port is an example and is given (by
+convention) an assigned special port index.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_host_self.html"><strong>mach_host_self</strong></a>,
+<a href="norma_get_special_port.html"><strong>norma_get_special_port</strong></a>.
-<h2>norma_task_clone</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Create a remote task that shares access to parent task's memory regardless of inheritance attributes.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t norma_task_clone</strong>
\r <strong>(task_t</strong> <var>parent_task</var>,
\r <strong>boolean_t</strong> <var>inherit_memory</var>,
\r <strong>int</strong> <var>child_node</var>,
\r <strong>task_t</strong> <var>child_task</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>parent_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task from which to draw the child
\rtask's port rights, resource limits, and address space.
\r<p>
\r<dt> <var>inherit_memory</var>
\r<dd>
\r[in scalar]
\rAddress space inheritance indicator. If true, the child task
\rinherits the address space of the parent task. If false, the kernel assigns
\rthe child task an empty address space.
\r<p>
\r<dt> <var>child_node</var>
\r<dd>
\r[in scalar]
\rThe node index of the node on which to create the child.
\r<p>
\r<dt> <var>child_task</var>
\r<dd>
\r[out task send right]
\rThe kernel-assigned port name for the new task.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>norma_task_clone</strong> function "clones" a new task from
\r<var>parent_task</var> on the specified <var>node</var> and returns the name
\rof the new task in <var>child_task</var>. The child
\rtask acquires shared parts of the parent's
\raddress space (see <strong>vm_inherit</strong>)
\rregardless of the inheritance set for the parent's memory regions, although the
\rinheritance for the child's regions will be set to that of the
\rparent's regions. The child
\rtask initially contains no threads.
\r<p>
\rBy way of comparison, tasks created by the standard <strong>task_create</strong>
\rprimitive are created on the same node as the parent.
\r<p>
\rOther than being created on a different node, the new task has the same
\rproperties as if created by <strong>task_create</strong>.
\r<h3>NOTES</h3>
\r<p>
\rThis call differs from <strong>norma_task_create</strong> in that the
\rinheritance set for the
\rparent's memory regions is ignored; the child always shares memory with the
\rparent.
\r<p>
\rThis call is intended to support process migration, where the inheritance
\rsemantics of <strong>norma_task_create</strong> would break migrated
\rprograms that depended upon
\rsharing relationships remaining after migration.
\r<p>
\rThis call is not a true task migration call, in that it does
\rnot migrate the port
\rspace, threads, and other non-address-space attributes of the task.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_create.html"><strong>task_create</strong></a>,
\r<a href="norma_task_create.html"><strong>norma_task_create</strong></a>.
\r\ No newline at end of file
+<h2>norma_task_clone</h2>
+<hr>
+<p>
+<strong>Function</strong> - Create a remote task that shares access to parent task's memory regardless of inheritance attributes.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t norma_task_clone</strong>
+ <strong>(task_t</strong> <var>parent_task</var>,
+ <strong>boolean_t</strong> <var>inherit_memory</var>,
+ <strong>int</strong> <var>child_node</var>,
+ <strong>task_t</strong> <var>child_task</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>parent_task</var>
+<dd>
+[in task send right]
+The port for the task from which to draw the child
+task's port rights, resource limits, and address space.
+<p>
+<dt> <var>inherit_memory</var>
+<dd>
+[in scalar]
+Address space inheritance indicator. If true, the child task
+inherits the address space of the parent task. If false, the kernel assigns
+the child task an empty address space.
+<p>
+<dt> <var>child_node</var>
+<dd>
+[in scalar]
+The node index of the node on which to create the child.
+<p>
+<dt> <var>child_task</var>
+<dd>
+[out task send right]
+The kernel-assigned port name for the new task.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>norma_task_clone</strong> function "clones" a new task from
+<var>parent_task</var> on the specified <var>node</var> and returns the name
+of the new task in <var>child_task</var>. The child
+task acquires shared parts of the parent's
+address space (see <strong>vm_inherit</strong>)
+regardless of the inheritance set for the parent's memory regions, although the
+inheritance for the child's regions will be set to that of the
+parent's regions. The child
+task initially contains no threads.
+<p>
+By way of comparison, tasks created by the standard <strong>task_create</strong>
+primitive are created on the same node as the parent.
+<p>
+Other than being created on a different node, the new task has the same
+properties as if created by <strong>task_create</strong>.
+<h3>NOTES</h3>
+<p>
+This call differs from <strong>norma_task_create</strong> in that the
+inheritance set for the
+parent's memory regions is ignored; the child always shares memory with the
+parent.
+<p>
+This call is intended to support process migration, where the inheritance
+semantics of <strong>norma_task_create</strong> would break migrated
+programs that depended upon
+sharing relationships remaining after migration.
+<p>
+This call is not a true task migration call, in that it does
+not migrate the port
+space, threads, and other non-address-space attributes of the task.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_create.html"><strong>task_create</strong></a>,
+<a href="norma_task_create.html"><strong>norma_task_create</strong></a>.
-<h2>norma_task_create</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Create a remote task using task_create semantics.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t norma_task_create</strong>
\r <strong>(task_t</strong> <var>parent_task</var>,
\r <strong>boolean_t</strong> <var>inherit_memory</var>,
\r <strong>int</strong> <var>child_node</var>,
\r <strong>task_t</strong> <var>child_task</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>parent_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task from which to draw the child
\rtask's port rights, resource limits, and address space.
\r<p>
\r<dt> <var>inherit_memory</var>
\r<dd>
\r[in scalar]
\rAddress space inheritance indicator. If true, the child task
\rinherits the address space of the parent task. If false, the kernel assigns
\rthe child task an empty address space.
\r<p>
\r<dt> <var>child_node</var>
\r<dd>
\r[in scalar]
\rThe node index of the node on which to create the child.
\r<p>
\r<dt> <var>child_task</var>
\r<dd>
\r[out task send right]
\rThe kernel-assigned port name for the new task.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>norma_task_create</strong> function creates a new task from
\r<var>parent_task</var> on the specified <var>node</var> and returns the name of the
\rnew task in <var>child_task</var>. The child
\rtask acquires shared or copied parts of the parent's address space (see
\r<strong>vm_inherit</strong>). The child task initially contains no threads.
\r<p>
\rBy way of comparison, tasks created by the standard <strong>task_create</strong>
\rprimitive are created on the same node as the parent.
\r<p>
\rOther than being created on a different node, the new task has the same
\rproperties as if created by <strong>task_create</strong>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_create.html"><strong>task_create</strong></a>,
\r<a href="norma_task_clone.html"><strong>norma_task_clone</strong></a>.
\r\ No newline at end of file
+<h2>norma_task_create</h2>
+<hr>
+<p>
+<strong>Function</strong> - Create a remote task using task_create semantics.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t norma_task_create</strong>
+ <strong>(task_t</strong> <var>parent_task</var>,
+ <strong>boolean_t</strong> <var>inherit_memory</var>,
+ <strong>int</strong> <var>child_node</var>,
+ <strong>task_t</strong> <var>child_task</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>parent_task</var>
+<dd>
+[in task send right]
+The port for the task from which to draw the child
+task's port rights, resource limits, and address space.
+<p>
+<dt> <var>inherit_memory</var>
+<dd>
+[in scalar]
+Address space inheritance indicator. If true, the child task
+inherits the address space of the parent task. If false, the kernel assigns
+the child task an empty address space.
+<p>
+<dt> <var>child_node</var>
+<dd>
+[in scalar]
+The node index of the node on which to create the child.
+<p>
+<dt> <var>child_task</var>
+<dd>
+[out task send right]
+The kernel-assigned port name for the new task.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>norma_task_create</strong> function creates a new task from
+<var>parent_task</var> on the specified <var>node</var> and returns the name of the
+new task in <var>child_task</var>. The child
+task acquires shared or copied parts of the parent's address space (see
+<strong>vm_inherit</strong>). The child task initially contains no threads.
+<p>
+By way of comparison, tasks created by the standard <strong>task_create</strong>
+primitive are created on the same node as the parent.
+<p>
+Other than being created on a different node, the new task has the same
+properties as if created by <strong>task_create</strong>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_create.html"><strong>task_create</strong></a>,
+<a href="norma_task_clone.html"><strong>norma_task_clone</strong></a>.
-<h2>norma_task_teleport</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - "Clone" a task on a specified node.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t norma_task_teleport</strong>
\r <strong>(task_t</strong> <var>parent_task</var>,
\r <strong>boolean_t</strong> <var>inherit_memory</var>,
\r <strong>int</strong> <var>child_node</var>,
\r <strong>task_t</strong> <var>child_task</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>parent_task</var>
\r<dd>
\r[in task send right] The port for the task from which to draw the child
\rtask's port rights, resource limits, and address space.
\r<p>
\r<dt> <var>inherit_memory</var>
\r<dd>
\r[in scalar] Address space inheritance indicator. If true, the child task in-
\rherits the address space of the parent task. If false, the kernel assigns
\rthe child task an empty address space.
\r<p>
\r<dt> <var>child_node</var>
\r<dd>
\r[in scalar] The node index of the node on which to create the child.
\r<p>
\r<dt> <var>child_task</var>
\r<dd>
\r[out task send right] The kernel-assigned port name for the new task.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe norma_task_clone function "clones" a new task from parent_task on
\rthe specified node and returns the name of the new task in
\rchild_task. The child task acquires shared parts of the parent's
\raddress space (see vm_inherit) regardless of the inheritance set for
\rthe parent's memory regions, although the inheritance for the
\rchild's regions will be set to that of the parent's regions. The child
\rtask initially contains no threads. The parent_task is then
\rterminated.
\rBy way of comparison, tasks created by the standard task_create
\rprimitive are created on the same node as the parent.
\rOther than being created on a different node, the new task has the
\rsame properties as if created by task_create.
\r<h3>NOTES</h3>
\r<p>
\rThis call differs from norma_task_clone in that the parent task is
\rterminated as part of the teleport call.
\rThis call differs from norma_task_create in that the inheritance set
\rfor the parent's memory regions is ignored; the child always shares
\rmemory with the parent.
\rThis call is intended to support process migration, where the
\rinheritance semantics of norma_task_create would break migrated
\rprograms that depended upon sharing relationships remaining after
\rmigration.
\rThis call is not a true task migration call, in that it does not
\rmigrate the port space, threads, and other non-address-space
\rattributes of the task.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="norma_task_clone.html"><strong>norma_task_clone</strong></a>,
\r<a href="task_create.html"><strong>task_create</strong></a>,
\r<a href="norma_task_create.html"><strong>norma_task_create</strong></a>,
\r\ No newline at end of file
+<h2>norma_task_teleport</h2>
+<hr>
+<p>
+<strong>Function</strong> - "Clone" a task on a specified node.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t norma_task_teleport</strong>
+ <strong>(task_t</strong> <var>parent_task</var>,
+ <strong>boolean_t</strong> <var>inherit_memory</var>,
+ <strong>int</strong> <var>child_node</var>,
+ <strong>task_t</strong> <var>child_task</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>parent_task</var>
+<dd>
+[in task send right] The port for the task from which to draw the child
+task's port rights, resource limits, and address space.
+<p>
+<dt> <var>inherit_memory</var>
+<dd>
+[in scalar] Address space inheritance indicator. If true, the child task in-
+herits the address space of the parent task. If false, the kernel assigns
+the child task an empty address space.
+<p>
+<dt> <var>child_node</var>
+<dd>
+[in scalar] The node index of the node on which to create the child.
+<p>
+<dt> <var>child_task</var>
+<dd>
+[out task send right] The kernel-assigned port name for the new task.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The norma_task_clone function "clones" a new task from parent_task on
+the specified node and returns the name of the new task in
+child_task. The child task acquires shared parts of the parent's
+address space (see vm_inherit) regardless of the inheritance set for
+the parent's memory regions, although the inheritance for the
+child's regions will be set to that of the parent's regions. The child
+task initially contains no threads. The parent_task is then
+terminated.
+By way of comparison, tasks created by the standard task_create
+primitive are created on the same node as the parent.
+Other than being created on a different node, the new task has the
+same properties as if created by task_create.
+<h3>NOTES</h3>
+<p>
+This call differs from norma_task_clone in that the parent task is
+terminated as part of the teleport call.
+This call differs from norma_task_create in that the inheritance set
+for the parent's memory regions is ignored; the child always shares
+memory with the parent.
+This call is intended to support process migration, where the
+inheritance semantics of norma_task_create would break migrated
+programs that depended upon sharing relationships remaining after
+migration.
+This call is not a true task migration call, in that it does not
+migrate the port space, threads, and other non-address-space
+attributes of the task.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="norma_task_clone.html"><strong>norma_task_clone</strong></a>,
+<a href="task_create.html"><strong>task_create</strong></a>,
+<a href="norma_task_create.html"><strong>norma_task_create</strong></a>,
-<h2>notify_server</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Handle the next kernel-generated IPC notification.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>boolean_t notify_server</strong>
\r <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
\r <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>in_msg</var>
\r<dd>
\r[pointer to in structure]
\rThe notification message received from the
\rkernel.
\r<p>
\r<dt> <var>out_msg</var>
\r<dd>
\r[out structure]
\rNot used.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>notify_server</strong> function is the MIG generated server
\rhandling function to
\rhandle messages from the kernel corresponding to IPC notifications. Such
\rmessages are delivered to the notification port named in a <strong>mach_msg</strong>
\ror <strong>mach_port_request_notification</strong> call. The <strong>notify_server</strong>
\rfunction performs all necessary
\rargument handling for this kernel message and calls the appropriate handling
\rfunction. These functions must be supplied by the caller.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>TRUE</strong>
\r<dd>
\rThe message was handled and the appropriate function was called.
\r<p>
\r<dt> <strong>FALSE</strong>
\r<dd>
\rThe message did not apply to the notification mechanism and no other
\raction was taken.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="seqnos_notify_server.html"><strong>seqnos_notify_server<strong></a>,
\r<a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name<strong></a>,
\r<a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders<strong></a>,
\r<a href="DMN_port_deleted.html"><strong>do_mach_notify_port_deleted<strong></a>,
\r<a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once<strong></a>.
\r\ No newline at end of file
+<h2>notify_server</h2>
+<hr>
+<p>
+<strong>Function</strong> - Handle the next kernel-generated IPC notification.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>boolean_t notify_server</strong>
+ <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
+ <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>in_msg</var>
+<dd>
+[pointer to in structure]
+The notification message received from the
+kernel.
+<p>
+<dt> <var>out_msg</var>
+<dd>
+[out structure]
+Not used.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>notify_server</strong> function is the MIG generated server
+handling function to
+handle messages from the kernel corresponding to IPC notifications. Such
+messages are delivered to the notification port named in a <strong>mach_msg</strong>
+or <strong>mach_port_request_notification</strong> call. The <strong>notify_server</strong>
+function performs all necessary
+argument handling for this kernel message and calls the appropriate handling
+function. These functions must be supplied by the caller.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>TRUE</strong>
+<dd>
+The message was handled and the appropriate function was called.
+<p>
+<dt> <strong>FALSE</strong>
+<dd>
+The message did not apply to the notification mechanism and no other
+action was taken.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="seqnos_notify_server.html"><strong>seqnos_notify_server<strong></a>,
+<a href="do_mach_notify_dead_name.html"><strong>do_mach_notify_dead_name<strong></a>,
+<a href="do_mach_notify_no_senders.html"><strong>do_mach_notify_no_senders<strong></a>,
+<a href="DMN_port_deleted.html"><strong>do_mach_notify_port_deleted<strong></a>,
+<a href="do_mach_notify_send_once.html"><strong>do_mach_notify_send_once<strong></a>.
-<h2>policy_fifo_info</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Specifies information associated with the system's First-In-First-Out scheduling policy.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct policy_fifo_limit</strong>
\r<strong>{</strong>
\r <strong>int</strong> <var>max_priority</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>struct policy_fifo_base</strong>
\r<strong>{</strong>
\r <strong>int</strong> <var>base_priority</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>struct policy_fifo_info</strong>
\r<strong>{</strong>
\r <strong>int</strong> <var>max_priority</var><strong>;</strong>
\r <strong>int</strong> <var>base_priority</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>depressed</var><strong>;</strong>
\r <strong>int</strong> <var>depress_priority</var><strong>;</strong>
\r<strong>};</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>max_priority</var>
\r<dd>
\rMaximum scheduling priority
\r<p>
\r<dt> <var>base_priority</var>
\r<dd>
\rScheduling priority
\r<p>
\r<dt> <var>depressed</var>
\r<dd>
\rTrue if scheduling priority is depressed
\r<p>
\r<dt> <var>depress_priority</var>
\r<dd>
\rScheduling priority from which depressed
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>policy_fifo_info</strong> structure defines the first-in-first-out
\rscheduling policy information.
\rFIFO threads have two priorities associated with them by the system:
\r<ul>
\r <p>
\r<li>
\rA maximum priority value which can be raised only via privileged operation
\rso that users may not unfairly compete with other users in their processor
\rset. Newly created threads obtain their maximum priority from that of their
\rassigned processor set.
\r <p>
\r<li>
\rA priority value which can be set by the thread to any value up to a
\rmaximum priority. Newly created threads obtain their priority from their task.
\r</ul>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="thread_info.html"><strong>thread_info</strong></a>,
\r<a href="task_info.html"><strong>task_info</strong></a>,
\r<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
\r<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>,
\r<a href="P_set_policy_disable.html"><strong>processor_set_policy_disable</strong></a>,
\r<a href="P_set_policy_enable.html"><strong>processor_set_policy_enable</strong></a>,
\r<a href="task_policy.html"><strong>task_policy</strong></a>,
\r<a href="thread_policy.html"><strong>thread_policy</strong></a>,
\r<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>.
\r<p>
\rData Structures:
\r<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>,
\r<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>.
\r\ No newline at end of file
+<h2>policy_fifo_info</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Specifies information associated with the system's First-In-First-Out scheduling policy.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct policy_fifo_limit</strong>
+<strong>{</strong>
+ <strong>int</strong> <var>max_priority</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>struct policy_fifo_base</strong>
+<strong>{</strong>
+ <strong>int</strong> <var>base_priority</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>struct policy_fifo_info</strong>
+<strong>{</strong>
+ <strong>int</strong> <var>max_priority</var><strong>;</strong>
+ <strong>int</strong> <var>base_priority</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>depressed</var><strong>;</strong>
+ <strong>int</strong> <var>depress_priority</var><strong>;</strong>
+<strong>};</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>max_priority</var>
+<dd>
+Maximum scheduling priority
+<p>
+<dt> <var>base_priority</var>
+<dd>
+Scheduling priority
+<p>
+<dt> <var>depressed</var>
+<dd>
+True if scheduling priority is depressed
+<p>
+<dt> <var>depress_priority</var>
+<dd>
+Scheduling priority from which depressed
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>policy_fifo_info</strong> structure defines the first-in-first-out
+scheduling policy information.
+FIFO threads have two priorities associated with them by the system:
+<ul>
+ <p>
+<li>
+A maximum priority value which can be raised only via privileged operation
+so that users may not unfairly compete with other users in their processor
+set. Newly created threads obtain their maximum priority from that of their
+assigned processor set.
+ <p>
+<li>
+A priority value which can be set by the thread to any value up to a
+maximum priority. Newly created threads obtain their priority from their task.
+</ul>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="thread_info.html"><strong>thread_info</strong></a>,
+<a href="task_info.html"><strong>task_info</strong></a>,
+<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
+<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>,
+<a href="P_set_policy_disable.html"><strong>processor_set_policy_disable</strong></a>,
+<a href="P_set_policy_enable.html"><strong>processor_set_policy_enable</strong></a>,
+<a href="task_policy.html"><strong>task_policy</strong></a>,
+<a href="thread_policy.html"><strong>thread_policy</strong></a>,
+<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>.
+<p>
+Data Structures:
+<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>,
+<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>.
-<h2>policy_rr_info</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Specifies information associated with the system's Round Robin scheduling policy.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct policy_rr_limit</strong>
\r<strong>{</strong>
\r <strong>int</strong> <var>max_priority</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>struct policy_rr_base</strong>
\r<strong>{</strong>
\r <strong>int</strong> <var>base_priority</var><strong>;</strong>
\r <strong>int</strong> <var>quantum</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>struct policy_rr_info</strong>
\r<strong>{</strong>
\r <strong>int</strong> <var>max_priority</var><strong>;</strong>
\r <strong>int</strong> <var>base_priority</var><strong>;</strong>
\r <strong>int</strong> <var>quantum</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>depressed</var><strong>;</strong>
\r <strong>int</strong> <var>depress_priority</var><strong>;</strong>
\r<strong>};</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>max_priority</var>
\r<dd>
\rMaximum scheduling priority
\r<p>
\r<dt> <var>base_priority</var>
\r<dd>
\rScheduling priority
\r<p>
\r<dt> <var>quantum</var>
\r<dd>
\rScheduling quantum (in milliseconds)
\r<p>
\r<dt> <var>depressed</var>
\r<dd>
\rTrue if scheduling priority is depressed
\r<p>
\r<dt> <var>depress_priority</var>
\r<dd>
\rScheduling priority from which depressed
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>policy_rr_info</strong> structure defines the round-robin
\rscheduling policy information.
\rRound-robin threads have two priorities associated with them by the system:
\r<ul>
\r <p>
\r<li>
\rA maximum priority value which can be raised only via privileged operation
\rso that users may not unfairly compete with other users in their processor
\rset. Newly created threads obtain their maximum priority from that of their
\rassigned processor set.
\r <p>
\r<li>
\rA priority value which can be set by the thread to any value up to a
\rmaximum priority. Newly created threads obtain their priority from their task.
\r</ul>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="thread_info.html"><strong>thread_info</strong></a>,
\r<a href="task_info.html"><strong>task_info</strong></a>,
\r<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
\r<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>,
\r<a href="P_set_policy_disable.html"><strong>processor_set_policy_disable</strong></a>,
\r<a href="P_set_policy_enable.html"><strong>processor_set_policy_enable</strong></a>,
\r<a href="task_policy.html"><strong>task_policy</strong></a>,
\r<a href="thread_policy.html"><strong>thread_policy</strong></a>,
\r<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>.
\r<p>
\rData Structures:
\r<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
\r<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>.
\r\ No newline at end of file
+<h2>policy_rr_info</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Specifies information associated with the system's Round Robin scheduling policy.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct policy_rr_limit</strong>
+<strong>{</strong>
+ <strong>int</strong> <var>max_priority</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>struct policy_rr_base</strong>
+<strong>{</strong>
+ <strong>int</strong> <var>base_priority</var><strong>;</strong>
+ <strong>int</strong> <var>quantum</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>struct policy_rr_info</strong>
+<strong>{</strong>
+ <strong>int</strong> <var>max_priority</var><strong>;</strong>
+ <strong>int</strong> <var>base_priority</var><strong>;</strong>
+ <strong>int</strong> <var>quantum</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>depressed</var><strong>;</strong>
+ <strong>int</strong> <var>depress_priority</var><strong>;</strong>
+<strong>};</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>max_priority</var>
+<dd>
+Maximum scheduling priority
+<p>
+<dt> <var>base_priority</var>
+<dd>
+Scheduling priority
+<p>
+<dt> <var>quantum</var>
+<dd>
+Scheduling quantum (in milliseconds)
+<p>
+<dt> <var>depressed</var>
+<dd>
+True if scheduling priority is depressed
+<p>
+<dt> <var>depress_priority</var>
+<dd>
+Scheduling priority from which depressed
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>policy_rr_info</strong> structure defines the round-robin
+scheduling policy information.
+Round-robin threads have two priorities associated with them by the system:
+<ul>
+ <p>
+<li>
+A maximum priority value which can be raised only via privileged operation
+so that users may not unfairly compete with other users in their processor
+set. Newly created threads obtain their maximum priority from that of their
+assigned processor set.
+ <p>
+<li>
+A priority value which can be set by the thread to any value up to a
+maximum priority. Newly created threads obtain their priority from their task.
+</ul>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="thread_info.html"><strong>thread_info</strong></a>,
+<a href="task_info.html"><strong>task_info</strong></a>,
+<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
+<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>,
+<a href="P_set_policy_disable.html"><strong>processor_set_policy_disable</strong></a>,
+<a href="P_set_policy_enable.html"><strong>processor_set_policy_enable</strong></a>,
+<a href="task_policy.html"><strong>task_policy</strong></a>,
+<a href="thread_policy.html"><strong>thread_policy</strong></a>,
+<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>.
+<p>
+Data Structures:
+<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
+<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>.
-<h2>policy_timeshare_info</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Specifies information associated with the system's Timeshare scheduling policy.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct policy_timeshare_limit</strong>
\r<strong>{</strong>
\r <strong>int</strong> <var>max_priority</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>struct policy_timeshare_base</strong>
\r<strong>{</strong>
\r <strong>int</strong> <var>base_priority</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>struct policy_timeshare_info</strong>
\r<strong>{</strong>
\r <strong>int</strong> <var>max_priority</var><strong>;</strong>
\r <strong>int</strong> <var>base_priority</var><strong>;</strong>
\r <strong>int</strong> <var>cur_priority</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>depressed</var><strong>;</strong>
\r <strong>int</strong> <var>depress_priority</var><strong>;</strong>
\r<strong>};</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>max_priority</var>
\r<dd>
\rMaximum scheduling priority.
\r<p>
\r<dt> <var>base_priority</var>
\r<dd>
\rBase scheduling priority.
\r<p>
\r<dt> <var>cur_priority</var>
\r<dd>
\rCurrent scheduling priority.
\r<p>
\r<dt> <var>depressed</var>
\r<dd>
\rTrue if scheduling priority is depressed.
\r<p>
\r<dt> <var>depress_priority</var>
\r<dd>
\rScheduling priority from which depressed.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>policy_timeshare_info</strong> structure defines the timeshare
\rscheduling policy
\rinformation.
\rTimeshare threads have three priorities associated with them by the system:
\r<ul>
\r <p>
\r<li>
\rA maximum priority value which can be raised only via privileged operation
\rso that users may not unfairly compete with other users in their processor
\rset. Newly created threads obtain their maximum priority from that of their
\rassigned processor set.
\r <p>
\r<li>
\rA priority value which can be set by the thread to any value up to a
\rmaximum priority. Newly created threads obtain their priority from their task.
\r <p>
\r<li>
\rA scheduled priority value which is used to make scheduling decisions for
\rthe thread. This value is determined on the basis of the user
\rpriority value by
\rthe scheduling policy (for time-sharing, this means adding an increment
\rderived from CPU usage).
\r</ul>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="thread_info.html"><strong>thread_info</strong></a>,
\r<a href="task_info.html"><strong>task_info</strong></a>,
\r<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
\r<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>,
\r<a href="P_set_policy_disable.html"><strong>processor_set_policy_disable</strong></a>,
\r<a href="P_set_policy_enable.html"><strong>processor_set_policy_enable</strong></a>,
\r<a href="task_policy.html"><strong>task_policy</strong></a>,
\r<a href="thread_policy.html"><strong>thread_policy</strong></a>,
\r<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>.
\r<p>
\rData Structures:
\r<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
\r<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>.
\r\ No newline at end of file
+<h2>policy_timeshare_info</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Specifies information associated with the system's Timeshare scheduling policy.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct policy_timeshare_limit</strong>
+<strong>{</strong>
+ <strong>int</strong> <var>max_priority</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>struct policy_timeshare_base</strong>
+<strong>{</strong>
+ <strong>int</strong> <var>base_priority</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>struct policy_timeshare_info</strong>
+<strong>{</strong>
+ <strong>int</strong> <var>max_priority</var><strong>;</strong>
+ <strong>int</strong> <var>base_priority</var><strong>;</strong>
+ <strong>int</strong> <var>cur_priority</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>depressed</var><strong>;</strong>
+ <strong>int</strong> <var>depress_priority</var><strong>;</strong>
+<strong>};</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>max_priority</var>
+<dd>
+Maximum scheduling priority.
+<p>
+<dt> <var>base_priority</var>
+<dd>
+Base scheduling priority.
+<p>
+<dt> <var>cur_priority</var>
+<dd>
+Current scheduling priority.
+<p>
+<dt> <var>depressed</var>
+<dd>
+True if scheduling priority is depressed.
+<p>
+<dt> <var>depress_priority</var>
+<dd>
+Scheduling priority from which depressed.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>policy_timeshare_info</strong> structure defines the timeshare
+scheduling policy
+information.
+Timeshare threads have three priorities associated with them by the system:
+<ul>
+ <p>
+<li>
+A maximum priority value which can be raised only via privileged operation
+so that users may not unfairly compete with other users in their processor
+set. Newly created threads obtain their maximum priority from that of their
+assigned processor set.
+ <p>
+<li>
+A priority value which can be set by the thread to any value up to a
+maximum priority. Newly created threads obtain their priority from their task.
+ <p>
+<li>
+A scheduled priority value which is used to make scheduling decisions for
+the thread. This value is determined on the basis of the user
+priority value by
+the scheduling policy (for time-sharing, this means adding an increment
+derived from CPU usage).
+</ul>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="thread_info.html"><strong>thread_info</strong></a>,
+<a href="task_info.html"><strong>task_info</strong></a>,
+<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
+<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>,
+<a href="P_set_policy_disable.html"><strong>processor_set_policy_disable</strong></a>,
+<a href="P_set_policy_enable.html"><strong>processor_set_policy_enable</strong></a>,
+<a href="task_policy.html"><strong>task_policy</strong></a>,
+<a href="thread_policy.html"><strong>thread_policy</strong></a>,
+<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>.
+<p>
+Data Structures:
+<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
+<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>.
-<h2>processor_assign</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Assign a processor to a processor set.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t processor_assign</strong>
\r <strong>(processor_t</strong> <var>processor</var>,
\r <strong>processor_set_t</strong> <var>new_set</var>,
\r <strong>boolean_t</strong> <var>wait</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>processor</var>
\r<dd>
\r[in processor send right]
\rThe processor to be assigned.
\r<dt> <var>new_set</var>
\r<dd>
\r[in processor-set-control send right]
\rThe control port for the processor
\rset into which the processor is to be assigned.
\r<dt> <var>wait</var>
\r<dd>
\r[in scalar]
\rTrue if the call should wait for the completion of the
\rassignment.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_assign</strong> function assigns <var>processor</var> to
\rthe set <var>new_set</var>. After the
\rassignment is completed, the processor only executes threads that are assigned
\rto that processor set. Any previous assignment of the processor
\ris nullified. The
\rmaster processor cannot be re-assigned.
\r<p>
\rThe <var>wait</var> argument indicates whether the
\rcaller should wait for the assignment
\rto be completed or should return immediately. Dedicated kernel threads are
\rused to perform processor assignment, so setting <var>wait</var> to <strong>FALSE</strong> allows
\rassignment requests to be queued and performed more quickly, especially
\rif the kernel has
\rmore than one dedicated internal thread for processor assignment.
\r<p>
\rAll processors take clock interrupts at all times. Redirection of other device
\rinterrupts away from processors assigned to other than the default
\rprocessor set is
\rmachine dependent.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_set_create.html">processor_set_create</a>,
\r<a href="processor_set_info.html">processor_set_info</a>,
\r<a href="task_assign.html">task_assign</a>,
\r<a href="thread_assign.html">thread_assign</a>.
\r\ No newline at end of file
+<h2>processor_assign</h2>
+<hr>
+<p>
+<strong>Function</strong> - Assign a processor to a processor set.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t processor_assign</strong>
+ <strong>(processor_t</strong> <var>processor</var>,
+ <strong>processor_set_t</strong> <var>new_set</var>,
+ <strong>boolean_t</strong> <var>wait</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>processor</var>
+<dd>
+[in processor send right]
+The processor to be assigned.
+<dt> <var>new_set</var>
+<dd>
+[in processor-set-control send right]
+The control port for the processor
+set into which the processor is to be assigned.
+<dt> <var>wait</var>
+<dd>
+[in scalar]
+True if the call should wait for the completion of the
+assignment.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_assign</strong> function assigns <var>processor</var> to
+the set <var>new_set</var>. After the
+assignment is completed, the processor only executes threads that are assigned
+to that processor set. Any previous assignment of the processor
+is nullified. The
+master processor cannot be re-assigned.
+<p>
+The <var>wait</var> argument indicates whether the
+caller should wait for the assignment
+to be completed or should return immediately. Dedicated kernel threads are
+used to perform processor assignment, so setting <var>wait</var> to <strong>FALSE</strong> allows
+assignment requests to be queued and performed more quickly, especially
+if the kernel has
+more than one dedicated internal thread for processor assignment.
+<p>
+All processors take clock interrupts at all times. Redirection of other device
+interrupts away from processors assigned to other than the default
+processor set is
+machine dependent.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_set_create.html">processor_set_create</a>,
+<a href="processor_set_info.html">processor_set_info</a>,
+<a href="task_assign.html">task_assign</a>,
+<a href="thread_assign.html">thread_assign</a>.
-<h2>processor_basic_info</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Defines the basic information about a processor.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct processor_basic_info</strong>
\r<strong>{</strong>
\r <strong>cpu_type_t</strong> <var>cpu_type</var><strong>;</strong>
\r <strong>cpu_subtype_t</strong> <var>cpu_subtype</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>running</var><strong>;</strong>
\r <strong>int</strong> <var>slot_num</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>is_master</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct processor_basic_info* processor_basic_info_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>cpu_type</var>
\r<dd>
\rType of CPU
\r<p>
\r<dt> <var>cpu_subtype</var>
\r<dd>
\rSub-type of CPU
\r<p>
\r<dt> <var>running</var>
\r<dd>
\rTrue if the CPU is running
\r<p>
\r<dt> <var>slot_num</var>
\r<dd>
\rSlot number of the CPU
\r<p>
\r<dt> <var>is_master</var>
\r<dd>
\rTrue if this is the master processor
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_basic_info</strong> structure defines the information
\ravailable about a processor slot.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_info.html"><strong>processor_info</strong></a>.
\r\ No newline at end of file
+<h2>processor_basic_info</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Defines the basic information about a processor.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct processor_basic_info</strong>
+<strong>{</strong>
+ <strong>cpu_type_t</strong> <var>cpu_type</var><strong>;</strong>
+ <strong>cpu_subtype_t</strong> <var>cpu_subtype</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>running</var><strong>;</strong>
+ <strong>int</strong> <var>slot_num</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>is_master</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct processor_basic_info* processor_basic_info_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>cpu_type</var>
+<dd>
+Type of CPU
+<p>
+<dt> <var>cpu_subtype</var>
+<dd>
+Sub-type of CPU
+<p>
+<dt> <var>running</var>
+<dd>
+True if the CPU is running
+<p>
+<dt> <var>slot_num</var>
+<dd>
+Slot number of the CPU
+<p>
+<dt> <var>is_master</var>
+<dd>
+True if this is the master processor
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_basic_info</strong> structure defines the information
+available about a processor slot.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_info.html"><strong>processor_info</strong></a>.
-<h2>processor_control</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Perform caller-specified operation on target processor. (Protected Interface.)
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t processor_control</strong>
\r <strong>(processor_t</strong> <var>processor</var>,
\r <strong>processor_info_t</strong> <var>cmd</var>,
\r <strong>mach_msg_type_number_t*</strong> <var>count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>processor</var>
\r<dd>
\r[in processor send right]
\rThe processor to be controlled.
\r<dt> <var>cmd</var>
\r<dd>
\r[pointer to in array of natural-sized units]
\rAn array containing the
\rcommand to be applied to the processor.
\r<dt> <var>count</var>
\r<dd>
\r[in scalar]
\rThe size of the <var>cmd</var> array (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_control</strong> function allows privileged software
\rto control a
\rprocessor in a multi-processor that so allows it. The interpretation
\rof <var>cmd</var> is machine
\rdependent.
\r<h3>NOTES</h3>
\r<p>
\rThese operations are machine dependent. They may do nothing.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<dt> <strong>KERN_FAILURE</strong>
\r<dd>
\rThe operation was not performed. A likely reason is that it
\ris not supported on this processor.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_start.html">processor_start</a>,
\r<a href="processor_exit.html">processor_exit</a>,
\r<a href="processor_info.html">processor_info</a>,
\r<a href="host_processors.html">host_processors</a>.
\r\ No newline at end of file
+<h2>processor_control</h2>
+<hr>
+<p>
+<strong>Function</strong> - Perform caller-specified operation on target processor. (Protected Interface.)
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t processor_control</strong>
+ <strong>(processor_t</strong> <var>processor</var>,
+ <strong>processor_info_t</strong> <var>cmd</var>,
+ <strong>mach_msg_type_number_t*</strong> <var>count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>processor</var>
+<dd>
+[in processor send right]
+The processor to be controlled.
+<dt> <var>cmd</var>
+<dd>
+[pointer to in array of natural-sized units]
+An array containing the
+command to be applied to the processor.
+<dt> <var>count</var>
+<dd>
+[in scalar]
+The size of the <var>cmd</var> array (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_control</strong> function allows privileged software
+to control a
+processor in a multi-processor that so allows it. The interpretation
+of <var>cmd</var> is machine
+dependent.
+<h3>NOTES</h3>
+<p>
+These operations are machine dependent. They may do nothing.
+<h3>RETURN VALUES</h3>
+<dl>
+<dt> <strong>KERN_FAILURE</strong>
+<dd>
+The operation was not performed. A likely reason is that it
+is not supported on this processor.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_start.html">processor_start</a>,
+<a href="processor_exit.html">processor_exit</a>,
+<a href="processor_info.html">processor_info</a>,
+<a href="host_processors.html">host_processors</a>.
-<h2>processor_exit</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Exit a processor.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t processor_exit</strong>
\r <strong>(processor_t</strong> <var>processor</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>processor</var>
\r<dd>
\r[in processor send right]
\rThe processor to be controlled.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_exit</strong> function allows privileged software
\rto exit a processor in a
\rmulti-processor that so allows it. An exited processor is removed from the
\rprocessor set to which it was assigned and ceases to be active.
\rThe interpretation of
\rthis operation is machine dependent.
\r<h3>NOTES</h3>
\r<p>
\rThis operation is machine dependent. It may do nothing.
\r<h3>CAUTIONS</h3>
\r<p>
\rThe ability to restart an exited processor is machine dependent.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<dt> <strong>KERN_FAILURE</strong>
\r<dd>
\rThe operation was not performed. A likely reason is that it
\ris not supported on this processor.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_control.html">processor_control</a>,
\r<a href="processor_start.html">processor_start</a>,
\r<a href="processor_info.html">processor_info</a>,
\r<a href="host_processors.html">host_processors</a>.
\r\ No newline at end of file
+<h2>processor_exit</h2>
+<hr>
+<p>
+<strong>Function</strong> - Exit a processor.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t processor_exit</strong>
+ <strong>(processor_t</strong> <var>processor</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>processor</var>
+<dd>
+[in processor send right]
+The processor to be controlled.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_exit</strong> function allows privileged software
+to exit a processor in a
+multi-processor that so allows it. An exited processor is removed from the
+processor set to which it was assigned and ceases to be active.
+The interpretation of
+this operation is machine dependent.
+<h3>NOTES</h3>
+<p>
+This operation is machine dependent. It may do nothing.
+<h3>CAUTIONS</h3>
+<p>
+The ability to restart an exited processor is machine dependent.
+<h3>RETURN VALUES</h3>
+<dl>
+<dt> <strong>KERN_FAILURE</strong>
+<dd>
+The operation was not performed. A likely reason is that it
+is not supported on this processor.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_control.html">processor_control</a>,
+<a href="processor_start.html">processor_start</a>,
+<a href="processor_info.html">processor_info</a>,
+<a href="host_processors.html">host_processors</a>.
-<h2>processor_get_assignment</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Get current assignment for a processor.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t processor_get_assignment</strong>
\r <strong>(processor_t</strong> <var>processor</var>,
\r <strong>processor_set_name_t</strong> <var>assigned_set</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>processor</var>
\r<dd>
\r[in processor send right]
\rThe processor whose assignment is desired.
\r<dt> <var>new_set</var>
\r<dd>
\r[out processor-set-name send right]
\rThe name port for the processor
\rset to which <var>processor</var> is currently assigned.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_get_assignment</strong> function returns the name port for the
\rprocessor set to which a desired processor is currently assigned.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<dt> <strong>KERN_FAILURE</strong>
\r<dd>
\rProcessor is either shut down of off-line.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_assign.html">processor_assign</a>,
\r<a href="processor_set_create.html">processor_set_create</a>,
\r<a href="processor_info.html">processor_info</a>,
\r<a href="task_assign.html">task_assign</a>,
\r<a href="thread_assign.html">thread_assign</a>.
\r\ No newline at end of file
+<h2>processor_get_assignment</h2>
+<hr>
+<p>
+<strong>Function</strong> - Get current assignment for a processor.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t processor_get_assignment</strong>
+ <strong>(processor_t</strong> <var>processor</var>,
+ <strong>processor_set_name_t</strong> <var>assigned_set</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>processor</var>
+<dd>
+[in processor send right]
+The processor whose assignment is desired.
+<dt> <var>new_set</var>
+<dd>
+[out processor-set-name send right]
+The name port for the processor
+set to which <var>processor</var> is currently assigned.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_get_assignment</strong> function returns the name port for the
+processor set to which a desired processor is currently assigned.
+<h3>RETURN VALUES</h3>
+<dl>
+<dt> <strong>KERN_FAILURE</strong>
+<dd>
+Processor is either shut down of off-line.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_assign.html">processor_assign</a>,
+<a href="processor_set_create.html">processor_set_create</a>,
+<a href="processor_info.html">processor_info</a>,
+<a href="task_assign.html">task_assign</a>,
+<a href="thread_assign.html">thread_assign</a>.
-<h2>processor_info</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return information about a processor.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t processor_info</strong>
\r <strong>(processor_t</strong> <var>processor</var>,
\r <strong>processor_flavor_t</strong> <var>flavor</var>,
\r <strong>host_t</strong> <var>host</var>,
\r <strong>processor_info_t</strong> <var>processor_info</var>,
\r <strong>mach_msg_type_number_t</strong> <var>processor_info_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>processor</var>
\r<dd>
\r[in processor send right]
\rA processor port for which information is
\rdesired.
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of information requested.
\r<dl>
\r<dt> <strong>PROCESSOR_BASIC_INFO</strong>
\r<dd>
\rBasic information, slot number, running status, etc. The
\rreturned structure is <strong>processor_basic_info</strong>.
\r</dl>
\r<dt> <var>host</var>
\r<dd>
\r[out host-name send right]
\rThe host on which the processor resides.
\rThis is the host name port.
\r<dt> <var>processor_info</var>
\r<dd>
\r[out structure]
\rInformation about the processor.
\r<dt> <var>processor_info_count</var>
\r<dd>
\r[in/out scalar]
\rOn input, the maximum size of the buffer; on output, the
\rsize returned (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_info</strong> function returns selected information
\rfor a processor, as specified by <var>flavor</var>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_start.html">processor_start</a>,
\r<a href="processor_exit.html">processor_exit</a>,
\r<a href="processor_control.html">processor_control</a>,
\r<a href="host_processors.html">host_processors</a>.
\r<p>
\rData Structures:
\r<a href="processor_basic_info.html">processor_basic_info</a>.
\r\ No newline at end of file
+<h2>processor_info</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return information about a processor.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t processor_info</strong>
+ <strong>(processor_t</strong> <var>processor</var>,
+ <strong>processor_flavor_t</strong> <var>flavor</var>,
+ <strong>host_t</strong> <var>host</var>,
+ <strong>processor_info_t</strong> <var>processor_info</var>,
+ <strong>mach_msg_type_number_t</strong> <var>processor_info_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>processor</var>
+<dd>
+[in processor send right]
+A processor port for which information is
+desired.
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of information requested.
+<dl>
+<dt> <strong>PROCESSOR_BASIC_INFO</strong>
+<dd>
+Basic information, slot number, running status, etc. The
+returned structure is <strong>processor_basic_info</strong>.
+</dl>
+<dt> <var>host</var>
+<dd>
+[out host-name send right]
+The host on which the processor resides.
+This is the host name port.
+<dt> <var>processor_info</var>
+<dd>
+[out structure]
+Information about the processor.
+<dt> <var>processor_info_count</var>
+<dd>
+[in/out scalar]
+On input, the maximum size of the buffer; on output, the
+size returned (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_info</strong> function returns selected information
+for a processor, as specified by <var>flavor</var>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_start.html">processor_start</a>,
+<a href="processor_exit.html">processor_exit</a>,
+<a href="processor_control.html">processor_control</a>,
+<a href="host_processors.html">host_processors</a>.
+<p>
+Data Structures:
+<a href="processor_basic_info.html">processor_basic_info</a>.
-<h2>processor_set_basic_info</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Defines the basic information about a processor set.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct processor_set_basic_info</strong>
\r<strong>{</strong>
\r <strong>int</strong> <var>processor_count</var><strong>;</strong>
\r <strong>int</strong> <var>default_policy</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct processor_set_basic_info* processor_set_basic_info_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>processor_count</var>
\r<dd>
\rNumber of processors in this set.
\r<p>
\r<dt> <var>default_policy</var>
\r<dd>
\rDefault policy to assign to threads whose otherwise assigned policy is
\rnot enabled.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_set_basic_info</strong> structure defines the
\rbasic information available about a processor set.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_set_info.html"><strong>processor_set_info</strong></a>.
\r<p>
\rData Structures:
\r<a href="processor_set_load_info.html"></strong>processor_set_load_info<strong></a>.
\r\ No newline at end of file
+<h2>processor_set_basic_info</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Defines the basic information about a processor set.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct processor_set_basic_info</strong>
+<strong>{</strong>
+ <strong>int</strong> <var>processor_count</var><strong>;</strong>
+ <strong>int</strong> <var>default_policy</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct processor_set_basic_info* processor_set_basic_info_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>processor_count</var>
+<dd>
+Number of processors in this set.
+<p>
+<dt> <var>default_policy</var>
+<dd>
+Default policy to assign to threads whose otherwise assigned policy is
+not enabled.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_set_basic_info</strong> structure defines the
+basic information available about a processor set.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_set_info.html"><strong>processor_set_info</strong></a>.
+<p>
+Data Structures:
+<a href="processor_set_load_info.html"></strong>processor_set_load_info<strong></a>.
-<h2>processor_set_create</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Create a new processor set object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t processor_set_create</strong>
\r <strong>(host_t</strong> <var>host_name</var>,
\r <strong>processor_set_t</strong> <var>new_set</var>,
\r <strong>processor_set_name_t</strong> <var>new_name</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>host_name</var>
\r<dd>
\r[in host-name send right]
\rThe name (or control) port for the host on
\rwhich the set is to be created.
\r<dt> <var>new_set</var>
\r<dd>
\r[out processor-set-control send right]
\rControl port used for performing
\roperations on the new set.
\r<dt> <var>new_name</var>
\r<dd>
\r[out processor-set-name send right]
\rName port used to identify the new
\rset and obtain information about it.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_set_create</strong> function creates a new processor
\rset and returns the
\rtwo ports associated with it. The port returned in <var>new_set</var> is the control port
\rrepresenting the set. It is used to perform operations such
\ras assigning processors,
\rtasks or threads. The port returned in <var>new_name</var> is the name port which
\ridentifies the set, and is used to obtain information about the set.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic values apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_set_destroy.html">processor_set_destroy</a>,
\r<a href="processor_set_info.html">processor_set_info</a>,
\r<a href="processor_assign.html">processor_assign</a>,
\r<a href="task_assign.html">task_assign</a>,
\r<a href="thread_assign.html">thread_assign</a>.
\r\ No newline at end of file
+<h2>processor_set_create</h2>
+<hr>
+<p>
+<strong>Function</strong> - Create a new processor set object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t processor_set_create</strong>
+ <strong>(host_t</strong> <var>host_name</var>,
+ <strong>processor_set_t</strong> <var>new_set</var>,
+ <strong>processor_set_name_t</strong> <var>new_name</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>host_name</var>
+<dd>
+[in host-name send right]
+The name (or control) port for the host on
+which the set is to be created.
+<dt> <var>new_set</var>
+<dd>
+[out processor-set-control send right]
+Control port used for performing
+operations on the new set.
+<dt> <var>new_name</var>
+<dd>
+[out processor-set-name send right]
+Name port used to identify the new
+set and obtain information about it.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_set_create</strong> function creates a new processor
+set and returns the
+two ports associated with it. The port returned in <var>new_set</var> is the control port
+representing the set. It is used to perform operations such
+as assigning processors,
+tasks or threads. The port returned in <var>new_name</var> is the name port which
+identifies the set, and is used to obtain information about the set.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic values apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_set_destroy.html">processor_set_destroy</a>,
+<a href="processor_set_info.html">processor_set_info</a>,
+<a href="processor_assign.html">processor_assign</a>,
+<a href="task_assign.html">task_assign</a>,
+<a href="thread_assign.html">thread_assign</a>.
-<h2>processor_set_default</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return the default processor set.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t processor_set_default</strong>
\r <strong>(host_t</strong> <var>host</var>,
\r <strong>processor_set_name_t</strong> <var>default_set_name</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>host</var>
\r<dd>
\r[in host-name send right]
\rThe name (or control) port for the host for
\rwhich the default processor set is desired.
\r<dt> <var>default_set_name</var>
\r<dd>
\r[out processor-set-name send right]
\rThe returned name port for the
\rdefault processor set.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_set_default</strong> function returns the name
\rport for the default
\rprocessor set for the specified host. The default processor
\rset is used by all threads,
\rtasks and processors that are not explicitly assigned to other sets.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_set_info.html">processor_set_info</a>,
\r<a href="thread_assign.html">thread_assign</a>,
\r<a href="task_assign.html">task_assign</a>.
\r\ No newline at end of file
+<h2>processor_set_default</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return the default processor set.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t processor_set_default</strong>
+ <strong>(host_t</strong> <var>host</var>,
+ <strong>processor_set_name_t</strong> <var>default_set_name</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>host</var>
+<dd>
+[in host-name send right]
+The name (or control) port for the host for
+which the default processor set is desired.
+<dt> <var>default_set_name</var>
+<dd>
+[out processor-set-name send right]
+The returned name port for the
+default processor set.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_set_default</strong> function returns the name
+port for the default
+processor set for the specified host. The default processor
+set is used by all threads,
+tasks and processors that are not explicitly assigned to other sets.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_set_info.html">processor_set_info</a>,
+<a href="thread_assign.html">thread_assign</a>,
+<a href="task_assign.html">task_assign</a>.
-<h2>processor_set_destroy</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Destroy the target processor set object.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t processor_set_destroy</strong>
\r <strong>(processor_set_t</strong> <var>processor_set</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>processor_set</var>
\r<dd>
\r[in processor-set-control send right]
\rThe control port for the processor
\rset to be destroyed.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_set_destroy</strong> function destroys the specified
\rprocessor set. Any
\rassigned processors, tasks or threads are re-assigned to the default set. The
\robject port (not the name port) for the processor set is required.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<dt> <strong>KERN_DEFAULT_SET</strong>
\r<dd>
\rAn attempt was made to destroy the default processor set.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_set_create.html">processor_set_create</a>,
\r<a href="processor_assign.html">processor_assign</a>,
\r<a href="task_assign.html">task_assign</a>,
\r<a href="thread_assign.html">thread_assign</a>.
\r\ No newline at end of file
+<h2>processor_set_destroy</h2>
+<hr>
+<p>
+<strong>Function</strong> - Destroy the target processor set object.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t processor_set_destroy</strong>
+ <strong>(processor_set_t</strong> <var>processor_set</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>processor_set</var>
+<dd>
+[in processor-set-control send right]
+The control port for the processor
+set to be destroyed.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_set_destroy</strong> function destroys the specified
+processor set. Any
+assigned processors, tasks or threads are re-assigned to the default set. The
+object port (not the name port) for the processor set is required.
+<h3>RETURN VALUES</h3>
+<dl>
+<dt> <strong>KERN_DEFAULT_SET</strong>
+<dd>
+An attempt was made to destroy the default processor set.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_set_create.html">processor_set_create</a>,
+<a href="processor_assign.html">processor_assign</a>,
+<a href="task_assign.html">task_assign</a>,
+<a href="thread_assign.html">thread_assign</a>.
-<h2>processor_set_info</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return processor set state according to caller-specified flavor.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t processor_set_info</strong>
\r <strong>(processor_set_name_t</strong> <var>processor_set_name</var>,
\r <strong>int</strong> <var>flavor</var>,
\r <strong>host_t</strong> <var>host</var>,
\r <strong>processor_set_info_t</strong> <var>processor_set_info</var>,
\r <strong>mach_msg_type_number_t</strong> <var>processor_set_info_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>processor_set_name</var>
\r<dd>
\r[in processor-set-name send right]
\rA processor set name (or control)
\rport for which information is desired.
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of information requested.
\r<dl>
\r<dt> <strong>PROCESSOR_SET_BASIC_INFO</strong>
\r<dd>
\rBasic information concerning the processor set (number of
\rassigned processors and default policy). The returned structure
\ris defined by <strong>processor_set_basic_info</strong>.
\r<dt> <strong>PROCESSOR_SET_TIMESHARE_DEFAULT</strong>
\r<dd>
\rThe base attributes for the timeshare scheduling policy. The
\rreturned structure is <strong>policy_timeshare_base</strong>.
\r<dt> <strong>PROCESSOR_SET_FIFO_DEFAULT</strong>
\r<dd>
\rThe base attributes for the FIFO scheduling policy. The
\rreturned structure is <strong>policy_fifo_base</strong>.
\r<dt> <strong>PROCESSOR_SET_RR_DEFAULT</strong>
\r<dd>
\rThe base attributes for the round-robin scheduling policy. The
\rreturned structure is <strong>policy_rr_base</strong>.
\r<dt> <strong>PROCESSOR_SET_TIMESHARE_LIMITS</strong>
\r<dd>
\rLimits on the allowed timeshare policy attributes. The
\rreturned structure is defined by <strong>policy_timeshare_limit</strong>.
\r<dt> <strong>PROCESSOR_SET_RR_LIMITS</strong>
\r<dd>
\rLimits on the allowed round robin policy attributes. The
\rreturned structure is defined by <strong>policy_rr_limit</strong>.
\r<dt> <strong>PROCESSOR_SET_FIFO_LIMITS</strong>
\r<dd>
\rLimits on the allowed first-in, first-out policy attributes. The
\rreturned structure is defined by <strong>policy_fifo_limit</strong>.
\r<dt> <strong>PROCESSOR_SET_ENABLED_POLICIES</strong>
\r<dd>
\rThe set of enabled policies. The returned data is a bit-vector.
\r</dl>
\r<dt> <var>host</var>
\r<dd>
\r[out host-name send right]
\rThe name port for the host on which the
\rprocessor set resides.
\r<dt> <var>processor_set_info</var>
\r<dd>
\r[out structure]
\rInformation about the processor set.
\r<dt> <var>processor_set_info_count</var>
\r<dd>
\r[in/out scalar]
\rOn input, the maximum size of the buffer; on output, the
\rsize returned (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_set_info</strong> function returns selected information
\rfor a processor set, as specified by <var>flavor</var>.
\r<h3>NOTES</h3>
\r<p>
\rA processor set has a single default scheduling policy in effect for it (as
\rreturned by <strong>PROCESSOR_SET_BASIC_INFO</strong>), so only one of the default
\rscheduling structures has valid information. On the other hand,
\ra processor set
\rmaintains limits for all defined scheduling policies, so all
\rof the scheduling limit
\rstructures return valid values.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_set_statistics.html">processor_set_statistics</a>,
\r<a href="processor_set_create.html">processor_set_create</a>,
\r<a href="processor_set_default.html">processor_set_default</a>,
\r<a href="processor_assign.html">processor_assign</a>,
\r<a href="P_set_policy_control.html">processor_set_policy_control</a>.
\r<p>
\rData Structures:
\r<a href="processor_set_basic_info.html">processor_set_basic_info</a>,
\r<a href="policy_timeshare_info.html">policy_timeshare_info</a>,
\r<a href="policy_rr_info.html">policy_rr_info</a>,
\r<a href="policy_fifo_info.html">policy_fifo_info</a>.
\r\ No newline at end of file
+<h2>processor_set_info</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return processor set state according to caller-specified flavor.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t processor_set_info</strong>
+ <strong>(processor_set_name_t</strong> <var>processor_set_name</var>,
+ <strong>int</strong> <var>flavor</var>,
+ <strong>host_t</strong> <var>host</var>,
+ <strong>processor_set_info_t</strong> <var>processor_set_info</var>,
+ <strong>mach_msg_type_number_t</strong> <var>processor_set_info_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>processor_set_name</var>
+<dd>
+[in processor-set-name send right]
+A processor set name (or control)
+port for which information is desired.
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of information requested.
+<dl>
+<dt> <strong>PROCESSOR_SET_BASIC_INFO</strong>
+<dd>
+Basic information concerning the processor set (number of
+assigned processors and default policy). The returned structure
+is defined by <strong>processor_set_basic_info</strong>.
+<dt> <strong>PROCESSOR_SET_TIMESHARE_DEFAULT</strong>
+<dd>
+The base attributes for the timeshare scheduling policy. The
+returned structure is <strong>policy_timeshare_base</strong>.
+<dt> <strong>PROCESSOR_SET_FIFO_DEFAULT</strong>
+<dd>
+The base attributes for the FIFO scheduling policy. The
+returned structure is <strong>policy_fifo_base</strong>.
+<dt> <strong>PROCESSOR_SET_RR_DEFAULT</strong>
+<dd>
+The base attributes for the round-robin scheduling policy. The
+returned structure is <strong>policy_rr_base</strong>.
+<dt> <strong>PROCESSOR_SET_TIMESHARE_LIMITS</strong>
+<dd>
+Limits on the allowed timeshare policy attributes. The
+returned structure is defined by <strong>policy_timeshare_limit</strong>.
+<dt> <strong>PROCESSOR_SET_RR_LIMITS</strong>
+<dd>
+Limits on the allowed round robin policy attributes. The
+returned structure is defined by <strong>policy_rr_limit</strong>.
+<dt> <strong>PROCESSOR_SET_FIFO_LIMITS</strong>
+<dd>
+Limits on the allowed first-in, first-out policy attributes. The
+returned structure is defined by <strong>policy_fifo_limit</strong>.
+<dt> <strong>PROCESSOR_SET_ENABLED_POLICIES</strong>
+<dd>
+The set of enabled policies. The returned data is a bit-vector.
+</dl>
+<dt> <var>host</var>
+<dd>
+[out host-name send right]
+The name port for the host on which the
+processor set resides.
+<dt> <var>processor_set_info</var>
+<dd>
+[out structure]
+Information about the processor set.
+<dt> <var>processor_set_info_count</var>
+<dd>
+[in/out scalar]
+On input, the maximum size of the buffer; on output, the
+size returned (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_set_info</strong> function returns selected information
+for a processor set, as specified by <var>flavor</var>.
+<h3>NOTES</h3>
+<p>
+A processor set has a single default scheduling policy in effect for it (as
+returned by <strong>PROCESSOR_SET_BASIC_INFO</strong>), so only one of the default
+scheduling structures has valid information. On the other hand,
+a processor set
+maintains limits for all defined scheduling policies, so all
+of the scheduling limit
+structures return valid values.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_set_statistics.html">processor_set_statistics</a>,
+<a href="processor_set_create.html">processor_set_create</a>,
+<a href="processor_set_default.html">processor_set_default</a>,
+<a href="processor_assign.html">processor_assign</a>,
+<a href="P_set_policy_control.html">processor_set_policy_control</a>.
+<p>
+Data Structures:
+<a href="processor_set_basic_info.html">processor_set_basic_info</a>,
+<a href="policy_timeshare_info.html">policy_timeshare_info</a>,
+<a href="policy_rr_info.html">policy_rr_info</a>,
+<a href="policy_fifo_info.html">policy_fifo_info</a>.
-<h2>processor_set_load_info</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Defines the scheduling statistics for a processor set.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct processor_set_load_info</strong>
\r<strong>{</strong>
\r <strong>int</strong> <var>task_count</var><strong>;</strong>
\r <strong>int</strong> <var>thread_count</var><strong>;</strong>
\r <strong>integer_t</strong> <var>load_average</var><strong>;</strong>
\r <strong>integer_t</strong> <var>mach_factor</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct processor_set_load_info* processor_set_load_info_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>task_count</var>
\r<dd>
\rNumber of tasks currently assigned to this processor set
\r<p>
\r<dt> <var>thread_count</var>
\r<dd>
\rNumber of threads currently assigned to this processor set
\r<p>
\r<dt> <var>load_average</var>
\r<dd>
\rAverage number of runnable processes divided by number of CPUs
\r<p>
\r<dt> <var>mach_factor</var>
\r<dd>
\rThe processing resources available to a new thread\(emthe number of
\rCPUs divided by (1 + the number of threads)
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_set_load_info</strong> structure defines the scheduling
\rstatistics
\rmaintained for a processor set.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\r<p>
\rData Structures:
\r<a href="processor_set_basic_info.html"><strong>processor_set_basic_info</strong></a>.
\r\ No newline at end of file
+<h2>processor_set_load_info</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Defines the scheduling statistics for a processor set.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct processor_set_load_info</strong>
+<strong>{</strong>
+ <strong>int</strong> <var>task_count</var><strong>;</strong>
+ <strong>int</strong> <var>thread_count</var><strong>;</strong>
+ <strong>integer_t</strong> <var>load_average</var><strong>;</strong>
+ <strong>integer_t</strong> <var>mach_factor</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct processor_set_load_info* processor_set_load_info_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>task_count</var>
+<dd>
+Number of tasks currently assigned to this processor set
+<p>
+<dt> <var>thread_count</var>
+<dd>
+Number of threads currently assigned to this processor set
+<p>
+<dt> <var>load_average</var>
+<dd>
+Average number of runnable processes divided by number of CPUs
+<p>
+<dt> <var>mach_factor</var>
+<dd>
+The processing resources available to a new thread\(emthe number of
+CPUs divided by (1 + the number of threads)
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_set_load_info</strong> structure defines the scheduling
+statistics
+maintained for a processor set.
+<h3>RELATED INFORMATION</h3>
+<p>
+<p>
+Data Structures:
+<a href="processor_set_basic_info.html"><strong>processor_set_basic_info</strong></a>.
-<h2>processor_set_max_priority</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Sets the maximum scheduling priority for a processor set.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include< mach/mach_host.h></strong>
\r\r<strong>kern_return_t processor_set_max_priority</strong>
\r <strong>(processor_set_t</strong> <var>processor_set</var>,
\r <strong>int</strong> <var>priority</var>,
\r <strong>boolean_t</strong> <var>change_threads</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>processor_set</var>
\r<dd>
\r[in processor-set-control port] The control port for the processor set whose maximum scheduling priority is to be set.
\r<dt> <var>priority</var>
\r<dd>
\r[in scalar] The new priority for the processor set.
\r<dt> <var>change_threads</var>
\r<dd>
\r[in scalar] True if the maximum priority of existing threads assigned to this processor set should also be changed.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_set_max_priority</strong>
\rfunction sets the maximum scheduling <var>priority</var> for
\r<var>processor_set</var>. The maximum <var>priority</var> of a
\rprocessor set is used only when creating new threads. A new thread's
\rmaximum <var>priority</var> is set to that of its assigned processor
\rset. When assigned to a processor set, a thread's maximum
\r<var>priority</var> is reduced, if necessary, to that of its new
\rprocessor set; its current <var>priority</var> is also reduced, as
\rneeded. Changing the maximum <var>priority</var> of a processor set
\rdoes not affect the <var>priority</var> of the currently assigned
\rthreads unless <var>change_threads</var> is TRUE. If this
\r<var>priority</var> change violates the maximum <var>priority</var> of
\rsome threads, their maximum priorities will be reduced to match.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="thread_assign.html">thread_assign</a>.
\r\ No newline at end of file
+<h2>processor_set_max_priority</h2>
+<hr>
+<p>
+<strong>Function</strong> - Sets the maximum scheduling priority for a processor set.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include< mach/mach_host.h></strong>
+
+<strong>kern_return_t processor_set_max_priority</strong>
+ <strong>(processor_set_t</strong> <var>processor_set</var>,
+ <strong>int</strong> <var>priority</var>,
+ <strong>boolean_t</strong> <var>change_threads</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>processor_set</var>
+<dd>
+[in processor-set-control port] The control port for the processor set whose maximum scheduling priority is to be set.
+<dt> <var>priority</var>
+<dd>
+[in scalar] The new priority for the processor set.
+<dt> <var>change_threads</var>
+<dd>
+[in scalar] True if the maximum priority of existing threads assigned to this processor set should also be changed.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_set_max_priority</strong>
+function sets the maximum scheduling <var>priority</var> for
+<var>processor_set</var>. The maximum <var>priority</var> of a
+processor set is used only when creating new threads. A new thread's
+maximum <var>priority</var> is set to that of its assigned processor
+set. When assigned to a processor set, a thread's maximum
+<var>priority</var> is reduced, if necessary, to that of its new
+processor set; its current <var>priority</var> is also reduced, as
+needed. Changing the maximum <var>priority</var> of a processor set
+does not affect the <var>priority</var> of the currently assigned
+threads unless <var>change_threads</var> is TRUE. If this
+<var>priority</var> change violates the maximum <var>priority</var> of
+some threads, their maximum priorities will be reduced to match.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="thread_assign.html">thread_assign</a>.
-<h2>processor_set_statistics</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return scheduling statistics for a processor set.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t processor_set_statistics</strong>
\r <strong>(processor_set_t</strong> <var>processor_set_control</var>,
\r <strong>processor_set_flavor_t</strong> <var>flavor</var>,
\r <strong>processor_set_info_t</strong> <var>processor_set_info</var>,
\r <strong>mach_msg_type_number_t</strong> <var>processor_set_info_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>processor_set_control</var>
\r<dd>
\r[in processor-set-control send right]
\rA processor set control port for
\rwhich information is desired.
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of information requested.
\r<dl>
\r<dt> <strong>PROCESSOR_SET_LOAD_INFO</strong>
\r<dd>
\rLoad statistics for the processor set. The returned structure is
\r<strong>processor_set_load_info</strong>.
\r</dl>
\r<dt> <var>processor_set_info</var>
\r<dd>
\r[out structure]
\rInformation about the processor set.
\r<dt> <var>processor_set_info_count</var>
\r<dd>
\r[in/out scalar]
\rOn input, the maximum size of the buffer; on output, the
\rsize returned (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_set_statistics</strong> function returns statistics
\rfor a processor set as specified by <var>flavor</var>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_set_info.html">processor_set_info</a>.
\r<p>
\rData Structures:
\r<a href="processor_set_load_info.html">processor_set_load_info</a>.
\r\ No newline at end of file
+<h2>processor_set_statistics</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return scheduling statistics for a processor set.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t processor_set_statistics</strong>
+ <strong>(processor_set_t</strong> <var>processor_set_control</var>,
+ <strong>processor_set_flavor_t</strong> <var>flavor</var>,
+ <strong>processor_set_info_t</strong> <var>processor_set_info</var>,
+ <strong>mach_msg_type_number_t</strong> <var>processor_set_info_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>processor_set_control</var>
+<dd>
+[in processor-set-control send right]
+A processor set control port for
+which information is desired.
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of information requested.
+<dl>
+<dt> <strong>PROCESSOR_SET_LOAD_INFO</strong>
+<dd>
+Load statistics for the processor set. The returned structure is
+<strong>processor_set_load_info</strong>.
+</dl>
+<dt> <var>processor_set_info</var>
+<dd>
+[out structure]
+Information about the processor set.
+<dt> <var>processor_set_info_count</var>
+<dd>
+[in/out scalar]
+On input, the maximum size of the buffer; on output, the
+size returned (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_set_statistics</strong> function returns statistics
+for a processor set as specified by <var>flavor</var>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_set_info.html">processor_set_info</a>.
+<p>
+Data Structures:
+<a href="processor_set_load_info.html">processor_set_load_info</a>.
-<h2>processor_set_tasks</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return a list of pointers to all tasks currently assigned to the target processor set.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t processor_set_tasks</strong>
\r <strong>(processor_set_t</strong> <var>processor_set</var>,
\r <strong>task_port_array_t</strong> <var>task_list</var>,
\r <strong>mach_msg_type_number_t*</strong> <var>task_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>processor_set</var>
\r<dd>
\r[in processor-set-control send right]
\rA processor set control port for
\rwhich information is desired.
\r<dt> <var>task_list</var>
\r<dd>
\r[out pointer to dynamic array of task send rights]
\rThe returned set of
\rports naming the tasks currently assigned to <var>processor_set</var>.
\r<dt> <var>task_count</var>
\r<dd>
\r[out scalar]
\rThe number of tasks returned in <var>task_list</var>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_set_tasks</strong> function returns send rights
\rto the kernel ports for each task currently assigned to <var>processor_set</var>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_set_threads.html">processor_set_threads</a>,
\r<a href="task_assign.html">task_assign</a>,
\r<a href="thread_assign.html">thread_assign</a>.
\r\ No newline at end of file
+<h2>processor_set_tasks</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return a list of pointers to all tasks currently assigned to the target processor set.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t processor_set_tasks</strong>
+ <strong>(processor_set_t</strong> <var>processor_set</var>,
+ <strong>task_port_array_t</strong> <var>task_list</var>,
+ <strong>mach_msg_type_number_t*</strong> <var>task_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>processor_set</var>
+<dd>
+[in processor-set-control send right]
+A processor set control port for
+which information is desired.
+<dt> <var>task_list</var>
+<dd>
+[out pointer to dynamic array of task send rights]
+The returned set of
+ports naming the tasks currently assigned to <var>processor_set</var>.
+<dt> <var>task_count</var>
+<dd>
+[out scalar]
+The number of tasks returned in <var>task_list</var>.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_set_tasks</strong> function returns send rights
+to the kernel ports for each task currently assigned to <var>processor_set</var>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_set_threads.html">processor_set_threads</a>,
+<a href="task_assign.html">task_assign</a>,
+<a href="thread_assign.html">thread_assign</a>.
-<h2>processor_set_threads</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return a list of pointers to all threads currently assigned to the target processor set.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t processor_set_threads</strong>
\r <strong>(processor_set_t</strong> <var>processor_set</var>,
\r <strong>thread_port_array_t</strong> <var>thread_list</var>,
\r <strong>mach_msg_type_number_t*</strong> <var>thread_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>processor_set</var>
\r<dd>
\r[in processor-set-control send right]
\rA processor set control port for
\rwhich information is desired.
\r<dt> <var>thread_list</var>
\r<dd>
\r[out pointer to dynamic array of thread send rights]
\rThe returned set of
\rports naming the threads currently assigned to <var>processor_set</var>.
\r<dt> <var>thread_count</var>
\r<dd>
\r[out scalar]
\rThe number of threads returned in <var>thread_list</var>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_set_threads</strong> function returns send rights
\rto the kernel ports for each thread currently assigned to <var>processor_set</var>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_set_tasks.html">processor_set_tasks</a>,
\r<a href="task_assign.html">task_assign</a>,
\r<a href="thread_assign.html">thread_assign</a>.
\r\ No newline at end of file
+<h2>processor_set_threads</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return a list of pointers to all threads currently assigned to the target processor set.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t processor_set_threads</strong>
+ <strong>(processor_set_t</strong> <var>processor_set</var>,
+ <strong>thread_port_array_t</strong> <var>thread_list</var>,
+ <strong>mach_msg_type_number_t*</strong> <var>thread_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>processor_set</var>
+<dd>
+[in processor-set-control send right]
+A processor set control port for
+which information is desired.
+<dt> <var>thread_list</var>
+<dd>
+[out pointer to dynamic array of thread send rights]
+The returned set of
+ports naming the threads currently assigned to <var>processor_set</var>.
+<dt> <var>thread_count</var>
+<dd>
+[out scalar]
+The number of threads returned in <var>thread_list</var>.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_set_threads</strong> function returns send rights
+to the kernel ports for each thread currently assigned to <var>processor_set</var>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_set_tasks.html">processor_set_tasks</a>,
+<a href="task_assign.html">task_assign</a>,
+<a href="thread_assign.html">thread_assign</a>.
-<h2>processor_start</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Start a processor.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<mach/mach_host.h></strong>
\r\r<strong>kern_return_t processor_start</strong>
\r <strong>(processor_t</strong> <var>processor</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>processor</var>
\r<dd>
\r[in processor send right]
\rThe processor to be controlled.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>processor_start</strong> function allows privileged software
\rto start a processor in
\ra multi-processor that so allows it. A newly started processor
\ris assigned to the
\rdefault processor set. The interpretation of this operation
\ris machine dependent.
\r<h3>NOTES</h3>
\r<p>
\rThis operation is machine dependent. It may do nothing.
\r<h3>CAUTIONS</h3>
\r<p>
\rThe ability to restart an exited processor is machine dependent.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<dt> <strong>KERN_FAILURE</strong>
\r<dd>
\rThe operation was not performed. A likely reason is that it
\ris not supported on this processor.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="processor_control.html">processor_control</a>,
\r<a href="processor_exit.html">processor_exit</a>,
\r<a href="processor_info.html">processor_info</a>,
\r<a href="host_processors.html">host_processors</a>.
\r\ No newline at end of file
+<h2>processor_start</h2>
+<hr>
+<p>
+<strong>Function</strong> - Start a processor.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<mach/mach_host.h></strong>
+
+<strong>kern_return_t processor_start</strong>
+ <strong>(processor_t</strong> <var>processor</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>processor</var>
+<dd>
+[in processor send right]
+The processor to be controlled.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>processor_start</strong> function allows privileged software
+to start a processor in
+a multi-processor that so allows it. A newly started processor
+is assigned to the
+default processor set. The interpretation of this operation
+is machine dependent.
+<h3>NOTES</h3>
+<p>
+This operation is machine dependent. It may do nothing.
+<h3>CAUTIONS</h3>
+<p>
+The ability to restart an exited processor is machine dependent.
+<h3>RETURN VALUES</h3>
+<dl>
+<dt> <strong>KERN_FAILURE</strong>
+<dd>
+The operation was not performed. A likely reason is that it
+is not supported on this processor.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="processor_control.html">processor_control</a>,
+<a href="processor_exit.html">processor_exit</a>,
+<a href="processor_info.html">processor_info</a>,
+<a href="host_processors.html">host_processors</a>.
-<h2>prof_server</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Handle the next kernel-generated PC sample message.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>boolean_t prof_server</strong>
\r <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
\r <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>in_msg</var>
\r<dd>
\r[pointer to in structure]
\rThe sample message received from the kernel.
\r<p>
\r<dt> <var>out_msg</var>
\r<dd>
\r[out structure]
\rNot used.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>prof_server</strong> function is the MIG generated server
\rhandling function to
\rhandle messages from the kernel corresponding to program counter (profiling)
\rsamples. Such messages are delivered to the task or thread sample port set by
\r<strong>task_sample</strong> or <strong>thread_sample</strong>. The <strong>prof_server</strong>
\rfunction performs all
\rnecessary argument handling for this kernel message and calls the appropriate
\rhandling function. These functions must be supplied by the caller.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>TRUE</strong>
\r<dd>
\rThe message was handled and the appropriate function was called.
\r<p>
\r<dt> <strong>FALSE</strong>
\r<dd>
\rThe message did not apply to the sample mechanism and no other
\raction was taken.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="receive_samples.html"><strong>receive_samples<strong></a>.
\r\ No newline at end of file
+<h2>prof_server</h2>
+<hr>
+<p>
+<strong>Function</strong> - Handle the next kernel-generated PC sample message.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>boolean_t prof_server</strong>
+ <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
+ <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>in_msg</var>
+<dd>
+[pointer to in structure]
+The sample message received from the kernel.
+<p>
+<dt> <var>out_msg</var>
+<dd>
+[out structure]
+Not used.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>prof_server</strong> function is the MIG generated server
+handling function to
+handle messages from the kernel corresponding to program counter (profiling)
+samples. Such messages are delivered to the task or thread sample port set by
+<strong>task_sample</strong> or <strong>thread_sample</strong>. The <strong>prof_server</strong>
+function performs all
+necessary argument handling for this kernel message and calls the appropriate
+handling function. These functions must be supplied by the caller.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>TRUE</strong>
+<dd>
+The message was handled and the appropriate function was called.
+<p>
+<dt> <strong>FALSE</strong>
+<dd>
+The message did not apply to the sample mechanism and no other
+action was taken.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="receive_samples.html"><strong>receive_samples<strong></a>.
-<h2>receive_samples</h2>
\r<p>
\rServer Interface - Handles the occurrence of a PC sampling message
\r\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t receive_samples</strong>
\r <strong>(mach_port_t</strong> <var>sample_port</var>,
\r <strong>sample_array_t</strong> <var>samples</var>,
\r <strong>mach_msg_type_number_t</strong> <var>sample_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>sample_port</var>
\r<dd>
\r[in sample (receive) right] The port to which the sample message was
\rsent.
\r\r<dt> <var>samples</var>
\r<dd>
\r[pointer to in array of vm_address_t] An array of PC sample values.
\r\r<dt> <var>sample_count</var>
\r<dd>
\r[in scalar] The number of values in samples.
\r</dl>
\r\r<h3>DESCRIPTION</h3>
\r<p>
\rA <strong>receive_samples</strong> function is called by
\r<strong>prof_server</strong> as the result of a kernel
\rmessage indicating that a set of program counter samples has been gathered.
\rThe parameter <var>sample_port</var> specifies the port named via
\ra previous call to <strong>task_sample</strong>
\ror <strong>thread_sample</strong>.
\r\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the virtual addresses
\rin the <var>samples</var> parameter.
\r\r<h3>RETURN VALUE</h3>
\r<p>
\rIrrelevant.
\r\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_sample.html"><strong>task_sample</strong></a>,
\r<a href="thread_sample.html"><strong>thread_sample</strong></a>,
\r<a href="prof_server.html"><strong>prof_server</strong></a>.
\r\ No newline at end of file
+<h2>receive_samples</h2>
+<p>
+Server Interface - Handles the occurrence of a PC sampling message
+
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t receive_samples</strong>
+ <strong>(mach_port_t</strong> <var>sample_port</var>,
+ <strong>sample_array_t</strong> <var>samples</var>,
+ <strong>mach_msg_type_number_t</strong> <var>sample_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>sample_port</var>
+<dd>
+[in sample (receive) right] The port to which the sample message was
+sent.
+
+<dt> <var>samples</var>
+<dd>
+[pointer to in array of vm_address_t] An array of PC sample values.
+
+<dt> <var>sample_count</var>
+<dd>
+[in scalar] The number of values in samples.
+</dl>
+
+<h3>DESCRIPTION</h3>
+<p>
+A <strong>receive_samples</strong> function is called by
+<strong>prof_server</strong> as the result of a kernel
+message indicating that a set of program counter samples has been gathered.
+The parameter <var>sample_port</var> specifies the port named via
+a previous call to <strong>task_sample</strong>
+or <strong>thread_sample</strong>.
+
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the virtual addresses
+in the <var>samples</var> parameter.
+
+<h3>RETURN VALUE</h3>
+<p>
+Irrelevant.
+
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_sample.html"><strong>task_sample</strong></a>,
+<a href="thread_sample.html"><strong>thread_sample</strong></a>,
+<a href="prof_server.html"><strong>prof_server</strong></a>.
-<h2>semaphore_create</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Create a new semaphore.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t semaphore_create</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>semaphore_t</strong> <var>*semaphore</var>,
\r <strong>int</strong> <var>policy</var>,
\r <strong>int</strong> <var>value</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>task</var>
\r<dd>
\r[in task port] The task receiving the send right of the newly created semaphore.
\r<p>
\r<dt> <var>semaphore</var>
\r<dd>
\r[out send right] The port naming the created semaphore.
\r<p>
\r<dt> <var>policy</var>
\r<dd>
\r[in scalar] The blocked thread wakeup policy for the newly created semaphore. Valid policies are:
\r<dl>
\r<p>
\r <dt> SYNC_POLICY_FIFO
\r<dd>
\ra first-in-first-out policy for scheduling thread wakeup.
\r <p>
\r <dt> SYNC_POLICY_FIXED_PRIORITY
\r<dd>
\ra fixed priority policy for scheduling thread wakeup.
\r </dl>
\r <p>
\r<dt> <var>value</var>
\r<dd>
\r[in scalar] The initial value of the semaphore count.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>semaphore_create</strong> function creates a new semaphore, associates the
\rcreated semaphore with the specified task, and returns a send right
\rnaming the new semaphore. In order to support a robust
\rproducer/consumer communication service, Interrupt Service Routines
\r(ISR) must be able to signal semaphores. The semaphore synchronizer
\rservice is designed to allow user-level device drivers to perform
\rsignal operations, eliminating the need for event counters. Device
\rdrivers which utilize semaphores are responsible for creating (via
\r<strong>semaphore_create</strong>) and exporting (via <strong>device_get_status</strong>)
\rsemaphores for
\ruser level access. Device driver semaphore creation is done at device
\rinitialization time. Device drivers may support multiple semaphores.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r <p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe task argument or the policy argument was invalid,
\r or the initial value of the semaphore was invalid.
\r <p>
\r<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
\r<dd>
\rThe kernel could not allocate the semaphore.
\r <p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe semaphore was successfully created.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>,
\r<a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>,
\r<a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>,
\r<a href="semaphore_wait.html"><strong>semaphore_wait</strong></a>,
\r<a href="device_get_status.html"><strong>device_get_status</strong></a>.
\r\ No newline at end of file
+<h2>semaphore_create</h2>
+<hr>
+<p>
+<strong>Function</strong> - Create a new semaphore.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t semaphore_create</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>semaphore_t</strong> <var>*semaphore</var>,
+ <strong>int</strong> <var>policy</var>,
+ <strong>int</strong> <var>value</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>task</var>
+<dd>
+[in task port] The task receiving the send right of the newly created semaphore.
+<p>
+<dt> <var>semaphore</var>
+<dd>
+[out send right] The port naming the created semaphore.
+<p>
+<dt> <var>policy</var>
+<dd>
+[in scalar] The blocked thread wakeup policy for the newly created semaphore. Valid policies are:
+<dl>
+<p>
+ <dt> SYNC_POLICY_FIFO
+<dd>
+a first-in-first-out policy for scheduling thread wakeup.
+ <p>
+ <dt> SYNC_POLICY_FIXED_PRIORITY
+<dd>
+a fixed priority policy for scheduling thread wakeup.
+ </dl>
+ <p>
+<dt> <var>value</var>
+<dd>
+[in scalar] The initial value of the semaphore count.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>semaphore_create</strong> function creates a new semaphore, associates the
+created semaphore with the specified task, and returns a send right
+naming the new semaphore. In order to support a robust
+producer/consumer communication service, Interrupt Service Routines
+(ISR) must be able to signal semaphores. The semaphore synchronizer
+service is designed to allow user-level device drivers to perform
+signal operations, eliminating the need for event counters. Device
+drivers which utilize semaphores are responsible for creating (via
+<strong>semaphore_create</strong>) and exporting (via <strong>device_get_status</strong>)
+semaphores for
+user level access. Device driver semaphore creation is done at device
+initialization time. Device drivers may support multiple semaphores.
+<h3>RETURN VALUES</h3>
+<dl>
+ <p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The task argument or the policy argument was invalid,
+ or the initial value of the semaphore was invalid.
+ <p>
+<dt> <strong>KERN_RESOURCE_SHORTAGE</strong>
+<dd>
+The kernel could not allocate the semaphore.
+ <p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The semaphore was successfully created.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>,
+<a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>,
+<a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>,
+<a href="semaphore_wait.html"><strong>semaphore_wait</strong></a>,
+<a href="device_get_status.html"><strong>device_get_status</strong></a>.
-<h2>semaphore_destroy</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Destroy a semaphore.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t semaphore_destroy</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>semaphore_t</strong> <var>semaphore</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task port] The task associated with the target semaphore.
\r<p>
\r<dt> <var>semaphore</var>
\r<dd>
\r[in send right] The port naming the semaphore to be destroyed.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>semaphore_destroy</strong> function destroys a semaphore.
\rAll send rights
\rnaming the semaphore become dead names. Threads waiting on the
\rsemaphore become unblocked with the return from the
\r<strong>semaphore_wait</strong>
\rcall indicating that the semaphore was destroyed. A call to
\r<strong>semaphore_destroy</strong> succeeds only if the semaphore is associated
\rwith the specified task.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rEither, or both, the task or semaphore arguments were invalid.
\r<p>
\r<dt> <strong>KERN_INVALID_RIGHT</strong>
\r<dd>
\rThe specified task does not own the specified semaphore.
\r<p>
\r<dt> <strong>KERN_TERMINATED</strong>
\r<dd>
\rThe specified semaphore was previously destroyed.
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe semaphore was destroyed.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="semaphore_create.html"><strong>semaphore_create</strong></a>,
\r<a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>,
\r<a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>,
\r<a href="semaphore_wait.html"><strong>semaphore_wait</strong></a>,
\r<a href="device_get_status.html"><strong>device_get_status</strong></a>.
\r\ No newline at end of file
+<h2>semaphore_destroy</h2>
+<hr>
+<p>
+<strong>Function</strong> - Destroy a semaphore.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t semaphore_destroy</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>semaphore_t</strong> <var>semaphore</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task port] The task associated with the target semaphore.
+<p>
+<dt> <var>semaphore</var>
+<dd>
+[in send right] The port naming the semaphore to be destroyed.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>semaphore_destroy</strong> function destroys a semaphore.
+All send rights
+naming the semaphore become dead names. Threads waiting on the
+semaphore become unblocked with the return from the
+<strong>semaphore_wait</strong>
+call indicating that the semaphore was destroyed. A call to
+<strong>semaphore_destroy</strong> succeeds only if the semaphore is associated
+with the specified task.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+Either, or both, the task or semaphore arguments were invalid.
+<p>
+<dt> <strong>KERN_INVALID_RIGHT</strong>
+<dd>
+The specified task does not own the specified semaphore.
+<p>
+<dt> <strong>KERN_TERMINATED</strong>
+<dd>
+The specified semaphore was previously destroyed.
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The semaphore was destroyed.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="semaphore_create.html"><strong>semaphore_create</strong></a>,
+<a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>,
+<a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>,
+<a href="semaphore_wait.html"><strong>semaphore_wait</strong></a>,
+<a href="device_get_status.html"><strong>device_get_status</strong></a>.
-<h2>semaphore_signal</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Increments the semaphore count.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t semaphore_signal</strong>
\r <strong>(semaphore_t</strong> <var>semaphore</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>semaphore</var>
\r<dd>
\r[in send right] The port naming the semaphore to be signalled.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>semaphore_signal</strong> function increments the semaphore count. If the
\rcount goes non-negative (i.e. greater than or equal to 0) and a thread
\ris blocked on the semaphore, then the waiting thread is scheduled to
\rexecute. If multiple threads are blocked on the semaphore, the thread
\rscheduled to execute is selected according to the wakeup policy of the
\rsemaphore (set when the semaphore was created via <strong>semaphore_create</strong>).
\rDevice driver interrupt service routines may safely execute
\r<strong>semaphore_signal</strong> operations without causing a deadlock.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe specified semaphore is invalid.
\r<p>
\r<dt> <strong>KERN_TERMINATED</strong>
\r<dd>
\rThe specified semaphore has been destroyed.
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe semaphore has been signalled.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="semaphore_create.html"><strong>semaphore_create</strong></a>,
\r<a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>,
\r<a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>,
\r<a href="semaphore_wait.html"><strong>semaphore_wait</strong></a>,
\r<a href="device_get_status.html"><strong>device_get_status</strong></a>.
\r\ No newline at end of file
+<h2>semaphore_signal</h2>
+<hr>
+<p>
+<strong>Function</strong> - Increments the semaphore count.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t semaphore_signal</strong>
+ <strong>(semaphore_t</strong> <var>semaphore</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>semaphore</var>
+<dd>
+[in send right] The port naming the semaphore to be signalled.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>semaphore_signal</strong> function increments the semaphore count. If the
+count goes non-negative (i.e. greater than or equal to 0) and a thread
+is blocked on the semaphore, then the waiting thread is scheduled to
+execute. If multiple threads are blocked on the semaphore, the thread
+scheduled to execute is selected according to the wakeup policy of the
+semaphore (set when the semaphore was created via <strong>semaphore_create</strong>).
+Device driver interrupt service routines may safely execute
+<strong>semaphore_signal</strong> operations without causing a deadlock.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The specified semaphore is invalid.
+<p>
+<dt> <strong>KERN_TERMINATED</strong>
+<dd>
+The specified semaphore has been destroyed.
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The semaphore has been signalled.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="semaphore_create.html"><strong>semaphore_create</strong></a>,
+<a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>,
+<a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>,
+<a href="semaphore_wait.html"><strong>semaphore_wait</strong></a>,
+<a href="device_get_status.html"><strong>device_get_status</strong></a>.
-<h2>semaphore_signal_all</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Wake up all threads blocked on a semaphore.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t semaphore_signal_all</strong>
\r <strong>(semaphore_t</strong> <var>semaphore</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>semaphore</var>
\r<dd>
\r[in send right] The port naming the semaphore to be signalled.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>semaphore_signal_all</strong> function wakes up all of the
\rthreads blocked on the semaphore. The semaphore count is reset to
\rzero.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe specified semaphore is invalid.
\r<p>
\r<dt> <strong>KERN_TERMINATED</strong>
\r<dd>
\rThe specified semaphore has been destroyed.
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe semaphore has been signalled.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="semaphore_create.html"><strong>semaphore_create</strong></a>,
\r<a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>,
\r<a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>,
\r\ No newline at end of file
+<h2>semaphore_signal_all</h2>
+<hr>
+<p>
+<strong>Function</strong> - Wake up all threads blocked on a semaphore.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t semaphore_signal_all</strong>
+ <strong>(semaphore_t</strong> <var>semaphore</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>semaphore</var>
+<dd>
+[in send right] The port naming the semaphore to be signalled.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>semaphore_signal_all</strong> function wakes up all of the
+threads blocked on the semaphore. The semaphore count is reset to
+zero.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The specified semaphore is invalid.
+<p>
+<dt> <strong>KERN_TERMINATED</strong>
+<dd>
+The specified semaphore has been destroyed.
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The semaphore has been signalled.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="semaphore_create.html"><strong>semaphore_create</strong></a>,
+<a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>,
+<a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>,
-<h2>semaphore_wait</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Wait on the specified semaphore.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t semaphore_wait</strong>
\r <strong>(semaphore_t</strong> <var>semaphore</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>semaphore</var>
\r<dd>
\r[in send right] The port naming the semaphore that the wait operation is being performed upon.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>semaphore_wait</strong> function decrements the semaphore count. If the
\rsemaphore count is negative after decrementing, the calling thread
\rblocks. Device driver interrupt service routines (ISR) should never
\rexecute <strong>semaphore_wait</strong>, since waiting on a semaphore at the ISR level
\rmay, and often will, lead to a deadlock.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\rThe specified semaphore is invalid.
\r<p>
\r<dt> <strong>KERN_TERMINATED</strong>
\r<dd>
\rThe specified semaphore has been destroyed.
\r<p>
\r<dt> <strong>KERN_ABORTED</strong>
\r<dd>
\rThe caller was blocked due to a negative count on the semaphore, and was
\r awoken for a reason not related to the semaphore subsystem
\r (e.g. <strong>thread_terminate</strong>).
\r<p>
\r<dt> <strong>KERN_SUCCESS</strong>
\r<dd>
\rThe semaphore wait operation was successful.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="semaphore_create.html"><strong>semaphore_create</strong></a>,
\r<a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>,
\r<a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>,
\r<a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>,
\r<a href="device_get_status.html"><strong>device_get_status</strong></a>.
\r\ No newline at end of file
+<h2>semaphore_wait</h2>
+<hr>
+<p>
+<strong>Function</strong> - Wait on the specified semaphore.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t semaphore_wait</strong>
+ <strong>(semaphore_t</strong> <var>semaphore</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>semaphore</var>
+<dd>
+[in send right] The port naming the semaphore that the wait operation is being performed upon.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>semaphore_wait</strong> function decrements the semaphore count. If the
+semaphore count is negative after decrementing, the calling thread
+blocks. Device driver interrupt service routines (ISR) should never
+execute <strong>semaphore_wait</strong>, since waiting on a semaphore at the ISR level
+may, and often will, lead to a deadlock.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+The specified semaphore is invalid.
+<p>
+<dt> <strong>KERN_TERMINATED</strong>
+<dd>
+The specified semaphore has been destroyed.
+<p>
+<dt> <strong>KERN_ABORTED</strong>
+<dd>
+The caller was blocked due to a negative count on the semaphore, and was
+ awoken for a reason not related to the semaphore subsystem
+ (e.g. <strong>thread_terminate</strong>).
+<p>
+<dt> <strong>KERN_SUCCESS</strong>
+<dd>
+The semaphore wait operation was successful.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="semaphore_create.html"><strong>semaphore_create</strong></a>,
+<a href="semaphore_destroy.html"><strong>semaphore_destroy</strong></a>,
+<a href="semaphore_signal.html"><strong>semaphore_signal</strong></a>,
+<a href="semaphore_signal_all.html"><strong>semaphore_signal_all</strong></a>,
+<a href="device_get_status.html"><strong>device_get_status</strong></a>.
-<h2>seqnos_notify_server</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Handle the next kernel-generated IPC notification.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>boolean_t seqnos_notify_server</strong>
\r <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
\r <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>in_msg</var>
\r<dd>
\r[pointer to in structure]
\rThe notification message received from the
\rkernel.
\r<p>
\r<dt> <var>out_msg</var>
\r<dd>
\r[out structure]
\rNot used.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>seqnos_notify_server</strong> function is the MIG generated server handling
\rfunction to handle messages from the kernel corresponding to IPC notifications.
\rSuch messages are delivered to the notification port named in a
\r<strong>mach_msg</strong> or <strong>mach_port_request_notification</strong> call.
\rThe <strong>seqnos_notify_server</strong> function
\rperforms all necessary argument handling for this kernel message and calls the
\rappropriate handling function. These functions must be supplied by the caller.
\r<h3>NOTES</h3>
\r<p>
\r<strong>seqnos_notify_server</strong> differs from <strong>notify_server</strong>
\rin that it supplies message
\rsequence numbers to the server interfaces.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>TRUE</strong>
\r<dd>
\rThe message was handled and the appropriate function was called.
\r<p>
\r<dt> <strong>FALSE</strong>
\r<dd>
\rThe message did not apply to the notification mechanism and no other
\raction was taken.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="notify_server.html"><strong>notify_server<strong></a>,
\r<a href="do_mach_notify_dead_name.html"><strong>do_seqnos_mach_notify_dead_name<strong></a>,
\r<a href="do_mach_notify_no_senders.html"><strong>do_seqnos_mach_notify_no_senders<strong></a>,
\r<a href="DMN_port_deleted.html"><strong>do_seqnos_mach_notify_port_deleted<strong></a>,
\r<a href="do_mach_notify_send_once.html"><strong>do_seqnos_mach_notify_send_once<strong></a>.
\r\ No newline at end of file
+<h2>seqnos_notify_server</h2>
+<hr>
+<p>
+<strong>Function</strong> - Handle the next kernel-generated IPC notification.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>boolean_t seqnos_notify_server</strong>
+ <strong>(mach_msg_header_t</strong> <var>request_msg</var>,
+ <strong>mach_msg_header_t</strong> <var>reply_ms</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>in_msg</var>
+<dd>
+[pointer to in structure]
+The notification message received from the
+kernel.
+<p>
+<dt> <var>out_msg</var>
+<dd>
+[out structure]
+Not used.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>seqnos_notify_server</strong> function is the MIG generated server handling
+function to handle messages from the kernel corresponding to IPC notifications.
+Such messages are delivered to the notification port named in a
+<strong>mach_msg</strong> or <strong>mach_port_request_notification</strong> call.
+The <strong>seqnos_notify_server</strong> function
+performs all necessary argument handling for this kernel message and calls the
+appropriate handling function. These functions must be supplied by the caller.
+<h3>NOTES</h3>
+<p>
+<strong>seqnos_notify_server</strong> differs from <strong>notify_server</strong>
+in that it supplies message
+sequence numbers to the server interfaces.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>TRUE</strong>
+<dd>
+The message was handled and the appropriate function was called.
+<p>
+<dt> <strong>FALSE</strong>
+<dd>
+The message did not apply to the notification mechanism and no other
+action was taken.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="notify_server.html"><strong>notify_server<strong></a>,
+<a href="do_mach_notify_dead_name.html"><strong>do_seqnos_mach_notify_dead_name<strong></a>,
+<a href="do_mach_notify_no_senders.html"><strong>do_seqnos_mach_notify_no_senders<strong></a>,
+<a href="DMN_port_deleted.html"><strong>do_seqnos_mach_notify_port_deleted<strong></a>,
+<a href="do_mach_notify_send_once.html"><strong>do_seqnos_mach_notify_send_once<strong></a>.
-<h2>task_assign</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Assign a task to a processor set.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_assign</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>processor_set_t</strong> <var>processor_set</var>,
\r <strong>boolean_t</strong> <var>assign_threads</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe port for the task to be assigned.
\r<dt> <var>processor_set</var>
\r<dd>
\r[in processor-set-control send right]
\rThe control port for the processor
\rset into which the task is to be assigned.
\r<dt> <var>assign_threads</var>
\r<dd>
\r[in scalar]
\rTrue if this assignment should apply as well to the threads
\rwithin the task.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_assign</strong> function assigns <var>task</var> to the set
\r<var>processor_set</var>.
\rAfter the assignment is completed, newly created threads within this task
\rwill be assigned to
\rthis processor set. Any previous assignment of the task is nullified.
\r<p>
\rIf <var>assign_threads</var> is <strong>TRUE</strong>, existing threads within the task
\rwill also be assigned to the processor set.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_assign_default.html"><strong>task_assign_default</strong></a>,
\r<a href="task_get_assignment.html"><strong>task_get_assignment</strong></a>,
\r<a href="processor_set_create.html"><strong>processor_set_create</strong></a>,
\r<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
\r<a href="thread_assign.html"><strong>thread_assign</strong></a>.
\r\ No newline at end of file
+<h2>task_assign</h2>
+<hr>
+<p>
+<strong>Function</strong> - Assign a task to a processor set.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_assign</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>processor_set_t</strong> <var>processor_set</var>,
+ <strong>boolean_t</strong> <var>assign_threads</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The port for the task to be assigned.
+<dt> <var>processor_set</var>
+<dd>
+[in processor-set-control send right]
+The control port for the processor
+set into which the task is to be assigned.
+<dt> <var>assign_threads</var>
+<dd>
+[in scalar]
+True if this assignment should apply as well to the threads
+within the task.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_assign</strong> function assigns <var>task</var> to the set
+<var>processor_set</var>.
+After the assignment is completed, newly created threads within this task
+will be assigned to
+this processor set. Any previous assignment of the task is nullified.
+<p>
+If <var>assign_threads</var> is <strong>TRUE</strong>, existing threads within the task
+will also be assigned to the processor set.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_assign_default.html"><strong>task_assign_default</strong></a>,
+<a href="task_get_assignment.html"><strong>task_get_assignment</strong></a>,
+<a href="processor_set_create.html"><strong>processor_set_create</strong></a>,
+<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
+<a href="thread_assign.html"><strong>thread_assign</strong></a>.
-<h2>task_assign_default</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Assign a task to the default processor set.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_assign_default</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>boolean_t</strong> <var>assign_threads</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe port for the task to be assigned.
\r<dt> <var>assign_threads</var>
\r<dd>
\r[in scalar]
\rTrue if this assignment should apply as well to the threads
\rwithin the task.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_assign_default</strong> function assigns <var>task</var> to the
\rdefault processor set.
\rAfter the assignment is completed, newly created threads within
\rthis task will be
\rassigned to this processor set. Any previous assignment of the
\rtask is nullified.
\r<p>
\rIf <var>assign_threads</var> is <strong>TRUE</strong>, existing threads within the
\rtask will also be assigned to the processor set.
\r<h3>NOTES</h3>
\r<p>
\rThis variant of <strong>task_assign</strong> exists because the control
\rport for the default
\rprocessor set is privileged, and therefore not available to most tasks.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_assign.html"><strong>task_assign</strong></a>,
\r<a href="task_get_assignment.html"><strong>task_get_assignment</strong></a>,
\r<a href="processor_set_create.html"><strong>processor_set_create</strong></a>,
\r<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
\r<a href="thread_assign.html"><strong>thread_assign</strong></a>.
\r\ No newline at end of file
+<h2>task_assign_default</h2>
+<hr>
+<p>
+<strong>Function</strong> - Assign a task to the default processor set.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_assign_default</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>boolean_t</strong> <var>assign_threads</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The port for the task to be assigned.
+<dt> <var>assign_threads</var>
+<dd>
+[in scalar]
+True if this assignment should apply as well to the threads
+within the task.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_assign_default</strong> function assigns <var>task</var> to the
+default processor set.
+After the assignment is completed, newly created threads within
+this task will be
+assigned to this processor set. Any previous assignment of the
+task is nullified.
+<p>
+If <var>assign_threads</var> is <strong>TRUE</strong>, existing threads within the
+task will also be assigned to the processor set.
+<h3>NOTES</h3>
+<p>
+This variant of <strong>task_assign</strong> exists because the control
+port for the default
+processor set is privileged, and therefore not available to most tasks.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_assign.html"><strong>task_assign</strong></a>,
+<a href="task_get_assignment.html"><strong>task_get_assignment</strong></a>,
+<a href="processor_set_create.html"><strong>processor_set_create</strong></a>,
+<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
+<a href="thread_assign.html"><strong>thread_assign</strong></a>.
-<h2>task_basic_info</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Defines basic information for a task.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct task_basic_info</strong>
\r<strong>{</strong>
\r <strong>integer_t</strong> <var>suspend_count</var><strong>;</strong>
\r <strong>vm_size_t</strong> <var>virtual_size</var><strong>;</strong>
\r <strong>vm_size_t</strong> <var>resident_size</var><strong>;</strong>
\r <strong>time_value_t</strong> <var>user_time</var><strong>;</strong>
\r <strong>time_value_t</strong> <var>system_time</var><strong>;</strong>
\r <strong>policy_t</strong> <var>policy</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct task_basic_info* task_basic_info_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>suspend_count</var>
\r<dd>
\rThe current suspend count for the task.
\r <p>
\r<dt> <var>virtual_size</var>
\r<dd>
\rThe number of virtual pages for the task.
\r <p>
\r<dt> <var>resident_size</var>
\r<dd>
\rThe number of resident pages for the task
\r <p>
\r<dt> <var>user_time</var>
\r<dd>
\rThe total user run time for terminated threads within the task.
\r <p>
\r<dt> <var>system_time</var>
\r<dd>
\rThe total system run time for terminated threads within the task.
\r <p>
\r<dt> <var>policy</var>
\r<dd>
\rDefault scheduling policy to apply to new threads.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_basic_info</strong> structure defines the basic information array for
\rtasks. The <strong>task_info</strong> function returns this array for a specified task.
\r<h3>NOTES</h3>
\r<p>
\rThis structure is machine word length sensitive due
\rto the presence of the
\rvirtual address sizes.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_info.html"><strong>task_info</strong></a>.
\r<p>
\rData Structures:
\r<a href="task_thread_times_info.html"><strong>task_thread_times_info</strong></a>,
\r<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
\r<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>,
\r<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>.
\r\ No newline at end of file
+<h2>task_basic_info</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Defines basic information for a task.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct task_basic_info</strong>
+<strong>{</strong>
+ <strong>integer_t</strong> <var>suspend_count</var><strong>;</strong>
+ <strong>vm_size_t</strong> <var>virtual_size</var><strong>;</strong>
+ <strong>vm_size_t</strong> <var>resident_size</var><strong>;</strong>
+ <strong>time_value_t</strong> <var>user_time</var><strong>;</strong>
+ <strong>time_value_t</strong> <var>system_time</var><strong>;</strong>
+ <strong>policy_t</strong> <var>policy</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct task_basic_info* task_basic_info_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>suspend_count</var>
+<dd>
+The current suspend count for the task.
+ <p>
+<dt> <var>virtual_size</var>
+<dd>
+The number of virtual pages for the task.
+ <p>
+<dt> <var>resident_size</var>
+<dd>
+The number of resident pages for the task
+ <p>
+<dt> <var>user_time</var>
+<dd>
+The total user run time for terminated threads within the task.
+ <p>
+<dt> <var>system_time</var>
+<dd>
+The total system run time for terminated threads within the task.
+ <p>
+<dt> <var>policy</var>
+<dd>
+Default scheduling policy to apply to new threads.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_basic_info</strong> structure defines the basic information array for
+tasks. The <strong>task_info</strong> function returns this array for a specified task.
+<h3>NOTES</h3>
+<p>
+This structure is machine word length sensitive due
+to the presence of the
+virtual address sizes.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_info.html"><strong>task_info</strong></a>.
+<p>
+Data Structures:
+<a href="task_thread_times_info.html"><strong>task_thread_times_info</strong></a>,
+<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
+<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>,
+<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>.
-<h2>task_create</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Create a new task.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_create</strong>
\r <strong>(task_t</strong> <var>parent_task</var>,
\r <strong>ledger_port_array_t</strong> <var>ledgers</var>,
\r <strong>int</strong> <var>ledger_count</var>,
\r <strong>boolean_t</strong> <var>inherit_memory</var>,
\r <strong>task_t</strong> <var>child_task</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>parent_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task from which to draw the child
\rtask's port rights and address space.
\r<p>
\r<dt> <var>ledgers</var>
\r<dd>
\r[pointer to in array of ledger send rights]
\rResource ledgers (on the
\rdestination host) from which the task will draw its resources. The first
\relement of this array is the wired kernel ledger, the second the paged
\rspace ledger. If the number of ledgers supplied does not match the
\rrequired number or one or more is null, the parent task's ledger is used.
\r<p>
\r<dt> <var>ledger_count</var>
\r<dd>
\r[in scalar]
\rThe number of ledger ports in the <var>ledgers</var> array.
\r<p>
\r<dt> <var>inherit_memory</var>
\r<dd>
\r[in scalar]
\rAddress space inheritance indicator. If true, the child task
\rinherits the (inheritable) address space of the parent task. If false, the
\rkernel assigns the child task an empty address space.
\r<p>
\r<dt> <var>child_task</var>
\r<dd>
\r[out task send right]
\rThe kernel-assigned port for the new task.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_create</strong> function creates a new task from <var>parent_task</var>
\rand returns the name of the new task in <var>child_task</var>.
\rThe child task acquires shared or copied parts of the parent's address space
\r(see <strong>vm_inherit</strong>). The child task initially
\rcontains no threads. The child task inherits the parent's security ID.
\r<p>
\rThe child task receives the following "special" ports, which are created or
\rcopied for it at task creation:
\r<dl>
\r<dt> [task-self send right]
\r<dd>
\rThe port by which the kernel knows the new child task
\rand allows it to be manipulated. The child task holds a send right for this
\rport. The port name is also returned to the calling task.
\r<p>
\r<dt> [bootstrap send right]
\r<dd>
\rThe port to which the child task can send a message
\rrequesting return of any system service ports that it needs (for
\rexample, a port
\rto the Network Name Server or the Environment Manager). The child task
\rinherits a send right for this port from the parent task. The task can use
\r<strong>task_set_special_port</strong> to change this port.
\r<p>
\r<dt> [host-self send right]
\r<dd>
\rThe port by which the child task requests information
\rabout its host. The child task inherits a send right for this port from the
\rparent task.
\r<p>
\r<dt> [ledger send rights]
\r<dd>
\rThe ports naming the ledgers from which the task draws
\rits resources.
\r</dl>
\r<p>
\rThe child task also inherits the following ports:
\r<dl>
\r<dt> [sample send right]
\r<dd>
\rThe port to which PC sampling messages are to be sent.
\r<p>
\r<dt> [exception send rights]
\r<dd>
\rPorts to which exception messages are sent.
\r<p>
\r<dt> [registered send rights]
\r<dd>
\rPorts to system services.
\r</dl>
\r<h3>NOTES</h3>
\r<p>
\rThe <strong>ledgers</strong> functionality mentioned above is not
\rcurrently implemented.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_create_security_token.html"><strong>task_create_security_token</strong></a>,
\r<a href="task_resume.html"><strong>task_resume</strong></a>,
\r<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>,
\r<a href="task_suspend.html"><strong>task_suspend</strong></a>,
\r<a href="task_terminate.html"><strong>task_terminate</strong></a>,
\r<a href="task_threads.html"><strong>task_threads</strong></a>,
\r<a href="thread_create.html"><strong>thread_create</strong></a>,
\r<a href="thread_resume.html"><strong>thread_resume</strong></a>,
\r<a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
\r<a href="task_sample.html"><strong>task_sample</strong></a>,
\r<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
\r<a href="mach_ports_register.html"><strong>mach_ports_register</strong></a>,
\r<a href="norma_task_create.html"><strong>norma_task_create</strong></a>,
\r<a href="host_security_set_task_token.html"><strong>host_security_set_task_token</strong></a>.
\r\ No newline at end of file
+<h2>task_create</h2>
+<hr>
+<p>
+<strong>Function</strong> - Create a new task.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_create</strong>
+ <strong>(task_t</strong> <var>parent_task</var>,
+ <strong>ledger_port_array_t</strong> <var>ledgers</var>,
+ <strong>int</strong> <var>ledger_count</var>,
+ <strong>boolean_t</strong> <var>inherit_memory</var>,
+ <strong>task_t</strong> <var>child_task</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>parent_task</var>
+<dd>
+[in task send right]
+The port for the task from which to draw the child
+task's port rights and address space.
+<p>
+<dt> <var>ledgers</var>
+<dd>
+[pointer to in array of ledger send rights]
+Resource ledgers (on the
+destination host) from which the task will draw its resources. The first
+element of this array is the wired kernel ledger, the second the paged
+space ledger. If the number of ledgers supplied does not match the
+required number or one or more is null, the parent task's ledger is used.
+<p>
+<dt> <var>ledger_count</var>
+<dd>
+[in scalar]
+The number of ledger ports in the <var>ledgers</var> array.
+<p>
+<dt> <var>inherit_memory</var>
+<dd>
+[in scalar]
+Address space inheritance indicator. If true, the child task
+inherits the (inheritable) address space of the parent task. If false, the
+kernel assigns the child task an empty address space.
+<p>
+<dt> <var>child_task</var>
+<dd>
+[out task send right]
+The kernel-assigned port for the new task.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_create</strong> function creates a new task from <var>parent_task</var>
+and returns the name of the new task in <var>child_task</var>.
+The child task acquires shared or copied parts of the parent's address space
+(see <strong>vm_inherit</strong>). The child task initially
+contains no threads. The child task inherits the parent's security ID.
+<p>
+The child task receives the following "special" ports, which are created or
+copied for it at task creation:
+<dl>
+<dt> [task-self send right]
+<dd>
+The port by which the kernel knows the new child task
+and allows it to be manipulated. The child task holds a send right for this
+port. The port name is also returned to the calling task.
+<p>
+<dt> [bootstrap send right]
+<dd>
+The port to which the child task can send a message
+requesting return of any system service ports that it needs (for
+example, a port
+to the Network Name Server or the Environment Manager). The child task
+inherits a send right for this port from the parent task. The task can use
+<strong>task_set_special_port</strong> to change this port.
+<p>
+<dt> [host-self send right]
+<dd>
+The port by which the child task requests information
+about its host. The child task inherits a send right for this port from the
+parent task.
+<p>
+<dt> [ledger send rights]
+<dd>
+The ports naming the ledgers from which the task draws
+its resources.
+</dl>
+<p>
+The child task also inherits the following ports:
+<dl>
+<dt> [sample send right]
+<dd>
+The port to which PC sampling messages are to be sent.
+<p>
+<dt> [exception send rights]
+<dd>
+Ports to which exception messages are sent.
+<p>
+<dt> [registered send rights]
+<dd>
+Ports to system services.
+</dl>
+<h3>NOTES</h3>
+<p>
+The <strong>ledgers</strong> functionality mentioned above is not
+currently implemented.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_create_security_token.html"><strong>task_create_security_token</strong></a>,
+<a href="task_resume.html"><strong>task_resume</strong></a>,
+<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>,
+<a href="task_suspend.html"><strong>task_suspend</strong></a>,
+<a href="task_terminate.html"><strong>task_terminate</strong></a>,
+<a href="task_threads.html"><strong>task_threads</strong></a>,
+<a href="thread_create.html"><strong>thread_create</strong></a>,
+<a href="thread_resume.html"><strong>thread_resume</strong></a>,
+<a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
+<a href="task_sample.html"><strong>task_sample</strong></a>,
+<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
+<a href="mach_ports_register.html"><strong>mach_ports_register</strong></a>,
+<a href="norma_task_create.html"><strong>norma_task_create</strong></a>,
+<a href="host_security_set_task_token.html"><strong>host_security_set_task_token</strong></a>.
-<h2>task_get_assignment</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return the processor set to which a task is assigned.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_get_assignment</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>processor_set_name_t</strong> <var>processor_set</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe port for the task whose assignment is desired.
\r<dt> <var>processor_set</var>
\r<dd>
\r[out processor-set-name send right]
\rThe name port for the processor
\rset into which the task is assigned.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_get_assignment</strong> function returns the name port
\rto the processor set to
\rwhich <var>task</var> is currently assigned. This port can only be used to obtain
\rinformation about the processor set.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_assign.html"><strong>task_assign</strong></a>,
\r<a href="task_assign_default.html"><strong>task_assign_default</strong></a>,
\r<a href="processor_set_create.html"><strong>processor_set_create</strong></a>,
\r<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
\r<a href="thread_assign.html"><strong>thread_assign</strong></a>.
\r\ No newline at end of file
+<h2>task_get_assignment</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return the processor set to which a task is assigned.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_get_assignment</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>processor_set_name_t</strong> <var>processor_set</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The port for the task whose assignment is desired.
+<dt> <var>processor_set</var>
+<dd>
+[out processor-set-name send right]
+The name port for the processor
+set into which the task is assigned.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_get_assignment</strong> function returns the name port
+to the processor set to
+which <var>task</var> is currently assigned. This port can only be used to obtain
+information about the processor set.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_assign.html"><strong>task_assign</strong></a>,
+<a href="task_assign_default.html"><strong>task_assign_default</strong></a>,
+<a href="processor_set_create.html"><strong>processor_set_create</strong></a>,
+<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
+<a href="thread_assign.html"><strong>thread_assign</strong></a>.
-<h2>task_get_emulation_vector</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return an array identifying the target task's user-level system call handlers.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_get_emulation_vector</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>int</strong> <var>vector_start</var>,
\r <strong>emulation_vector_t</strong> <var>emulation_vector</var>,
\r <strong>mach_msg_type_number_t*</strong> <var>emulation_vector_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe port for the task for which the system call
\rhandler addresses are desired.
\r<p>
\r<dt> <var>vector_start</var>
\r<dd>
\r[out scalar]
\rThe syscall number corresponding to the first element of
\r<var>emulation_vector</var>.
\r<p>
\r<dt> <var>emulation_vector</var>
\r<dd>
\r[out pointer to dynamic array of <strong>vm_address_t</strong>]
\rPointer to the returned
\rarray of routine entrypoints for the system calls starting with syscall
\rnumber <var>vector_start</var>.
\r<p>
\r<dt> <var>emulation_vector_count</var>
\r<dd>
\r[out scalar]
\rThe number of entries filled by the kernel.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_get_emulation_vector</strong> function returns the
\ruser-level syscall handler entrypoint addresses.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the
\rvirtual addresses in the <var>emulation_vector</var> parameter.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_set_emulation_vector.html"><strong>task_set_emulation_vector</strong></a>.
\r\ No newline at end of file
+<h2>task_get_emulation_vector</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return an array identifying the target task's user-level system call handlers.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_get_emulation_vector</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>int</strong> <var>vector_start</var>,
+ <strong>emulation_vector_t</strong> <var>emulation_vector</var>,
+ <strong>mach_msg_type_number_t*</strong> <var>emulation_vector_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The port for the task for which the system call
+handler addresses are desired.
+<p>
+<dt> <var>vector_start</var>
+<dd>
+[out scalar]
+The syscall number corresponding to the first element of
+<var>emulation_vector</var>.
+<p>
+<dt> <var>emulation_vector</var>
+<dd>
+[out pointer to dynamic array of <strong>vm_address_t</strong>]
+Pointer to the returned
+array of routine entrypoints for the system calls starting with syscall
+number <var>vector_start</var>.
+<p>
+<dt> <var>emulation_vector_count</var>
+<dd>
+[out scalar]
+The number of entries filled by the kernel.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_get_emulation_vector</strong> function returns the
+user-level syscall handler entrypoint addresses.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the
+virtual addresses in the <var>emulation_vector</var> parameter.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_set_emulation_vector.html"><strong>task_set_emulation_vector</strong></a>.
-<h2>task_get_exception_ports</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return send rights to the target task's exception ports.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_get_exception_ports</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>exception_mask_t</strong> <var>exception_types</var>,
\r <strong>exception_mask_array_t</strong> <var>old_exception_masks</var>,
\r <strong>old_exception_masks</strong> <var>old_exception_count</var>,
\r <strong>exception_port_array_t</strong> <var>old_exception_ports</var>,
\r <strong>exception_behavior_array_t</strong> <var>old_behaviors</var>,
\r <strong>exception_flavor_array_t</strong> <var>old_flavors</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task for which to return the exception ports.
\r<p>
\r<dt> <var>exception_types</var>
\r<dd>
\r[in scalar]
\rA flag word indicating the types of exceptions for which the
\rexception ports are desired:
\r<dl>
\r<p>
\r<dt> <strong>EXC_MASK_BAD_ACCESS</strong>
\r<dd>
\rCould not access memory.
\r<p>
\r<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
\r<dd>
\rInstruction failed. Illegal or undefined instruction or operand.
\r<p>
\r<dt> <strong>EXC_MASK_ARITHMETIC</strong>
\r<dd>
\rArithmetic exception
\r<p>
\r<dt> <strong>EXC_MASK_EMULATION</strong>
\r<dd>
\rEmulation instruction. Emulation support instruction
\rencountered.
\r<p>
\r<dt> <strong>EXC_MASK_SOFTWARE</strong>
\r<dd>
\rSoftware generated exception.
\r<p>
\r<dt> <strong>EXC_MASK_BREAKPOINT</strong>
\r<dd>
\rTrace, breakpoint, etc.
\r<p>
\r<dt> <strong>EXC_MASK_SYSCALL</strong>
\r<dd>
\rSystem call requested.
\r<p>
\r<dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
\r<dd>
\rSystem call with a number in the Mach call range requested.
\r<p>
\r<dt> <strong>EXC_MASK_RPC_ALERT </strong>
\r<dd>
\rExceptional condition encountered during execution of RPC.
\r</dl>
\r<p>
\r<dt> <var>old_exception_masks</var>
\r<dd>
\r[out array of <var>exception_mask_t</var>]
\rAn array, each element being a mask
\rspecifying for which exception types the corresponding element of the
\rother arrays apply.
\r<p>
\r<dt> <var>old_exception_count</var>
\r<dd>
\r[pointer to in/out scalar]
\rOn input, the maximum size of the array
\rbuffers; on output, the number of returned <exception type mask,
\rexception port, behavior, flavor> sets returned.
\r<p>
\r<dt> <var>old_exception_ports</var>
\r<dd>
\r[out array of exception send rights]
\rThe returned exception ports.
\r<p>
\r<dt> <var>old_behaviors</var>
\r<dd>
\r[out array of <var>exception_behavior_t</var>]
\rThe type of exception message to
\rbe sent. Defined types are:
\r<dl>
\r<p>
\r<dt> <strong>EXCEPTION_DEFAULT</strong>
\r<dd>
\rSend a <strong>catch_exception_raise</strong> message including the thread identity.
\r<p>
\r<dt> <strong>EXCEPTION_STATE</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state</strong> message including the
\rthread state.
\r<p>
\r<dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state_identity</strong> message
\rincluding the thread identity and state.
\r</dl>
\r<p>
\r<dt> <var>old_flavors</var>
\r<dd>
\r[out array of <var>thread_state_flavor_t</var>]
\rThe type of state to be sent with
\rthe exception message. These types are defined in <strong><mach/thread_states.h></strong>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_get_exception_ports</strong> function returns send
\rrights for a specified set
\rof exception ports belonging to task. A task exception port is used when a
\rthread specific exception port returns a non-success reply.
\rThe call returns a set
\rof quadruples <exception type mask, exception port, behavior, flavor> for each
\runique set of <exception port, behavior, flavor> in effect for
\rthe task where the
\rexception type mask indicates for which exception types the other values apply.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_task_self.html"><strong>mach_task_self</strong></a>,
\r<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
\r<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
\r<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
\r<a href="thread_create.html"><strong>thread_create</strong></a>,
\r<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
\r<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
\r<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>.
\r\ No newline at end of file
+<h2>task_get_exception_ports</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return send rights to the target task's exception ports.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_get_exception_ports</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>exception_mask_t</strong> <var>exception_types</var>,
+ <strong>exception_mask_array_t</strong> <var>old_exception_masks</var>,
+ <strong>old_exception_masks</strong> <var>old_exception_count</var>,
+ <strong>exception_port_array_t</strong> <var>old_exception_ports</var>,
+ <strong>exception_behavior_array_t</strong> <var>old_behaviors</var>,
+ <strong>exception_flavor_array_t</strong> <var>old_flavors</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task for which to return the exception ports.
+<p>
+<dt> <var>exception_types</var>
+<dd>
+[in scalar]
+A flag word indicating the types of exceptions for which the
+exception ports are desired:
+<dl>
+<p>
+<dt> <strong>EXC_MASK_BAD_ACCESS</strong>
+<dd>
+Could not access memory.
+<p>
+<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
+<dd>
+Instruction failed. Illegal or undefined instruction or operand.
+<p>
+<dt> <strong>EXC_MASK_ARITHMETIC</strong>
+<dd>
+Arithmetic exception
+<p>
+<dt> <strong>EXC_MASK_EMULATION</strong>
+<dd>
+Emulation instruction. Emulation support instruction
+encountered.
+<p>
+<dt> <strong>EXC_MASK_SOFTWARE</strong>
+<dd>
+Software generated exception.
+<p>
+<dt> <strong>EXC_MASK_BREAKPOINT</strong>
+<dd>
+Trace, breakpoint, etc.
+<p>
+<dt> <strong>EXC_MASK_SYSCALL</strong>
+<dd>
+System call requested.
+<p>
+<dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
+<dd>
+System call with a number in the Mach call range requested.
+<p>
+<dt> <strong>EXC_MASK_RPC_ALERT </strong>
+<dd>
+Exceptional condition encountered during execution of RPC.
+</dl>
+<p>
+<dt> <var>old_exception_masks</var>
+<dd>
+[out array of <var>exception_mask_t</var>]
+An array, each element being a mask
+specifying for which exception types the corresponding element of the
+other arrays apply.
+<p>
+<dt> <var>old_exception_count</var>
+<dd>
+[pointer to in/out scalar]
+On input, the maximum size of the array
+buffers; on output, the number of returned <exception type mask,
+exception port, behavior, flavor> sets returned.
+<p>
+<dt> <var>old_exception_ports</var>
+<dd>
+[out array of exception send rights]
+The returned exception ports.
+<p>
+<dt> <var>old_behaviors</var>
+<dd>
+[out array of <var>exception_behavior_t</var>]
+The type of exception message to
+be sent. Defined types are:
+<dl>
+<p>
+<dt> <strong>EXCEPTION_DEFAULT</strong>
+<dd>
+Send a <strong>catch_exception_raise</strong> message including the thread identity.
+<p>
+<dt> <strong>EXCEPTION_STATE</strong>
+<dd>
+Send a <strong>catch_exception_raise_state</strong> message including the
+thread state.
+<p>
+<dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
+<dd>
+Send a <strong>catch_exception_raise_state_identity</strong> message
+including the thread identity and state.
+</dl>
+<p>
+<dt> <var>old_flavors</var>
+<dd>
+[out array of <var>thread_state_flavor_t</var>]
+The type of state to be sent with
+the exception message. These types are defined in <strong><mach/thread_states.h></strong>.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_get_exception_ports</strong> function returns send
+rights for a specified set
+of exception ports belonging to task. A task exception port is used when a
+thread specific exception port returns a non-success reply.
+The call returns a set
+of quadruples <exception type mask, exception port, behavior, flavor> for each
+unique set of <exception port, behavior, flavor> in effect for
+the task where the
+exception type mask indicates for which exception types the other values apply.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_task_self.html"><strong>mach_task_self</strong></a>,
+<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
+<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
+<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
+<a href="thread_create.html"><strong>thread_create</strong></a>,
+<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
+<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
+<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>.
-<h2>task_get_special_port</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return a send write to the indicated special port.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_get_special_port</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>int</strong> <var>which_port</var>,
\r <strong>task</strong> <var>special_port</var><strong>);</strong>
\r\r\r<strong>Macro Forms:</strong>
\r\r\r<strong>kern_return_t task_get_bootstrap_port</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>task</strong> <var>special_port</var><strong>);</strong>
\r\r\r<strong>kern_return_t task_get_kernel_port</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>task</strong> <var>special_port</var><strong>);</strong>
\r\r\r<strong>kern_return_t task_get_host_name_port</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>task</strong> <var>special_port</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe port for the task for which to return the port's
\rsend right.
\r<p>
\r<dt> <var>which_port</var>
\r<dd>
\r[in scalar]
\rThe special port for which the send right is requested. Valid
\rvalues are:
\r<dl>
\r<p>
\r<dt> <strong>TASK_KERNEL_PORT</strong>
\r<dd>
\r[task-self send right] The port used to control this task. Used
\rto send messages that affect the task. This is the port returned
\rby <strong>mach_task_self</strong>.
\r<p>
\r<dt> <strong>TASK_BOOTSTRAP_PORT</strong>
\r<dd>
\r[bootstrap send right] The task's bootstrap port. Used to send
\rmessages requesting return of other system service ports.
\r<p>
\r<dt> <strong>TASK_HOST_NAME_PORT</strong>
\r<dd>
\r[host-self send right] The port used to request information of
\rthe containing host. This is the port returned by
\r<strong>mach_host_self</strong>.
\r<p>
\r<dt> <strong>TASK_WIRED_LEDGER_PORT</strong>
\r<dd>
\r[ledger send right] The port naming the source from which
\rthis task draws its wired kernel memory.
\r<p>
\r<dt> <strong>TASK_PAGED_LEDGER_PORT</strong>
\r<dd>
\r[ledger send right] The port naming the source from which
\rthis task draws its default memory managed memory.
\r</dl>
\r<p>
\r<dt> <var>special_port</var>
\r<dd>
\r[out task-special send right]
\rThe returned value for the port.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_get_special_port</strong> function returns a send right
\rfor a special port belonging to <var>task</var>.
\r<p>
\rIf one task has a send right for the kernel port of another task, it can use
\rthe port to perform kernel operations for the other task. Send rights for a
\rkernel port normally are held only by the task to which the port belongs,
\ror by the task's parent task. Using the <strong>mach_msg</strong> function, however,
\rany task can pass a send right for its kernel port to another task.
\r<h3>NOTES</h3>
\r<p>
\rThe current implementation does not support the <strong>TASK_HOST_NAME_PORT</strong>
\rfeatures associated with this interface.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_task_self.html"><strong>mach_task_self</strong></a>,
\r<a href="task_create.html"><strong>task_create</strong></a>,
\r<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>,
\r<a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>,
\r<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>,
\r<a href="mach_host_self.html"><strong>mach_host_self</strong></a>.
\r\ No newline at end of file
+<h2>task_get_special_port</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return a send write to the indicated special port.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_get_special_port</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>int</strong> <var>which_port</var>,
+ <strong>task</strong> <var>special_port</var><strong>);</strong>
+
+
+<strong>Macro Forms:</strong>
+
+
+<strong>kern_return_t task_get_bootstrap_port</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>task</strong> <var>special_port</var><strong>);</strong>
+
+
+<strong>kern_return_t task_get_kernel_port</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>task</strong> <var>special_port</var><strong>);</strong>
+
+
+<strong>kern_return_t task_get_host_name_port</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>task</strong> <var>special_port</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The port for the task for which to return the port's
+send right.
+<p>
+<dt> <var>which_port</var>
+<dd>
+[in scalar]
+The special port for which the send right is requested. Valid
+values are:
+<dl>
+<p>
+<dt> <strong>TASK_KERNEL_PORT</strong>
+<dd>
+[task-self send right] The port used to control this task. Used
+to send messages that affect the task. This is the port returned
+by <strong>mach_task_self</strong>.
+<p>
+<dt> <strong>TASK_BOOTSTRAP_PORT</strong>
+<dd>
+[bootstrap send right] The task's bootstrap port. Used to send
+messages requesting return of other system service ports.
+<p>
+<dt> <strong>TASK_HOST_NAME_PORT</strong>
+<dd>
+[host-self send right] The port used to request information of
+the containing host. This is the port returned by
+<strong>mach_host_self</strong>.
+<p>
+<dt> <strong>TASK_WIRED_LEDGER_PORT</strong>
+<dd>
+[ledger send right] The port naming the source from which
+this task draws its wired kernel memory.
+<p>
+<dt> <strong>TASK_PAGED_LEDGER_PORT</strong>
+<dd>
+[ledger send right] The port naming the source from which
+this task draws its default memory managed memory.
+</dl>
+<p>
+<dt> <var>special_port</var>
+<dd>
+[out task-special send right]
+The returned value for the port.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_get_special_port</strong> function returns a send right
+for a special port belonging to <var>task</var>.
+<p>
+If one task has a send right for the kernel port of another task, it can use
+the port to perform kernel operations for the other task. Send rights for a
+kernel port normally are held only by the task to which the port belongs,
+or by the task's parent task. Using the <strong>mach_msg</strong> function, however,
+any task can pass a send right for its kernel port to another task.
+<h3>NOTES</h3>
+<p>
+The current implementation does not support the <strong>TASK_HOST_NAME_PORT</strong>
+features associated with this interface.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_task_self.html"><strong>mach_task_self</strong></a>,
+<a href="task_create.html"><strong>task_create</strong></a>,
+<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>,
+<a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>,
+<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>,
+<a href="mach_host_self.html"><strong>mach_host_self</strong></a>.
-<h2>task_info</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return per-task information according to specified flavor.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_info</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>task_flavor_t</strong> <var>flavor</var>,
\r <strong>task_info_t</strong> <var>task_info</var>,
\r <strong>mach_msg_type_number_t</strong> <var>task_info_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe port for the task for which the information is to
\rbe returned.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of information to be returned. Valid values are:
\r<dl>
\r<p>
\r<dt> <strong>TASK_BASIC_INFO</strong>
\r<dd>
\rReturns basic information about the task, such as the task's
\rsuspend count and number of resident pages. The structure
\rreturned is <strong>task_basic_info</strong>.
\r<p>
\r<dt> <strong>TASK_THREAD_TIMES_INFO</strong>
\r<dd>
\rReturns system and user space run-times for live threads. The
\rstructure returned is <strong>task_thread_times_info</strong>.
\r<p>
\r<dt> <strong>TASK_SCHED_FIFO_INFO</strong>
\r<dd>
\rReturns default <strong>FIFO</strong> scheduling policy attributes to be
\rassigned to new threads. The structure returned is <strong>policy_fifo_base</strong>.
\r<p>
\r<dt> <strong>TASK_SCHED_RR_INFO</strong>
\r<dd>
\rReturns default round-robin scheduling policy attributes to be
\rassigned to new threads. The structure returned is
\r<strong>policy_rr_base</strong>.
\r<p>
\r<dt> <strong>TASK_SCHED_TIMESHARE_INFO</strong>
\r<dd>
\rReturns default timeshare scheduling policy attributes to be
\rassigned to new threads. The structure returned is
\r<strong>policy_timeshare_base</strong>.
\r<p>
\r<dt> <strong>TASK_SECURITY_TOKEN</strong>
\r<dd>
\rReturns the security token for the task. The value returned is of
\rtype <var>security_token_t</var>.
\r<p>
\r<dt> <strong>TASK_AUDIT_TOKEN</strong>
\r<dd>
\rReturns the security token for the task. The value returned is of
\rtype <var>audit_token_t</var>.
\r<p>
\r<dt> <strong>TASK_USER_DATA</strong>
\r<dd>
\rReturns user-specified information previously established via the
\r<strong>task_set_info</strong> interface. The structure returned is
\r<strong>task_user_data</strong>.
\r</dl>
\r<p>
\r<dt> <var>task_info</var>
\r<dd>
\r[out structure]
\rInformation about the specified task.
\r<p>
\r<dt> <var>task_info_count</var>
\r<dd>
\r[in/out scalar]
\rOn input, the maximum size of the buffer; on output, the
\rsize returned (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_info</strong> function returns an information structure
\rof type <var>flavor</var>.
\r<h3>NOTES</h3>
\r<p>
\rAt any given time, a task has one default scheduling policy assigned to it (as
\rreturned by <strong>TASK_BASIC_INFO</strong>). As such, only one of the scheduling flavors
\rwill return valid information.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_POLICY</strong>
\r<dd>
\rA request was made for the default scheduling policy attributes for the
\rtask but the requested policy is not the task's default policy.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>,
\r<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>,
\r<a href="task_set_info.html"><strong>task_set_info</strong></a>,
\r<a href="task_threads.html"><strong>task_threads</strong></a>,
\r<a href="thread_info.html"><strong>thread_info</strong></a>,
\r<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
\r<a href="thread_set_state.html"><strong>thread_set_state</strong></a>.
\r<p>
\rData Structures:
\r<a href="task_basic_info.html"><strong>task_basic_info</strong></a>,
\r<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>,
\r<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
\r<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>,
\r<a href="task_thread_times_info.html"><strong>task_thread_times_info</strong></a>.
\r\ No newline at end of file
+<h2>task_info</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return per-task information according to specified flavor.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_info</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>task_flavor_t</strong> <var>flavor</var>,
+ <strong>task_info_t</strong> <var>task_info</var>,
+ <strong>mach_msg_type_number_t</strong> <var>task_info_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The port for the task for which the information is to
+be returned.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of information to be returned. Valid values are:
+<dl>
+<p>
+<dt> <strong>TASK_BASIC_INFO</strong>
+<dd>
+Returns basic information about the task, such as the task's
+suspend count and number of resident pages. The structure
+returned is <strong>task_basic_info</strong>.
+<p>
+<dt> <strong>TASK_THREAD_TIMES_INFO</strong>
+<dd>
+Returns system and user space run-times for live threads. The
+structure returned is <strong>task_thread_times_info</strong>.
+<p>
+<dt> <strong>TASK_SCHED_FIFO_INFO</strong>
+<dd>
+Returns default <strong>FIFO</strong> scheduling policy attributes to be
+assigned to new threads. The structure returned is <strong>policy_fifo_base</strong>.
+<p>
+<dt> <strong>TASK_SCHED_RR_INFO</strong>
+<dd>
+Returns default round-robin scheduling policy attributes to be
+assigned to new threads. The structure returned is
+<strong>policy_rr_base</strong>.
+<p>
+<dt> <strong>TASK_SCHED_TIMESHARE_INFO</strong>
+<dd>
+Returns default timeshare scheduling policy attributes to be
+assigned to new threads. The structure returned is
+<strong>policy_timeshare_base</strong>.
+<p>
+<dt> <strong>TASK_SECURITY_TOKEN</strong>
+<dd>
+Returns the security token for the task. The value returned is of
+type <var>security_token_t</var>.
+<p>
+<dt> <strong>TASK_AUDIT_TOKEN</strong>
+<dd>
+Returns the security token for the task. The value returned is of
+type <var>audit_token_t</var>.
+<p>
+<dt> <strong>TASK_USER_DATA</strong>
+<dd>
+Returns user-specified information previously established via the
+<strong>task_set_info</strong> interface. The structure returned is
+<strong>task_user_data</strong>.
+</dl>
+<p>
+<dt> <var>task_info</var>
+<dd>
+[out structure]
+Information about the specified task.
+<p>
+<dt> <var>task_info_count</var>
+<dd>
+[in/out scalar]
+On input, the maximum size of the buffer; on output, the
+size returned (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_info</strong> function returns an information structure
+of type <var>flavor</var>.
+<h3>NOTES</h3>
+<p>
+At any given time, a task has one default scheduling policy assigned to it (as
+returned by <strong>TASK_BASIC_INFO</strong>). As such, only one of the scheduling flavors
+will return valid information.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_POLICY</strong>
+<dd>
+A request was made for the default scheduling policy attributes for the
+task but the requested policy is not the task's default policy.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>,
+<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>,
+<a href="task_set_info.html"><strong>task_set_info</strong></a>,
+<a href="task_threads.html"><strong>task_threads</strong></a>,
+<a href="thread_info.html"><strong>thread_info</strong></a>,
+<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
+<a href="thread_set_state.html"><strong>thread_set_state</strong></a>.
+<p>
+Data Structures:
+<a href="task_basic_info.html"><strong>task_basic_info</strong></a>,
+<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>,
+<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
+<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>,
+<a href="task_thread_times_info.html"><strong>task_thread_times_info</strong></a>.
-<h2>task_policy</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set target task's default scheduling policy state.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_policy</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>policy_t</strong> <var>policy</var>,
\r <strong>policy_base_t</strong> <var>base</var>,
\r <strong>base</strong> <var>base_count</var>,
\r <strong>boolean_t</strong> <var>set_limit</var>,
\r <strong>boolean_t</strong> <var>change_threads</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe port for the task whose scheduling attributes
\rare to be set.
\r<dt> <var>policy</var>
\r<dd>
\r[in scalar]
\rDefault policy. The values currently defined are <strong>POLICY_TIMESHARE</strong>,
\r<strong>POLICY_RR</strong> (round robin) and <strong>POLICY_FIFO</strong> (firstin, first-out).
\r<dt> <var>base</var>
\r<dd>
\r[pointer to in structure]
\rBase scheduling policy data, <strong>policy_fifo_base</strong>,
\r<strong>policy_rr_base</strong> or <strong>policy_timeshare_base</strong>.
\r<dt> <var>base_count</var>
\r<dd>
\r[in scalar]
\rThe size of the buffer (in natural-sized units).
\r<dt> <var>set_limit</var>
\r<dd>
\r[in scalar]
\rTrue if the scheduling limits for the task should be restricted
\rto allow no more service than specified by <var>base</var>.
\r<dt> <var>change_threads</var>
\r<dd>
\r[in scalar]
\rTrue if the attributes (and limits, if <var>set_limit</var> is true) of
\rexisting threads within the task should also be changed.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_policy</strong> function sets the default scheduling
\rattributes for <var>task</var>. These
\rattributes are used when creating new threads. Changing the default attributes
\rfor a task does not affect the attributes of the contained threads unless
\r<var>change_threads</var> is <strong>TRUE</strong>. At no time will a thread ever have
\rscheduling attributes that exceed the thread's limits.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<dt> <strong>KERN_INVALID_POLICY</strong>
\r<dd>
\rThe processor set does not currently enable <var>policy</var>.
\r<dt> <strong>KERN_POLICY_LIMIT</strong>
\r<dd>
\rThe specified scheduling attributes exceeds the thread's limits.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="thread_policy.html"><strong>thread_policy</strong></a>,
\r<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>,
\r<a href="task_set_policy.html"><strong>task_set_policy</strong></a>,
\r<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>.
\r<p>
\rData Structures:
\r<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
\r<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>,
\r<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>.
\r\ No newline at end of file
+<h2>task_policy</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set target task's default scheduling policy state.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_policy</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>policy_t</strong> <var>policy</var>,
+ <strong>policy_base_t</strong> <var>base</var>,
+ <strong>base</strong> <var>base_count</var>,
+ <strong>boolean_t</strong> <var>set_limit</var>,
+ <strong>boolean_t</strong> <var>change_threads</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The port for the task whose scheduling attributes
+are to be set.
+<dt> <var>policy</var>
+<dd>
+[in scalar]
+Default policy. The values currently defined are <strong>POLICY_TIMESHARE</strong>,
+<strong>POLICY_RR</strong> (round robin) and <strong>POLICY_FIFO</strong> (firstin, first-out).
+<dt> <var>base</var>
+<dd>
+[pointer to in structure]
+Base scheduling policy data, <strong>policy_fifo_base</strong>,
+<strong>policy_rr_base</strong> or <strong>policy_timeshare_base</strong>.
+<dt> <var>base_count</var>
+<dd>
+[in scalar]
+The size of the buffer (in natural-sized units).
+<dt> <var>set_limit</var>
+<dd>
+[in scalar]
+True if the scheduling limits for the task should be restricted
+to allow no more service than specified by <var>base</var>.
+<dt> <var>change_threads</var>
+<dd>
+[in scalar]
+True if the attributes (and limits, if <var>set_limit</var> is true) of
+existing threads within the task should also be changed.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_policy</strong> function sets the default scheduling
+attributes for <var>task</var>. These
+attributes are used when creating new threads. Changing the default attributes
+for a task does not affect the attributes of the contained threads unless
+<var>change_threads</var> is <strong>TRUE</strong>. At no time will a thread ever have
+scheduling attributes that exceed the thread's limits.
+<h3>RETURN VALUES</h3>
+<dl>
+<dt> <strong>KERN_INVALID_POLICY</strong>
+<dd>
+The processor set does not currently enable <var>policy</var>.
+<dt> <strong>KERN_POLICY_LIMIT</strong>
+<dd>
+The specified scheduling attributes exceeds the thread's limits.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="thread_policy.html"><strong>thread_policy</strong></a>,
+<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>,
+<a href="task_set_policy.html"><strong>task_set_policy</strong></a>,
+<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>.
+<p>
+Data Structures:
+<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
+<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>,
+<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>.
-<h2>task_resume</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Decrement the target task's suspend count.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_resume</strong>
\r <strong>(task_t</strong> <var>task</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe port to the task to be resumed.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_resume</strong> function decrements the suspend count
\rfor <var>task</var>. If the task's suspend count goes to zero, the
\rfunction resumes any suspended threads within the task. To resume
\ra given thread, the thread's own suspend count must also be zero.
\r<h3>NOTES</h3>
\r<p>
\rAn attempt to lower the suspend count below zero is ignored.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_create.html"><strong>task_create</strong></a>,
\r<a href="task_info.html"><strong>task_info</strong></a>,
\r<a href="task_suspend.html"><strong>task_suspend</strong></a>,
\r<a href="task_terminate.html"><strong>task_terminate</strong></a>,
\r<a href="thread_info.html"><strong>thread_info</strong></a>,
\r<a href="thread_resume.html"><strong>thread_resume</strong></a>,
\r<a href="thread_suspend.html"><strong>thread_suspend</strong></a>.
\r\ No newline at end of file
+<h2>task_resume</h2>
+<hr>
+<p>
+<strong>Function</strong> - Decrement the target task's suspend count.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_resume</strong>
+ <strong>(task_t</strong> <var>task</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The port to the task to be resumed.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_resume</strong> function decrements the suspend count
+for <var>task</var>. If the task's suspend count goes to zero, the
+function resumes any suspended threads within the task. To resume
+a given thread, the thread's own suspend count must also be zero.
+<h3>NOTES</h3>
+<p>
+An attempt to lower the suspend count below zero is ignored.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_create.html"><strong>task_create</strong></a>,
+<a href="task_info.html"><strong>task_info</strong></a>,
+<a href="task_suspend.html"><strong>task_suspend</strong></a>,
+<a href="task_terminate.html"><strong>task_terminate</strong></a>,
+<a href="thread_info.html"><strong>thread_info</strong></a>,
+<a href="thread_resume.html"><strong>thread_resume</strong></a>,
+<a href="thread_suspend.html"><strong>thread_suspend</strong></a>.
-<h2>task_sample</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Sample the target task's thread program counters periodically.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_sample</strong>
\r <strong>(task_t</strong> <var>sample_task</var>,
\r <strong>mach_port_make_send_t</strong> <var>reply_port</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>sample_task</var>
\r<dd>
\r[in task send right]
\rPort for the task whose threads' PC are to be
\rsampled.
\r<p>
\r<dt> <var>reply_port</var>
\r<dd>
\r[in sample receive (to be converted to send) right]
\rPort to which PC sample buffers are sent. A value of <strong>MACH_PORT_NULL</strong>
\rstops PC sampling for the task.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_sample</strong> function causes the program counter (PC) of the
\rspecified <var>sample_task</var> (actually, all of the threads within
\r<var>sample_task</var>) to be sampled periodically (whenever one of the threads
\rhappens to be running at the time of the kernel's "hardclock" interrupt).
\rThe set of PC sample values obtained are saved in buffers which are sent to
\rthe specified <var>reply_port</var> in <strong>receive_samples</strong> messages.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="thread_sample.html"><strong>thread_sample</strong></a>,
\r<a href="receive_samples.html"><strong>receive_samples</strong></a>.
\r\ No newline at end of file
+<h2>task_sample</h2>
+<hr>
+<p>
+<strong>Function</strong> - Sample the target task's thread program counters periodically.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_sample</strong>
+ <strong>(task_t</strong> <var>sample_task</var>,
+ <strong>mach_port_make_send_t</strong> <var>reply_port</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>sample_task</var>
+<dd>
+[in task send right]
+Port for the task whose threads' PC are to be
+sampled.
+<p>
+<dt> <var>reply_port</var>
+<dd>
+[in sample receive (to be converted to send) right]
+Port to which PC sample buffers are sent. A value of <strong>MACH_PORT_NULL</strong>
+stops PC sampling for the task.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_sample</strong> function causes the program counter (PC) of the
+specified <var>sample_task</var> (actually, all of the threads within
+<var>sample_task</var>) to be sampled periodically (whenever one of the threads
+happens to be running at the time of the kernel's "hardclock" interrupt).
+The set of PC sample values obtained are saved in buffers which are sent to
+the specified <var>reply_port</var> in <strong>receive_samples</strong> messages.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="thread_sample.html"><strong>thread_sample</strong></a>,
+<a href="receive_samples.html"><strong>receive_samples</strong></a>.
-<h2>task_set_emulation</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Establish a user-level handler for a system call.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_set_emulation</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>vm_address_t</strong> <var>routine_entry_pt</var>,
\r <strong>int</strong> <var>syscall_number</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task port] The port for the task for which to establish the system call handler.
\r<p>
\r<dt> <var>routine_entry_pt</var>
\r<dd>
\r[in scalar] The address within the task of the handler for this particular system call.
\r<p>
\r<dt> <var>syscall_number</var>
\r<dd>
\r[in scalar] The number of the system call to be handled by this handler.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_set_emulation</strong> function establishes a handler within the task
\rfor a particular system call. When a thread executes a system call
\rwith this particular number, the system call will be redirected to the
\rspecified routine within the task's address space. This is expected to
\rbe an address within the transparent emulation library. These
\remulation handler addresses are inherited by child processes.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the virtual
\raddress parameter.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_set_emulation_vector.html"><strong>task_set_emulation_vector</strong></a>,
\r<a href="task_get_emulation_vector.html"><strong>task_get_emulation_vector</strong></a>.
\r\ No newline at end of file
+<h2>task_set_emulation</h2>
+<hr>
+<p>
+<strong>Function</strong> - Establish a user-level handler for a system call.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_set_emulation</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>vm_address_t</strong> <var>routine_entry_pt</var>,
+ <strong>int</strong> <var>syscall_number</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task port] The port for the task for which to establish the system call handler.
+<p>
+<dt> <var>routine_entry_pt</var>
+<dd>
+[in scalar] The address within the task of the handler for this particular system call.
+<p>
+<dt> <var>syscall_number</var>
+<dd>
+[in scalar] The number of the system call to be handled by this handler.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_set_emulation</strong> function establishes a handler within the task
+for a particular system call. When a thread executes a system call
+with this particular number, the system call will be redirected to the
+specified routine within the task's address space. This is expected to
+be an address within the transparent emulation library. These
+emulation handler addresses are inherited by child processes.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the virtual
+address parameter.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_set_emulation_vector.html"><strong>task_set_emulation_vector</strong></a>,
+<a href="task_get_emulation_vector.html"><strong>task_get_emulation_vector</strong></a>.
-<h2>task_set_emulation_vector</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Establish the target task's user-level system call handlers.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_set_emulation_vector</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>int</strong> <var>vector_start</var>,
\r <strong>emulation_vector_t</strong> <var>emulation_vector</var>,
\r <strong>mach_msg_type_number_t</strong> <var>emulation_vector_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe port for the task for which to establish the
\rsystem call handler.
\r<p>
\r<dt> <var>vector_start</var>
\r<dd>
\r[in scalar]
\rThe syscall number corresponding to the first element of
\r<var>emulation_vector</var>.
\r<p>
\r<dt> <var>emulation_vector</var>
\r<dd>
\r[pointer to in array of <strong>vm_address_t</strong>]
\rAn array of routine entrypoints
\rfor the system calls starting with syscall number <var>vector_start</var>.
\r<p>
\r<dt> <var>emulation_vector_count</var>
\r<dd>
\r[in scalar]
\rThe number of elements in <var>emulation_vector</var>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_set_emulation_vector</strong> function establishes
\ra handler within the task
\rfor a set of system calls. When a thread executes a system call
\rwith one of these
\rnumbers, the system call will be redirected to the corresponding
\rroutine within
\rthe task's address space.
\r<p>
\rThese emulation handler addresses are inherited by child processes.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the
\rvirtual addresses
\rin the <var>emulation_vector</var> parameter.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_get_emulation_vector.html"><strong>task_get_emulation_vector</strong></a>.
\r\ No newline at end of file
+<h2>task_set_emulation_vector</h2>
+<hr>
+<p>
+<strong>Function</strong> - Establish the target task's user-level system call handlers.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_set_emulation_vector</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>int</strong> <var>vector_start</var>,
+ <strong>emulation_vector_t</strong> <var>emulation_vector</var>,
+ <strong>mach_msg_type_number_t</strong> <var>emulation_vector_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The port for the task for which to establish the
+system call handler.
+<p>
+<dt> <var>vector_start</var>
+<dd>
+[in scalar]
+The syscall number corresponding to the first element of
+<var>emulation_vector</var>.
+<p>
+<dt> <var>emulation_vector</var>
+<dd>
+[pointer to in array of <strong>vm_address_t</strong>]
+An array of routine entrypoints
+for the system calls starting with syscall number <var>vector_start</var>.
+<p>
+<dt> <var>emulation_vector_count</var>
+<dd>
+[in scalar]
+The number of elements in <var>emulation_vector</var>.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_set_emulation_vector</strong> function establishes
+a handler within the task
+for a set of system calls. When a thread executes a system call
+with one of these
+numbers, the system call will be redirected to the corresponding
+routine within
+the task's address space.
+<p>
+These emulation handler addresses are inherited by child processes.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the
+virtual addresses
+in the <var>emulation_vector</var> parameter.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_get_emulation_vector.html"><strong>task_get_emulation_vector</strong></a>.
-<h2>task_set_exception_ports</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set target task's exception ports.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_set_exception_ports</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>exception_mask_t</strong> <var>exception_types</var>,
\r <strong>mach_port_t</strong> <var>exception_port</var>,
\r <strong>exception_behavior_t</strong> <var>behavior</var>,
\r <strong>thread_state_flavor_t</strong> <var>flavor</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task for which to set the ports.
\r<p>
\r<dt> <var>exception_types</var>
\r<dd>
\r[in scalar]
\rA flag word indicating the types of exceptions for which the
\rexception port applies:
\r<dl>
\r<p>
\r<dt> <strong>EXC_MASK_BAD_ACCESS</strong>
\r<dd>
\rCould not access memory.
\r<p>
\r<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
\r<dd>
\rInstruction failed. Illegal or undefined instruction or operand.
\r<p>
\r<dt> <strong>EXC_MASK_ARITHMETIC</strong>
\r<dd>
\rArithmetic exception
\r<p>
\r<dt> <strong>EXC_MASK_EMULATION</strong>
\r<dd>
\rEmulation instruction. Emulation support instruction
\rencountered.
\r<p>
\r<dt> <strong>EXC_MASK_SOFTWARE</strong>
\r<dd>
\rSoftware generated exception.
\r<p>
\r<dt> <strong>EXC_MASK_BREAKPOINT</strong>
\r<dd>
\rTrace, breakpoint, etc.
\r<p>
\r<dt> <strong>EXC_MASK_SYSCALL</strong>
\r<dd>
\rSystem call requested.
\r<p>
\r<dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
\r<dd>
\rSystem call with a number in the Mach call range requested.
\r<p>
\r<dt> <strong>EXC_MASK_RPC_ALERT </strong>
\r<dd>
\rExceptional condition encountered during execution of RPC.
\r</dl>
\r<p>
\r<dt> <var>exception_port</var>
\r<dd>
\r[in exception send right]
\rThe exception port for all selected exception
\rtypes.
\r<p>
\r<dt> <var>behavior</var>
\r<dd>
\r[in scalar]
\rThe type of exception message to be sent. Defined types are:
\r<dl>
\r<p>
\r<dt> <strong>EXCEPTION_DEFAULT</strong>
\r<dd>
\rSend a <strong>catch_exception_raise</strong> message including the thread
\ridentity.
\r<p>
\r<dt> <strong>EXCEPTION_STATE</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state</strong> message including the
\rthread state.
\r<p>
\r<dt> <strong>EXCEPTION_STATE_PROTECTED</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state</strong> message including the
\rthread state. Mark the exception port (and associated
\rexceptions) as protected.
\r<p>
\r<dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state_identity</strong> message
\rincluding the thread identity and state.
\r<p>
\r<dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state_identity</strong> message
\rincluding the thread identity and state. Mark the exception port
\r(and associated exceptions) as protected.
\r</dl>
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of state to be sent with the exception message.
\rThese types are defined in <strong><mach/thread_states.h></strong>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_set_exception_ports</strong> function sets a specified
\rset of exception ports belonging to <var>task</var>. A task exception port
\ris used when a thread specific exception port returns a non-success reply.
\r<h3>NOTES</h3>
\r<p>
\rIf the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is
\rthe host name port, Mach kernel traps are executed by the kernel as expected;
\rany other value causes the attempted execution of these system call numbers to
\rbe considered an exception.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_task_self.html"><strong>mach_task_self</strong></a>,
\r<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
\r<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
\r<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
\r<a href="thread_create.html"><strong>thread_create</strong></a>,
\r<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
\r<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
\r<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>,
\r<a href="thread_abort.html"><strong>thread_abort</strong></a>.
\r\ No newline at end of file
+<h2>task_set_exception_ports</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set target task's exception ports.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_set_exception_ports</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>exception_mask_t</strong> <var>exception_types</var>,
+ <strong>mach_port_t</strong> <var>exception_port</var>,
+ <strong>exception_behavior_t</strong> <var>behavior</var>,
+ <strong>thread_state_flavor_t</strong> <var>flavor</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task for which to set the ports.
+<p>
+<dt> <var>exception_types</var>
+<dd>
+[in scalar]
+A flag word indicating the types of exceptions for which the
+exception port applies:
+<dl>
+<p>
+<dt> <strong>EXC_MASK_BAD_ACCESS</strong>
+<dd>
+Could not access memory.
+<p>
+<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
+<dd>
+Instruction failed. Illegal or undefined instruction or operand.
+<p>
+<dt> <strong>EXC_MASK_ARITHMETIC</strong>
+<dd>
+Arithmetic exception
+<p>
+<dt> <strong>EXC_MASK_EMULATION</strong>
+<dd>
+Emulation instruction. Emulation support instruction
+encountered.
+<p>
+<dt> <strong>EXC_MASK_SOFTWARE</strong>
+<dd>
+Software generated exception.
+<p>
+<dt> <strong>EXC_MASK_BREAKPOINT</strong>
+<dd>
+Trace, breakpoint, etc.
+<p>
+<dt> <strong>EXC_MASK_SYSCALL</strong>
+<dd>
+System call requested.
+<p>
+<dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
+<dd>
+System call with a number in the Mach call range requested.
+<p>
+<dt> <strong>EXC_MASK_RPC_ALERT </strong>
+<dd>
+Exceptional condition encountered during execution of RPC.
+</dl>
+<p>
+<dt> <var>exception_port</var>
+<dd>
+[in exception send right]
+The exception port for all selected exception
+types.
+<p>
+<dt> <var>behavior</var>
+<dd>
+[in scalar]
+The type of exception message to be sent. Defined types are:
+<dl>
+<p>
+<dt> <strong>EXCEPTION_DEFAULT</strong>
+<dd>
+Send a <strong>catch_exception_raise</strong> message including the thread
+identity.
+<p>
+<dt> <strong>EXCEPTION_STATE</strong>
+<dd>
+Send a <strong>catch_exception_raise_state</strong> message including the
+thread state.
+<p>
+<dt> <strong>EXCEPTION_STATE_PROTECTED</strong>
+<dd>
+Send a <strong>catch_exception_raise_state</strong> message including the
+thread state. Mark the exception port (and associated
+exceptions) as protected.
+<p>
+<dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
+<dd>
+Send a <strong>catch_exception_raise_state_identity</strong> message
+including the thread identity and state.
+<p>
+<dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong>
+<dd>
+Send a <strong>catch_exception_raise_state_identity</strong> message
+including the thread identity and state. Mark the exception port
+(and associated exceptions) as protected.
+</dl>
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of state to be sent with the exception message.
+These types are defined in <strong><mach/thread_states.h></strong>.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_set_exception_ports</strong> function sets a specified
+set of exception ports belonging to <var>task</var>. A task exception port
+is used when a thread specific exception port returns a non-success reply.
+<h3>NOTES</h3>
+<p>
+If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is
+the host name port, Mach kernel traps are executed by the kernel as expected;
+any other value causes the attempted execution of these system call numbers to
+be considered an exception.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_task_self.html"><strong>mach_task_self</strong></a>,
+<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
+<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
+<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
+<a href="thread_create.html"><strong>thread_create</strong></a>,
+<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
+<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
+<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>,
+<a href="thread_abort.html"><strong>thread_abort</strong></a>.
-<H2>task_set_info</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set task-specific information state.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>#include<task_info.h></strong>
\r\r<strong>kern_return_t task_set_info</strong>
\r <strong>(task_t</strong> <var>target_task</var>,
\r <strong>task_flavor_t</strong> <var>flavor</var>,
\r <strong>task_info_t</strong> <var>task_info</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\rThe task whose information is to be set.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\rSpecifies the type of information to be set. Currently the interface
\rsupports the setting of a single flavor:
\r<strong>TASK_USER_DATA</strong>.
\r<p>
\r<dt> <var>task_info</var>
\r<dd>
\rSpecifies the information to be set.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_set_info</strong> interface provides the caller with
\rthe means to set the target task's <var>user_data</var> field. This
\rfield may be used to specify arbitrarily task-specific data.
\r<h3>NOTES</h3>
\r<p>
\rCurrently, this interface is used exclusively to provide freshly
\rcolocated user tasks with the short-circuited RPC glue vector.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic values apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\r\ No newline at end of file
+<H2>task_set_info</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set task-specific information state.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>#include<task_info.h></strong>
+
+<strong>kern_return_t task_set_info</strong>
+ <strong>(task_t</strong> <var>target_task</var>,
+ <strong>task_flavor_t</strong> <var>flavor</var>,
+ <strong>task_info_t</strong> <var>task_info</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+The task whose information is to be set.
+<p>
+<dt> <var>flavor</var>
+<dd>
+Specifies the type of information to be set. Currently the interface
+supports the setting of a single flavor:
+<strong>TASK_USER_DATA</strong>.
+<p>
+<dt> <var>task_info</var>
+<dd>
+Specifies the information to be set.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_set_info</strong> interface provides the caller with
+the means to set the target task's <var>user_data</var> field. This
+field may be used to specify arbitrarily task-specific data.
+<h3>NOTES</h3>
+<p>
+Currently, this interface is used exclusively to provide freshly
+colocated user tasks with the short-circuited RPC glue vector.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic values apply.
+<h3>RELATED INFORMATION</h3>
+<p>
-<h2>task_set_policy</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set target task's default scheduling policy state. (Protected Interface.)
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_set_policy</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>processor_set_t</strong> <var>processor_set</var>,
\r <strong>policy_t</strong> <var>policy</var>,
\r <strong>policy_base_t</strong> <var>base</var>,
\r <strong>mach_msg_type_number_t</strong> <var>base_count</var>,
\r <strong>policy_limit_t</strong> <var>limit</var>,
\r <strong>mach_msg_type_number_t</strong> <var>limit_count</var>,
\r <strong>boolean_t</strong> <var>change_threads</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task whose scheduling policy is to be set.
\r<dt> <var>processor_set</var>
\r<dd>
\r[in processor-set-control send right]
\rThe control port for the processor
\rset to which the task is currently assigned.
\r<dt> <var>policy</var>
\r<dd>
\r[in scalar]
\rPolicy to be set. The values currently defined are <strong>POLICY_TIMESHARE</strong>,
\r<strong>POLICY_RR</strong> (round robin) and <strong>POLICY_FIFO</strong> (firstin, first-out).
\r<dt> <var>base</var>
\r<dd>
\r[pointer to in structure]
\rBase policy specific data, <strong>policy_fifo_base</strong>,
\r<strong>policy_rr_base</strong> or <strong>policy_timeshare_base</strong>.
\r<dt> <var>base_count</var>
\r<dd>
\r[in scalar]
\rThe size of the buffer (in natural-sized units).
\r<dt> <var>limit</var>
\r<dd>
\r[pointer to in structure]
\rPolicy specific limits, <strong>policy_fifo_limit</strong>,
\r<strong>policy_rr_limit</strong> or <strong>policy_timeshare_limit</strong>.
\r<dt> <var>limit_count</var>
\r<dd>
\r[in scalar]
\rThe size of the buffer (in natural-sized units).
\r<dt> <var>change_threads</var>
\r<dd>
\r[in scalar]
\rTrue if the scheduling attributes for all contained threads
\rshould be changed as well.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_set_policy</strong> function sets the scheduling attributes,
\rboth base and limit, for <var>task</var>.
\r<var>policy</var> may be any policy implemented by the processor set whether or
\rnot it is enabled.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<dt> <strong>KERN_INVALID_PROCESSOR_SET</strong>
\r<dd>
\r<var>processor_set</var> is not the task's processor set control port.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>,
\r<a href="thread_policy.html"><strong>thread_policy</strong></a>,
\r<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>,
\r<a href="task_policy.html"><strong>task_policy</strong></a>.
\r<p>
\rData Structures:
\r<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
\r<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>,
\r<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>.
\r\ No newline at end of file
+<h2>task_set_policy</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set target task's default scheduling policy state. (Protected Interface.)
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_set_policy</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>processor_set_t</strong> <var>processor_set</var>,
+ <strong>policy_t</strong> <var>policy</var>,
+ <strong>policy_base_t</strong> <var>base</var>,
+ <strong>mach_msg_type_number_t</strong> <var>base_count</var>,
+ <strong>policy_limit_t</strong> <var>limit</var>,
+ <strong>mach_msg_type_number_t</strong> <var>limit_count</var>,
+ <strong>boolean_t</strong> <var>change_threads</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task whose scheduling policy is to be set.
+<dt> <var>processor_set</var>
+<dd>
+[in processor-set-control send right]
+The control port for the processor
+set to which the task is currently assigned.
+<dt> <var>policy</var>
+<dd>
+[in scalar]
+Policy to be set. The values currently defined are <strong>POLICY_TIMESHARE</strong>,
+<strong>POLICY_RR</strong> (round robin) and <strong>POLICY_FIFO</strong> (firstin, first-out).
+<dt> <var>base</var>
+<dd>
+[pointer to in structure]
+Base policy specific data, <strong>policy_fifo_base</strong>,
+<strong>policy_rr_base</strong> or <strong>policy_timeshare_base</strong>.
+<dt> <var>base_count</var>
+<dd>
+[in scalar]
+The size of the buffer (in natural-sized units).
+<dt> <var>limit</var>
+<dd>
+[pointer to in structure]
+Policy specific limits, <strong>policy_fifo_limit</strong>,
+<strong>policy_rr_limit</strong> or <strong>policy_timeshare_limit</strong>.
+<dt> <var>limit_count</var>
+<dd>
+[in scalar]
+The size of the buffer (in natural-sized units).
+<dt> <var>change_threads</var>
+<dd>
+[in scalar]
+True if the scheduling attributes for all contained threads
+should be changed as well.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_set_policy</strong> function sets the scheduling attributes,
+both base and limit, for <var>task</var>.
+<var>policy</var> may be any policy implemented by the processor set whether or
+not it is enabled.
+<h3>RETURN VALUES</h3>
+<dl>
+<dt> <strong>KERN_INVALID_PROCESSOR_SET</strong>
+<dd>
+<var>processor_set</var> is not the task's processor set control port.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>,
+<a href="thread_policy.html"><strong>thread_policy</strong></a>,
+<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>,
+<a href="task_policy.html"><strong>task_policy</strong></a>.
+<p>
+Data Structures:
+<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
+<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>,
+<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>.
-<h2>task_set_port_space</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set the size of the target task's port name space table.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_set_port_space</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>int</strong> <var>table_entries</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in send right] The port referencing the task whose port name space is
\rto be set.
\r<p>
\r<dt> <var>table_entries</var>
\r<dd>
\r[in scalar] The number of entries in the port name space table.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_set_port_space</strong> function preallocates the specified number of
\rentries in the specified task's IPC name space.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_NO_SPACE</strong>
\r<dd>
\rThe requested table size exceeds the maximum allowable table size.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>.
\r\ No newline at end of file
+<h2>task_set_port_space</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set the size of the target task's port name space table.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_set_port_space</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>int</strong> <var>table_entries</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in send right] The port referencing the task whose port name space is
+to be set.
+<p>
+<dt> <var>table_entries</var>
+<dd>
+[in scalar] The number of entries in the port name space table.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_set_port_space</strong> function preallocates the specified number of
+entries in the specified task's IPC name space.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_NO_SPACE</strong>
+<dd>
+The requested table size exceeds the maximum allowable table size.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_port_allocate.html"><strong>mach_port_allocate</strong></a>.
-<h2>task_set_special_port</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set the indicated special port.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_set_special_port</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>int</strong> <var>which_port</var>,
\r <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
\r\r\r<strong>Macro forms:</strong>
\r\r\r<strong>kern_return_t task_set_bootstrap_port</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>int</strong> <var>which_port</var>,
\r <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
\r\r\r<strong>kern_return_t task_set_kernel_port</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>int</strong> <var>which_port</var>,
\r <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
\r\r\r<strong>kern_return_t task_set_host_name_port</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe port for the task for which to set the port.
\r<p>
\r<dt> <var>which_port</var>
\r<dd>
\r[in scalar]
\rThe special port to be set. Valid values are:
\r<dl>
\r<p>
\r<dt> <strong>TASK_BOOTSTRAP_PORT</strong>
\r<dd>
\r[bootstrap send right] The task's bootstrap port. Used to send
\rmessages requesting return of other system service ports.
\r<p>
\r<dt> <strong>TASK_KERNEL_PORT</strong>
\r<dd>
\r[task-self send right] The task's kernel port. Used by the
\rkernel to receive messages to manipulate the task. This is the
\rport returned by <strong>mach_task_self</strong>. Setting this special port
\rdoes not change the identity of the kernel port that names the
\rtask; this simply changes the value returned as the kernel
\rspecial port.
\r<p>
\r<dt> <strong>TASK_HOST_NAME_PORT</strong>
\r<dd>
\r[host-self send right] The task's host self port. Used by the
\rtask to request information about its containing host. This is
\rthe port returned by <strong>mach_host_self</strong>. Setting this special port
\rdoes not change the identity of the kernel port that names the
\rhost; this simply changes the value returned as the host
\rspecial port.
\r<p>
\r<dt> <strong>TASK_WIRED_LEDGER_PORT</strong>
\r<dd>
\r[ledger send right] The resource ledger from which the task
\rdraws its wired kernel memory. Setting this special port does
\rnot change the ledger from which the task draws its resources;
\rthis simply changes the value returned as the ledger special
\rport.
\r<p>
\r<dt> <strong>TASK_PAGED_LEDGER_PORT</strong>
\r<dd>
\r[ledger send right] The resource ledger from which the task
\rdraws its default memory managed memory. Setting this
\rspecial port does not change the ledger from which the task
\rdraws its resources; this simply changes the value returned as
\rthe ledger special port.
\r</dl>
\r<p>
\r<dt> <var>special_port</var>
\r<dd>
\r[in task-special send right]
\rThe value for the port.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_set_special_port</strong> function sets a special port
\rbelonging to <var>task</var>.
\r<h3>NOTES</h3>
\r<p>
\rThe current implementation does not support the <strong>TASK_HOST_NAME_PORT</strong>
\rfeatures associated with this interface.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_create.html"><strong>task_create</strong></a>,
\r<a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>,
\r<a href="mach_task_self.html"><strong>mach_task_self</strong></a>,
\r<a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>,
\r<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>,
\r<a href="mach_host_self.html"><strong>mach_host_self</strong></a>.
\r\ No newline at end of file
+<h2>task_set_special_port</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set the indicated special port.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_set_special_port</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>int</strong> <var>which_port</var>,
+ <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
+
+
+<strong>Macro forms:</strong>
+
+
+<strong>kern_return_t task_set_bootstrap_port</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>int</strong> <var>which_port</var>,
+ <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
+
+
+<strong>kern_return_t task_set_kernel_port</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>int</strong> <var>which_port</var>,
+ <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
+
+
+<strong>kern_return_t task_set_host_name_port</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The port for the task for which to set the port.
+<p>
+<dt> <var>which_port</var>
+<dd>
+[in scalar]
+The special port to be set. Valid values are:
+<dl>
+<p>
+<dt> <strong>TASK_BOOTSTRAP_PORT</strong>
+<dd>
+[bootstrap send right] The task's bootstrap port. Used to send
+messages requesting return of other system service ports.
+<p>
+<dt> <strong>TASK_KERNEL_PORT</strong>
+<dd>
+[task-self send right] The task's kernel port. Used by the
+kernel to receive messages to manipulate the task. This is the
+port returned by <strong>mach_task_self</strong>. Setting this special port
+does not change the identity of the kernel port that names the
+task; this simply changes the value returned as the kernel
+special port.
+<p>
+<dt> <strong>TASK_HOST_NAME_PORT</strong>
+<dd>
+[host-self send right] The task's host self port. Used by the
+task to request information about its containing host. This is
+the port returned by <strong>mach_host_self</strong>. Setting this special port
+does not change the identity of the kernel port that names the
+host; this simply changes the value returned as the host
+special port.
+<p>
+<dt> <strong>TASK_WIRED_LEDGER_PORT</strong>
+<dd>
+[ledger send right] The resource ledger from which the task
+draws its wired kernel memory. Setting this special port does
+not change the ledger from which the task draws its resources;
+this simply changes the value returned as the ledger special
+port.
+<p>
+<dt> <strong>TASK_PAGED_LEDGER_PORT</strong>
+<dd>
+[ledger send right] The resource ledger from which the task
+draws its default memory managed memory. Setting this
+special port does not change the ledger from which the task
+draws its resources; this simply changes the value returned as
+the ledger special port.
+</dl>
+<p>
+<dt> <var>special_port</var>
+<dd>
+[in task-special send right]
+The value for the port.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_set_special_port</strong> function sets a special port
+belonging to <var>task</var>.
+<h3>NOTES</h3>
+<p>
+The current implementation does not support the <strong>TASK_HOST_NAME_PORT</strong>
+features associated with this interface.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_create.html"><strong>task_create</strong></a>,
+<a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>,
+<a href="mach_task_self.html"><strong>mach_task_self</strong></a>,
+<a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>,
+<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>,
+<a href="mach_host_self.html"><strong>mach_host_self</strong></a>.
-<h2>task_suspend</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Suspend the target task.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_suspend</strong>
\r <strong>(task_t</strong> <var>task</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe port for the task to be suspended.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_suspend</strong> function increments the suspend count
\rfor task and stops all
\rthreads within the task. As long as the suspend count is positive,
\rno newly-created threads can execute. The function does not return until all
\rof the task's threads have been suspended.
\r<h3>NOTES</h3>
\r<p>
\rTo resume a suspended task and its threads, use <strong>task_resume</strong>.
\rIf the suspend
\rcount is greater than one, <strong>task_resume</strong> must be repeated
\rthat number of times.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_create.html"><strong>task_create</strong></a>,
\r<a href="task_info.html"><strong>task_info</strong></a>,
\r<a href="task_resume.html"><strong>task_resume</strong></a>,
\r<a href="task_terminate.html"><strong>task_terminate</strong></a>,
\r<a href="thread_suspend.html"><strong>thread_suspend</strong></a>.
\r\ No newline at end of file
+<h2>task_suspend</h2>
+<hr>
+<p>
+<strong>Function</strong> - Suspend the target task.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_suspend</strong>
+ <strong>(task_t</strong> <var>task</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The port for the task to be suspended.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_suspend</strong> function increments the suspend count
+for task and stops all
+threads within the task. As long as the suspend count is positive,
+no newly-created threads can execute. The function does not return until all
+of the task's threads have been suspended.
+<h3>NOTES</h3>
+<p>
+To resume a suspended task and its threads, use <strong>task_resume</strong>.
+If the suspend
+count is greater than one, <strong>task_resume</strong> must be repeated
+that number of times.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_create.html"><strong>task_create</strong></a>,
+<a href="task_info.html"><strong>task_info</strong></a>,
+<a href="task_resume.html"><strong>task_resume</strong></a>,
+<a href="task_terminate.html"><strong>task_terminate</strong></a>,
+<a href="thread_suspend.html"><strong>thread_suspend</strong></a>.
-<h2>task_swap_exception_ports</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set target task's exception ports, returning the previous exception ports.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_swap_exception_ports</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>exception_mask_t</strong> <var>exception_types</var>,
\r <strong>mach_port_t</strong> <var>exception_port</var>,
\r <strong>exception_behavior_t</strong> <var>behavior</var>,
\r <strong>thread_state_flavor_t</strong> <var>flavor</var>,
\r <strong>exception_mask_array_t</strong> <var>old_exception_masks</var>,
\r <strong>old_exception_masks</strong> <var>old_exception_count</var>,
\r <strong>exception_port_array_t</strong> <var>old_exception_ports</var>,
\r <strong>exception_behavior_array_t</strong> <var>old_behaviors</var>,
\r <strong>exception_flavor_array_t</strong> <var>old_flavors</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe task for which to set the ports.
\r<p>
\r<dt> <var>exception_types</var>
\r<dd>
\r[in scalar]
\rA flag word indicating the types of exceptions for which the
\rexception port applies:
\r<dl>
\r<p>
\r<dt> <strong>EXC_MASK_BAD_ACCESS</strong>
\r<dd>
\rCould not access memory.
\r<p>
\r<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
\r<dd>
\rInstruction failed. Illegal or undefined instruction or operand.
\r<p>
\r<dt> <strong>EXC_MASK_ARITHMETIC</strong>
\r<dd>
\rArithmetic exception
\r<p>
\r<dt> <strong>EXC_MASK_EMULATION</strong>
\r<dd>
\rEmulation instruction. Emulation support instruction
\rencountered.
\r<p>
\r<dt> <strong>EXC_MASK_SOFTWARE</strong>
\r<dd>
\rSoftware generated exception.
\r<p>
\r<dt> <strong>EXC_MASK_BREAKPOINT</strong>
\r<dd>
\rTrace, breakpoint, etc.
\r<p>
\r<dt> <strong>EXC_MASK_SYSCALL</strong>
\r<dd>
\rSystem call requested.
\r<p>
\r<dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
\r<dd>
\rSystem call with a number in the Mach call range requested.
\r<p>
\r<dt> <strong>EXC_MASK_RPC_ALERT </strong>
\r<dd>
\rExceptional condition encountered during execution of RPC.
\r</dl>
\r<p>
\r<dt> <var>exception_port</var>
\r<dd>
\r[in exception send right]
\rThe exception port for all selected exception
\rtypes.
\r<p>
\r<dt> <var>behavior</var>
\r<dd>
\r[in scalar]
\rThe type of exception message to be sent. Defined types are:
\r<dl>
\r<p>
\r<dt> <strong>EXCEPTION_DEFAULT</strong>
\r<dd>
\rSend a <strong>catch_exception_raise</strong> message including the thread
\ridentity.
\r<p>
\r<dt> <strong>EXCEPTION_STATE</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state</strong> message including the
\rthread state.
\r<p>
\r<dt> <strong>EXCEPTION_STATE_PROTECTED</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state</strong> message including the
\rthread state. Mark the exception port (and associated
\rexceptions) as protected.
\r<p>
\r<dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state_identity</strong> message
\rincluding the thread identity and state.
\r<p>
\r<dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state_identity</strong> message
\rincluding the thread identity and state. Mark the exception port
\r(and associated exceptions) as protected.
\r</dl>
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of state to be sent with the exception message.
\rThese types are defined in <strong><mach/thread_states.h></strong>.
\r<p>
\r<dt> <var>old_exception_masks</var>
\r<dd>
\r[out array of <var>exception_mask_t</var>]
\rAn array, each element being a mask
\rspecifying for which exception types the corresponding element of the
\rother arrays apply.
\r<p>
\r<dt> <var>old_exception_count</var>
\r<dd>
\r[pointer to in/out scalar]
\rOn input, the maximum size of the array
\rbuffers; on output, the number of returned <exception type mask,
\rexception port, behavior, flavor> sets returned.
\r<p>
\r<dt> <var>old_exception_ports</var>
\r<dd>
\r[out array of exception send rights]
\rThe returned exception ports.
\r<p>
\r<dt> <var>old_behaviors</var>
\r<dd>
\r[out array of <var>exception_behavior_t</var>]
\rThe type of exception message to
\rbe sent as with <var>behavior</var>.
\r<p>
\r<dt> <var>old_flavors</var>
\r<dd>
\r[out array of <var>thread_state_flavor_t</var>]
\rThe type of state to be sent with
\rthe exception message. These types are defined in <strong><mach/thread_states.h></strong>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_swap_exception_ports</strong> function sets a specified
\rset of exception
\rports belonging to <var>task</var>, returning the old set. A task exception
\rport is used when
\ra thread specific exception port returns a non-success reply.
\r<h3>NOTES</h3>
\r<p>
\rIf the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is
\rthe host name port, Mach kernel traps are executed by the kernel as expected;
\rany other value causes the attempted execution of these system call numbers to
\rbe considered an exception.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_task_self.html"><strong>mach_task_self</strong></a>,
\r<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
\r<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
\r<a href="thread_create.html"><strong>thread_create</strong></a>,
\r<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
\r<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
\r<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
\r<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>,
\r<a href="thread_abort.html"><strong>thread_abort</strong></a>.
\r\ No newline at end of file
+<h2>task_swap_exception_ports</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set target task's exception ports, returning the previous exception ports.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_swap_exception_ports</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>exception_mask_t</strong> <var>exception_types</var>,
+ <strong>mach_port_t</strong> <var>exception_port</var>,
+ <strong>exception_behavior_t</strong> <var>behavior</var>,
+ <strong>thread_state_flavor_t</strong> <var>flavor</var>,
+ <strong>exception_mask_array_t</strong> <var>old_exception_masks</var>,
+ <strong>old_exception_masks</strong> <var>old_exception_count</var>,
+ <strong>exception_port_array_t</strong> <var>old_exception_ports</var>,
+ <strong>exception_behavior_array_t</strong> <var>old_behaviors</var>,
+ <strong>exception_flavor_array_t</strong> <var>old_flavors</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The task for which to set the ports.
+<p>
+<dt> <var>exception_types</var>
+<dd>
+[in scalar]
+A flag word indicating the types of exceptions for which the
+exception port applies:
+<dl>
+<p>
+<dt> <strong>EXC_MASK_BAD_ACCESS</strong>
+<dd>
+Could not access memory.
+<p>
+<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
+<dd>
+Instruction failed. Illegal or undefined instruction or operand.
+<p>
+<dt> <strong>EXC_MASK_ARITHMETIC</strong>
+<dd>
+Arithmetic exception
+<p>
+<dt> <strong>EXC_MASK_EMULATION</strong>
+<dd>
+Emulation instruction. Emulation support instruction
+encountered.
+<p>
+<dt> <strong>EXC_MASK_SOFTWARE</strong>
+<dd>
+Software generated exception.
+<p>
+<dt> <strong>EXC_MASK_BREAKPOINT</strong>
+<dd>
+Trace, breakpoint, etc.
+<p>
+<dt> <strong>EXC_MASK_SYSCALL</strong>
+<dd>
+System call requested.
+<p>
+<dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
+<dd>
+System call with a number in the Mach call range requested.
+<p>
+<dt> <strong>EXC_MASK_RPC_ALERT </strong>
+<dd>
+Exceptional condition encountered during execution of RPC.
+</dl>
+<p>
+<dt> <var>exception_port</var>
+<dd>
+[in exception send right]
+The exception port for all selected exception
+types.
+<p>
+<dt> <var>behavior</var>
+<dd>
+[in scalar]
+The type of exception message to be sent. Defined types are:
+<dl>
+<p>
+<dt> <strong>EXCEPTION_DEFAULT</strong>
+<dd>
+Send a <strong>catch_exception_raise</strong> message including the thread
+identity.
+<p>
+<dt> <strong>EXCEPTION_STATE</strong>
+<dd>
+Send a <strong>catch_exception_raise_state</strong> message including the
+thread state.
+<p>
+<dt> <strong>EXCEPTION_STATE_PROTECTED</strong>
+<dd>
+Send a <strong>catch_exception_raise_state</strong> message including the
+thread state. Mark the exception port (and associated
+exceptions) as protected.
+<p>
+<dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
+<dd>
+Send a <strong>catch_exception_raise_state_identity</strong> message
+including the thread identity and state.
+<p>
+<dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong>
+<dd>
+Send a <strong>catch_exception_raise_state_identity</strong> message
+including the thread identity and state. Mark the exception port
+(and associated exceptions) as protected.
+</dl>
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of state to be sent with the exception message.
+These types are defined in <strong><mach/thread_states.h></strong>.
+<p>
+<dt> <var>old_exception_masks</var>
+<dd>
+[out array of <var>exception_mask_t</var>]
+An array, each element being a mask
+specifying for which exception types the corresponding element of the
+other arrays apply.
+<p>
+<dt> <var>old_exception_count</var>
+<dd>
+[pointer to in/out scalar]
+On input, the maximum size of the array
+buffers; on output, the number of returned <exception type mask,
+exception port, behavior, flavor> sets returned.
+<p>
+<dt> <var>old_exception_ports</var>
+<dd>
+[out array of exception send rights]
+The returned exception ports.
+<p>
+<dt> <var>old_behaviors</var>
+<dd>
+[out array of <var>exception_behavior_t</var>]
+The type of exception message to
+be sent as with <var>behavior</var>.
+<p>
+<dt> <var>old_flavors</var>
+<dd>
+[out array of <var>thread_state_flavor_t</var>]
+The type of state to be sent with
+the exception message. These types are defined in <strong><mach/thread_states.h></strong>.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_swap_exception_ports</strong> function sets a specified
+set of exception
+ports belonging to <var>task</var>, returning the old set. A task exception
+port is used when
+a thread specific exception port returns a non-success reply.
+<h3>NOTES</h3>
+<p>
+If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is
+the host name port, Mach kernel traps are executed by the kernel as expected;
+any other value causes the attempted execution of these system call numbers to
+be considered an exception.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_task_self.html"><strong>mach_task_self</strong></a>,
+<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
+<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
+<a href="thread_create.html"><strong>thread_create</strong></a>,
+<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
+<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
+<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
+<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>,
+<a href="thread_abort.html"><strong>thread_abort</strong></a>.
-<h2>task_terminate</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Terminate the target task and deallocate its resources.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_terminate</strong>
\r <strong>(task_t</strong> <var>task</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe port for the task to be destroyed.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_terminate</strong> function kills task and all its
\rthreads, if any. The kernel
\rfrees all resources that are in use by the task. The kernel
\rdestroys any port for
\rwhich the task holds the receive right.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_create.html"><strong>task_create</strong></a>,
\r<a href="task_suspend.html"><strong>task_suspend</strong></a>,
\r<a href="task_resume.html"><strong>task_resume</strong></a>,
\r<a href="thread_terminate.html"><strong>thread_terminate</strong></a>,
\r<a href="thread_suspend.html"><strong>thread_suspend</strong></a>.
\r\ No newline at end of file
+<h2>task_terminate</h2>
+<hr>
+<p>
+<strong>Function</strong> - Terminate the target task and deallocate its resources.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_terminate</strong>
+ <strong>(task_t</strong> <var>task</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The port for the task to be destroyed.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_terminate</strong> function kills task and all its
+threads, if any. The kernel
+frees all resources that are in use by the task. The kernel
+destroys any port for
+which the task holds the receive right.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_create.html"><strong>task_create</strong></a>,
+<a href="task_suspend.html"><strong>task_suspend</strong></a>,
+<a href="task_resume.html"><strong>task_resume</strong></a>,
+<a href="thread_terminate.html"><strong>thread_terminate</strong></a>,
+<a href="thread_suspend.html"><strong>thread_suspend</strong></a>.
-<h2>task_thread_times_info</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Defines thread execution times information for tasks.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct task_thread_times_info</strong>
\r<strong>{</strong>
\r <strong>time_value_t</strong> <var>user_time</var><strong>;</strong>
\r <strong>time_value_t</strong> <var>system_time</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct task_thread_times_info* task_thread_times_info_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r <p>
\r<dt> <var>user_time</var>
\r<dd>
\rTotal user run time for live threads.
\r <p>
\r<dt> <var>system_time</var>
\r<dd>
\rTotal system run time for live threads.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_thread_times_info</strong> structure defines thread
\rexecution time statistics
\rfor tasks. The <strong>task_info</strong> function returns these times
\rfor a specified task. The
\r<strong>thread_info</strong> function returns this information for a specific thread.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_info.html"><strong>task_info</strong></a>,
\r<a href="thread_info.html"><strong>thread_info</strong></a>.
\r<p>
\rData Structures:
\r<a href="task_basic_info.html"><strong>task_basic_info</strong></a>,
\r<a href="thread_basic_info.html"><strong>thread_basic_info</strong></a>.
\r\ No newline at end of file
+<h2>task_thread_times_info</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Defines thread execution times information for tasks.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct task_thread_times_info</strong>
+<strong>{</strong>
+ <strong>time_value_t</strong> <var>user_time</var><strong>;</strong>
+ <strong>time_value_t</strong> <var>system_time</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct task_thread_times_info* task_thread_times_info_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+ <p>
+<dt> <var>user_time</var>
+<dd>
+Total user run time for live threads.
+ <p>
+<dt> <var>system_time</var>
+<dd>
+Total system run time for live threads.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_thread_times_info</strong> structure defines thread
+execution time statistics
+for tasks. The <strong>task_info</strong> function returns these times
+for a specified task. The
+<strong>thread_info</strong> function returns this information for a specific thread.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_info.html"><strong>task_info</strong></a>,
+<a href="thread_info.html"><strong>thread_info</strong></a>.
+<p>
+Data Structures:
+<a href="task_basic_info.html"><strong>task_basic_info</strong></a>,
+<a href="thread_basic_info.html"><strong>thread_basic_info</strong></a>.
-<h2>task_threads</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return the target task's list of threads.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t task_threads</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>thread_act_port_array_t</strong> <var>thread_list</var>,
\r <strong>mach_msg_type_number_t*</strong> <var>thread_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right]
\rThe port for the task for which the thread list is to
\rbe returned.
\r<p>
\r<dt> <var>thread_list</var>
\r<dd>
\r[out pointer to dynamic array of thread send rights]
\rThe returned list of
\rthreads within <var>task</var>, in no particular order.
\r<p>
\r<dt> <var>thread_count</var>
\r<dd>
\r[out scalar]
\rThe returned count of threads in <var>thread_list</var>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>task_threads</strong> function returns a list of the threads
\rwithin <var>task</var>. The calling
\rtask or thread also receives a send right to the kernel port
\rfor each listed thread.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="thread_create.html"><strong>thread_create</strong></a>,
\r<a href="thread_terminate.html"><strong>thread_terminate</strong></a>,
\r<a href="thread_suspend.html"><strong>thread_suspend</strong></a>.
\r\ No newline at end of file
+<h2>task_threads</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return the target task's list of threads.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t task_threads</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>thread_act_port_array_t</strong> <var>thread_list</var>,
+ <strong>mach_msg_type_number_t*</strong> <var>thread_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right]
+The port for the task for which the thread list is to
+be returned.
+<p>
+<dt> <var>thread_list</var>
+<dd>
+[out pointer to dynamic array of thread send rights]
+The returned list of
+threads within <var>task</var>, in no particular order.
+<p>
+<dt> <var>thread_count</var>
+<dd>
+[out scalar]
+The returned count of threads in <var>thread_list</var>.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>task_threads</strong> function returns a list of the threads
+within <var>task</var>. The calling
+task or thread also receives a send right to the kernel port
+for each listed thread.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="thread_create.html"><strong>thread_create</strong></a>,
+<a href="thread_terminate.html"><strong>thread_terminate</strong></a>,
+<a href="thread_suspend.html"><strong>thread_suspend</strong></a>.
-<h2>thread_abort</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Abort a thread.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_abort</strong>
\r <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_thread</var>
\r<dd>
\r[in thread send right]
\rThe thread to be aborted.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_abort</strong> function aborts page faults and any
\rmessage primitive calls
\rin use by <var>target_thread</var>. Scheduling depressions and clock sleeps are also
\raborted. The call returns a code indicating that it was interrupted.
\rThe call is
\rinterrupted even if the thread (or the task containing it) is
\rsuspended. If it is
\rsuspended, the thread receives the interrupt when it resumes.
\r<p>
\rIf its state is not modified before it resumes, the thread will
\rretry an aborted
\rpage fault. The Mach message trap returns either
\r<strong>MACH_SEND_INTERRUPTED</strong> or <strong>MACH_RCV_INTERRUPTED</strong>, depending
\ron whether the send or the
\rreceive side was interrupted. Note, though, that the Mach message trap is
\rcontained within the <strong>mach_msg</strong> library routine, which,
\rby default, retries
\rinterrupted message calls.
\r<p>
\rThe basic purpose of <strong>thread_abort</strong> is to let one thread
\rcleanly stop another thread (<var>target_thread</var>).
\rThe target thread is stopped in such a manner that its
\rfuture execution can be controlled in a predictable way. When
\r<strong>thread_abort</strong>
\rreturns, the target thread will appear to have just returned
\rfrom the kernel (if it
\rhad been in kernel mode).
\r<h3>NOTES</h3>
\r<p>
\rBy way of comparison, the <strong>thread_suspend</strong> function keeps
\rthe target thread
\rfrom executing any further instructions at the user level, including
\rthe return
\rfrom a system call. The <strong>thread_get_state</strong> function
\rreturns the thread's user
\rstate, while <strong>thread_set_state</strong> allows modification of the user state.
\r<p>
\rA problem occurs if a suspended thread had been executing within a system
\rcall. In this case, the thread has, not only a user state, but
\ran associated kernel
\rstate. (The kernel state cannot be changed with <strong>thread_set_state</strong>.)
\rAs a result,
\rwhen the thread resumes, the system call can return, producing a change in the
\ruser state and, possibly, user memory.
\r<p>
\rFor a thread executing within a system call, <strong>thread_abort</strong>
\raborts the kernel call
\rfrom the thread's point of view. Specifically, it resets the
\rkernel state so that the
\rthread will resume execution at the system call return, with the return code
\rvalue set to one of the interrupted codes. The system call itself
\rmay be completed
\rentirely, aborted entirely or be partially completed, depending on when the
\rabort is received. As a result, if the thread's user state has
\rbeen modified by
\r<strong>thread_set_state</strong>, it will not be altered un-predictably
\rby any unexpected
\rsystem call side effects.
\r<p>
\rFor example, to simulate a POSIX signal, use the following sequence of calls:
\r<dl>
\r<dd>
\r<strong>thread_suspend</strong>\(emTo stop the thread.
\r<dd>
\r<strong>thread_abort</strong>\(emTo interrupt any system call in progress
\rand set the return
\rvalue to "interrupted". Because the thread is already stopped, it will not
\rreturn to user code.
\r<dd>
\r<strong>thread_set_state</strong>\(emTo modify the thread's user state to simulate a
\rprocedure call to the signal handler.
\r<dd>
\r<strong>thread_resume</strong>\(emTo resume execution at the signal handler.
\rIf the thread's
\rstack is set up correctly, the thread can return to the interrupted system call.
\rNote that the code to push an extra stack frame and change the registers is
\rhighly machine dependent.
\r</dl>
\r<h3>CAUTIONS</h3>
\r<p>
\rAs a rule, do not use <strong>thread_abort</strong> on a non-suspended
\rthread. This operation
\ris very risky because it is difficult to know which system trap, if any, is
\rexecuting and whether an interrupt return will result in some
\ruseful action by the
\rthread.
\r<p>
\r<strong>thread_abort</strong> will abort any non-atomic operation (such as a multi-page
\r<strong>memory_object_data_supply</strong>) at an arbitrary point in a non-restartable
\rway. Such problems can be avoided by using <strong>thread_abort_safely</strong>.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_EXCEPTION_PROTECTED</strong>
\r<dd>
\rThe thread is processing a protected exception.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>,
\r<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
\r<a href="thread_info.html"><strong>thread_info</strong></a>,
\r<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
\r<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
\r<a href="thread_terminate.html"><strong>thread_terminate</strong></a>,
\r<a href="thread_abort_safely.html"><strong>thread_abort_safely</strong></a>,
\r<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>.
\r\ No newline at end of file
+<h2>thread_abort</h2>
+<hr>
+<p>
+<strong>Function</strong> - Abort a thread.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_abort</strong>
+ <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_thread</var>
+<dd>
+[in thread send right]
+The thread to be aborted.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_abort</strong> function aborts page faults and any
+message primitive calls
+in use by <var>target_thread</var>. Scheduling depressions and clock sleeps are also
+aborted. The call returns a code indicating that it was interrupted.
+The call is
+interrupted even if the thread (or the task containing it) is
+suspended. If it is
+suspended, the thread receives the interrupt when it resumes.
+<p>
+If its state is not modified before it resumes, the thread will
+retry an aborted
+page fault. The Mach message trap returns either
+<strong>MACH_SEND_INTERRUPTED</strong> or <strong>MACH_RCV_INTERRUPTED</strong>, depending
+on whether the send or the
+receive side was interrupted. Note, though, that the Mach message trap is
+contained within the <strong>mach_msg</strong> library routine, which,
+by default, retries
+interrupted message calls.
+<p>
+The basic purpose of <strong>thread_abort</strong> is to let one thread
+cleanly stop another thread (<var>target_thread</var>).
+The target thread is stopped in such a manner that its
+future execution can be controlled in a predictable way. When
+<strong>thread_abort</strong>
+returns, the target thread will appear to have just returned
+from the kernel (if it
+had been in kernel mode).
+<h3>NOTES</h3>
+<p>
+By way of comparison, the <strong>thread_suspend</strong> function keeps
+the target thread
+from executing any further instructions at the user level, including
+the return
+from a system call. The <strong>thread_get_state</strong> function
+returns the thread's user
+state, while <strong>thread_set_state</strong> allows modification of the user state.
+<p>
+A problem occurs if a suspended thread had been executing within a system
+call. In this case, the thread has, not only a user state, but
+an associated kernel
+state. (The kernel state cannot be changed with <strong>thread_set_state</strong>.)
+As a result,
+when the thread resumes, the system call can return, producing a change in the
+user state and, possibly, user memory.
+<p>
+For a thread executing within a system call, <strong>thread_abort</strong>
+aborts the kernel call
+from the thread's point of view. Specifically, it resets the
+kernel state so that the
+thread will resume execution at the system call return, with the return code
+value set to one of the interrupted codes. The system call itself
+may be completed
+entirely, aborted entirely or be partially completed, depending on when the
+abort is received. As a result, if the thread's user state has
+been modified by
+<strong>thread_set_state</strong>, it will not be altered un-predictably
+by any unexpected
+system call side effects.
+<p>
+For example, to simulate a POSIX signal, use the following sequence of calls:
+<dl>
+<dd>
+<strong>thread_suspend</strong>\(emTo stop the thread.
+<dd>
+<strong>thread_abort</strong>\(emTo interrupt any system call in progress
+and set the return
+value to "interrupted". Because the thread is already stopped, it will not
+return to user code.
+<dd>
+<strong>thread_set_state</strong>\(emTo modify the thread's user state to simulate a
+procedure call to the signal handler.
+<dd>
+<strong>thread_resume</strong>\(emTo resume execution at the signal handler.
+If the thread's
+stack is set up correctly, the thread can return to the interrupted system call.
+Note that the code to push an extra stack frame and change the registers is
+highly machine dependent.
+</dl>
+<h3>CAUTIONS</h3>
+<p>
+As a rule, do not use <strong>thread_abort</strong> on a non-suspended
+thread. This operation
+is very risky because it is difficult to know which system trap, if any, is
+executing and whether an interrupt return will result in some
+useful action by the
+thread.
+<p>
+<strong>thread_abort</strong> will abort any non-atomic operation (such as a multi-page
+<strong>memory_object_data_supply</strong>) at an arbitrary point in a non-restartable
+way. Such problems can be avoided by using <strong>thread_abort_safely</strong>.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_EXCEPTION_PROTECTED</strong>
+<dd>
+The thread is processing a protected exception.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_msg.html"><strong>mach_msg</strong></a>,
+<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
+<a href="thread_info.html"><strong>thread_info</strong></a>,
+<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
+<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
+<a href="thread_terminate.html"><strong>thread_terminate</strong></a>,
+<a href="thread_abort_safely.html"><strong>thread_abort_safely</strong></a>,
+<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>.
-<h2>thread_abort_safely</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Abort a thread, restartably.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_abort_safely</strong>
\r <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_thread</var>
\r<dd>
\r[in thread send right]
\rThe thread to be aborted.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_abort_safely</strong> function aborts page faults and any message
\rprimitive calls in use by <var>target_thread</var>. Scheduling depressions
\rand clock sleeps are
\ralso aborted. The call returns a code indicating that it was
\rinterrupted. The call
\ris interrupted even if the thread (or the task containing it)
\ris suspended. If it is
\rsuspended, the thread receives the interrupt when it resumes.
\r<p>
\rIf its state is not modified before it resumes, the thread will
\rretry an aborted
\rpage fault. The Mach message trap returns either
\r<strong>MACH_SEND_INTERRUPTED</strong> or <strong>MACH_RCV_INTERRUPTED</strong>, depending
\ron whether the send or the
\rreceive side was interrupted. Note, though, that the Mach message trap is
\rcontained within the <strong>mach_msg</strong> library routine, which,
\rby default, retries
\rinterrupted message calls.
\r<p>
\rThe basic purpose of <strong>thread_abort_safely</strong> is to let
\rone thread cleanly stop
\ranother thread (<var>target_thread</var>). The target thread is stopped
\rin such a manner that
\rits future execution can be controlled in a predictable way. When
\r<strong>thread_abort_safely</strong> returns (if successful), the target
\rthread will appear to have just
\rreturned from the kernel (if it had been in kernel mode).
\r<h3>NOTES</h3>
\r<p>
\rBy way of comparison, the <strong>thread_suspend</strong> function keeps
\rthe target thread
\rfrom executing any further instructions at the user level, including
\rthe return
\rfrom a system call. The <strong>thread_get_state</strong> function
\rreturns the thread's user
\rstate, while <strong>thread_set_state</strong> allows modification of the user state.
\r<p>
\rA problem occurs if a suspended thread had been executing within a system
\rcall. In this case, the thread has, not only a user state, but
\ran associated kernel
\rstate. (The kernel state cannot be changed with <strong>thread_set_state</strong>.)
\rAs a result,
\rwhen the thread resumes, the system call can return, producing a change in the
\ruser state and, possibly, user memory.
\r<p>
\rFor a thread executing within a system call, <strong>thread_abort_safely</strong>
\raborts the
\rkernel call from the thread's point of view. Specifically, it
\rresets the kernel state so
\rthat the thread will resume execution at the system call return,
\rwith the return
\rcode value set to one of the interrupted codes. The system call itself may
\rcompleted entirely, aborted entirely or be partially completed,
\rdepending on when
\rthe abort is received. As a result, if the thread's user state
\rhas been modified by
\r<strong>thread_set_state</strong>, it will not be altered un-predictably
\rby any unexpected
\rsystem call side effects.
\r<p>
\rFor example, to simulate a POSIX signal, use the following sequence of calls:
\r<dl>
\r<dd>
\r<strong>thread_suspend</strong>\(emTo stop the thread.
\r<dd>
\r<strong>thread_abort_safely</strong>\(emTo interrupt any system call in
\rprogress and set the
\rreturn value to "interrupted". Because the thread is already stopped, it will
\rnot return to user code.
\r<dd>
\r<strong>thread_set_state</strong>\(emTo modify the thread's user state to simulate a
\rprocedure call to the signal handler.
\r<dd>
\r<strong>thread_resume</strong>\(emTo resume execution at the signal handler.
\rIf the thread's
\rstack is set up correctly, the thread can return to the interrupted
\rsystem call.
\rNote that the code to push an extra stack frame and change the registers is
\rhighly machine dependent.
\r</dl>
\r<h3>CAUTIONS</h3>
\r<p>
\rAs a rule, do not use <strong>thread_abort_safely</strong> on a non-suspended
\rthread. This
\roperation is very risky because it is difficult to know which
\rsystem trap, if any, is
\rexecuting and whether an interrupt return will result in some useful action by
\rthe thread.
\r<p>
\r<strong>thread_abort_safely</strong> will not abort any non-atomic operation
\r(such as a
\rmulti-page <strong>memory_object_data_supply</strong> or exception processing)
\rbut will return an
\rerror instead. The caller of this function must then allow the
\rthread to resume
\rand attempt to abort it later. If the thread must be aborted,
\reven if doing so
\rwould abort any non-atomic operations, <strong>thread_abort</strong> would be used.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_FAILURE</strong>
\r<dd>
\rThe thread is in the middle of a non-restartable operation.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>,
\r<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
\r<a href="thread_info.html"><strong>thread_info</strong></a>,
\r<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
\r<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
\r<a href="thread_terminate.html"><strong>thread_terminate</strong></a>,
\r<a href="thread_abort.html"><strong>thread_abort</strong></a>.
\r\ No newline at end of file
+<h2>thread_abort_safely</h2>
+<hr>
+<p>
+<strong>Function</strong> - Abort a thread, restartably.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_abort_safely</strong>
+ <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_thread</var>
+<dd>
+[in thread send right]
+The thread to be aborted.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_abort_safely</strong> function aborts page faults and any message
+primitive calls in use by <var>target_thread</var>. Scheduling depressions
+and clock sleeps are
+also aborted. The call returns a code indicating that it was
+interrupted. The call
+is interrupted even if the thread (or the task containing it)
+is suspended. If it is
+suspended, the thread receives the interrupt when it resumes.
+<p>
+If its state is not modified before it resumes, the thread will
+retry an aborted
+page fault. The Mach message trap returns either
+<strong>MACH_SEND_INTERRUPTED</strong> or <strong>MACH_RCV_INTERRUPTED</strong>, depending
+on whether the send or the
+receive side was interrupted. Note, though, that the Mach message trap is
+contained within the <strong>mach_msg</strong> library routine, which,
+by default, retries
+interrupted message calls.
+<p>
+The basic purpose of <strong>thread_abort_safely</strong> is to let
+one thread cleanly stop
+another thread (<var>target_thread</var>). The target thread is stopped
+in such a manner that
+its future execution can be controlled in a predictable way. When
+<strong>thread_abort_safely</strong> returns (if successful), the target
+thread will appear to have just
+returned from the kernel (if it had been in kernel mode).
+<h3>NOTES</h3>
+<p>
+By way of comparison, the <strong>thread_suspend</strong> function keeps
+the target thread
+from executing any further instructions at the user level, including
+the return
+from a system call. The <strong>thread_get_state</strong> function
+returns the thread's user
+state, while <strong>thread_set_state</strong> allows modification of the user state.
+<p>
+A problem occurs if a suspended thread had been executing within a system
+call. In this case, the thread has, not only a user state, but
+an associated kernel
+state. (The kernel state cannot be changed with <strong>thread_set_state</strong>.)
+As a result,
+when the thread resumes, the system call can return, producing a change in the
+user state and, possibly, user memory.
+<p>
+For a thread executing within a system call, <strong>thread_abort_safely</strong>
+aborts the
+kernel call from the thread's point of view. Specifically, it
+resets the kernel state so
+that the thread will resume execution at the system call return,
+with the return
+code value set to one of the interrupted codes. The system call itself may
+completed entirely, aborted entirely or be partially completed,
+depending on when
+the abort is received. As a result, if the thread's user state
+has been modified by
+<strong>thread_set_state</strong>, it will not be altered un-predictably
+by any unexpected
+system call side effects.
+<p>
+For example, to simulate a POSIX signal, use the following sequence of calls:
+<dl>
+<dd>
+<strong>thread_suspend</strong>\(emTo stop the thread.
+<dd>
+<strong>thread_abort_safely</strong>\(emTo interrupt any system call in
+progress and set the
+return value to "interrupted". Because the thread is already stopped, it will
+not return to user code.
+<dd>
+<strong>thread_set_state</strong>\(emTo modify the thread's user state to simulate a
+procedure call to the signal handler.
+<dd>
+<strong>thread_resume</strong>\(emTo resume execution at the signal handler.
+If the thread's
+stack is set up correctly, the thread can return to the interrupted
+system call.
+Note that the code to push an extra stack frame and change the registers is
+highly machine dependent.
+</dl>
+<h3>CAUTIONS</h3>
+<p>
+As a rule, do not use <strong>thread_abort_safely</strong> on a non-suspended
+thread. This
+operation is very risky because it is difficult to know which
+system trap, if any, is
+executing and whether an interrupt return will result in some useful action by
+the thread.
+<p>
+<strong>thread_abort_safely</strong> will not abort any non-atomic operation
+(such as a
+multi-page <strong>memory_object_data_supply</strong> or exception processing)
+but will return an
+error instead. The caller of this function must then allow the
+thread to resume
+and attempt to abort it later. If the thread must be aborted,
+even if doing so
+would abort any non-atomic operations, <strong>thread_abort</strong> would be used.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_FAILURE</strong>
+<dd>
+The thread is in the middle of a non-restartable operation.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_msg.html"><strong>mach_msg</strong></a>,
+<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
+<a href="thread_info.html"><strong>thread_info</strong></a>,
+<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
+<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
+<a href="thread_terminate.html"><strong>thread_terminate</strong></a>,
+<a href="thread_abort.html"><strong>thread_abort</strong></a>.
-<h2>thread_activation_create</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Create a thread activation.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_activation_create</strong>
\r <strong>(task_t</strong> <var>task</var>,
\r <strong>mach_port_name_t</strong> <var>RPC_port</var>,
\r <strong>vm_offset_t</strong> <var>user_stack</var>,
\r <strong>vm_size_t</strong> <var>stack_size</var>,
\r <strong>thread_act_t</strong> <var>thread_act_t</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>task</var>
\r<dd>
\r[in task send right] The port for the task that is to contain the new
\rthread activation.
\r<p>
\r<dt> <var>RPC_port</var>
\r<dd>
\r[in receive right] A receive right held by the task, or a port set in the
\rtask.
\r<p>
\r<dt> <var>user_stack</var>
\r<dd>
\r[in scalar] The virtual address in the task to be used as the starting ad-
\rdress of the user-level stack.
\r<p>
\r<dt> <var>new_act</var>
\r<dd>
\r[out thread send right] The kernel-assigned name for the new thread ac-
\rtivation.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe thread_activation_create function creates a thread activation, or
\r"empty thread", into which a client thread shuttle can migrate during
\rRPC. The RPC_port must name ei- ther a receive right held by the
\rtask, or a port set in the task. The new thread activation will be
\radded to a pool of activations attached to this port (or port set).
\rIncoming RPC's targeted at the port (or one of the ports in the set)
\rcan use any of the activations in the pool. That is, the client
\rthread shuttle will migrate into the specified server task, take one
\rof the thread activations out of the pool, and join up with it for the
\rduration of the RPC. The shuttle will migrate back to the original
\rclient activation at the end of the RPC. If no thread activations are
\rin the pool, RPC will be blocked until one is created in the pool, or
\ran existing one finishes its RPC and returns to the pool.
\rThe new thread activation will begin each RPC using the stack pointer
\rspecified by user_stack. The kernel neither knows nor cares how big
\rthe specified stack is.
\rWhen a short-circuited RPC (or mach_rpc) is invoked on a port created
\rwith mach_port_allocate_subsystem, the RPC will begin execution in the
\rsubsystem server at the work function address specified by the port
\rand routine number and looked up in the associated subsystem data.
\r<h3>NOTES</h3>
\r<p>
\rThe following calls targeted at a thread_act port may _not_ be called
\ron an empty thread_act (and will return KERN_INVALID_ARGUMENT if
\rthey are called with one):
\rthread_abort
\rthread_abort_safely
\rthread_depress_abort
\rthread_info
\rthread_wire
\rIn addition, if thread_switch is called with an empty thread_act as
\rits first argument, the argument will be ignored (i.e., the function
\rwill behave as if a zero-valued argument had been given).
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_create.html"><strong>task_create</strong></a>,
\r<a href="MP_allocate_subsystem.html"><strong>mach_port_allocate_subsystem</strong></a>,
\r\ No newline at end of file
+<h2>thread_activation_create</h2>
+<hr>
+<p>
+<strong>Function</strong> - Create a thread activation.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_activation_create</strong>
+ <strong>(task_t</strong> <var>task</var>,
+ <strong>mach_port_name_t</strong> <var>RPC_port</var>,
+ <strong>vm_offset_t</strong> <var>user_stack</var>,
+ <strong>vm_size_t</strong> <var>stack_size</var>,
+ <strong>thread_act_t</strong> <var>thread_act_t</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>task</var>
+<dd>
+[in task send right] The port for the task that is to contain the new
+thread activation.
+<p>
+<dt> <var>RPC_port</var>
+<dd>
+[in receive right] A receive right held by the task, or a port set in the
+task.
+<p>
+<dt> <var>user_stack</var>
+<dd>
+[in scalar] The virtual address in the task to be used as the starting ad-
+dress of the user-level stack.
+<p>
+<dt> <var>new_act</var>
+<dd>
+[out thread send right] The kernel-assigned name for the new thread ac-
+tivation.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The thread_activation_create function creates a thread activation, or
+"empty thread", into which a client thread shuttle can migrate during
+RPC. The RPC_port must name ei- ther a receive right held by the
+task, or a port set in the task. The new thread activation will be
+added to a pool of activations attached to this port (or port set).
+Incoming RPC's targeted at the port (or one of the ports in the set)
+can use any of the activations in the pool. That is, the client
+thread shuttle will migrate into the specified server task, take one
+of the thread activations out of the pool, and join up with it for the
+duration of the RPC. The shuttle will migrate back to the original
+client activation at the end of the RPC. If no thread activations are
+in the pool, RPC will be blocked until one is created in the pool, or
+an existing one finishes its RPC and returns to the pool.
+The new thread activation will begin each RPC using the stack pointer
+specified by user_stack. The kernel neither knows nor cares how big
+the specified stack is.
+When a short-circuited RPC (or mach_rpc) is invoked on a port created
+with mach_port_allocate_subsystem, the RPC will begin execution in the
+subsystem server at the work function address specified by the port
+and routine number and looked up in the associated subsystem data.
+<h3>NOTES</h3>
+<p>
+The following calls targeted at a thread_act port may _not_ be called
+on an empty thread_act (and will return KERN_INVALID_ARGUMENT if
+they are called with one):
+thread_abort
+thread_abort_safely
+thread_depress_abort
+thread_info
+thread_wire
+In addition, if thread_switch is called with an empty thread_act as
+its first argument, the argument will be ignored (i.e., the function
+will behave as if a zero-valued argument had been given).
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_create.html"><strong>task_create</strong></a>,
+<a href="MP_allocate_subsystem.html"><strong>mach_port_allocate_subsystem</strong></a>,
-<h2>thread_assign</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Assign a thread to a processor set.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_assign</strong>
\r <strong>(thread_act_t</strong> <var>thread</var>,
\r <strong>processor_set_t</strong> <var>processor_set</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>thread</var>
\r<dd>
\r[in thread send right]
\rThe thread to be assigned.
\r<p>
\r<dt> <var>processor_set</var>
\r<dd>
\r[in processor-set-control send right]
\rThe control port for the processor
\rset into which the thread is to be assigned.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_assign</strong> function assigns <strong>thread</strong> to the set
\r<var>processor_set</var>. After the
\rassignment is completed, the thread executes only on processors
\rthat are assigned
\rto that processor set. Any previous assignment of the thread is nullified.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="thread_assign_default.html"><strong>thread_assign_default</strong></a>,
\r<a href="thread_get_assignment.html"><strong>thread_get_assignment</strong></a>,
\r<a href="processor_set_create.html"><strong>processor_set_create</strong></a>,
\r<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
\r<a href="task_assign.html"><strong>task_assign</strong></a>.
\r\ No newline at end of file
+<h2>thread_assign</h2>
+<hr>
+<p>
+<strong>Function</strong> - Assign a thread to a processor set.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_assign</strong>
+ <strong>(thread_act_t</strong> <var>thread</var>,
+ <strong>processor_set_t</strong> <var>processor_set</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>thread</var>
+<dd>
+[in thread send right]
+The thread to be assigned.
+<p>
+<dt> <var>processor_set</var>
+<dd>
+[in processor-set-control send right]
+The control port for the processor
+set into which the thread is to be assigned.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_assign</strong> function assigns <strong>thread</strong> to the set
+<var>processor_set</var>. After the
+assignment is completed, the thread executes only on processors
+that are assigned
+to that processor set. Any previous assignment of the thread is nullified.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="thread_assign_default.html"><strong>thread_assign_default</strong></a>,
+<a href="thread_get_assignment.html"><strong>thread_get_assignment</strong></a>,
+<a href="processor_set_create.html"><strong>processor_set_create</strong></a>,
+<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
+<a href="task_assign.html"><strong>task_assign</strong></a>.
-<h2>thread_assign_default</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Assign a thread to the default processor set.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_assign_default</strong>
\r <strong>(thread_act_t</strong> <var>thread</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>thread</var>
\r<dd>
\r[in thread send right]
\rThe thread to be assigned.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_assign_default</strong> function assigns <var>thread</var> to
\rthe default processor set.
\rAfter the assignment is completed, the thread executes only on processors that
\rare assigned to that processor set. Any previous assignment of the thread is
\rnullified.
\r<h3>NOTES</h3>
\r<p>
\rThis variant of <strong>thread_assign</strong> exists because the control
\rport for the default
\rprocessor set is privileged, and therefore not available to most tasks.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="thread_assign.html"><strong>thread_assign</strong></a>,
\r<a href="thread_get_assignment.html"><strong>thread_get_assignment</strong></a>,
\r<a href="processor_set_create.html"><strong>processor_set_create</strong></a>,
\r<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
\r<a href="task_assign.html"><strong>task_assign</strong></a>.
\r\ No newline at end of file
+<h2>thread_assign_default</h2>
+<hr>
+<p>
+<strong>Function</strong> - Assign a thread to the default processor set.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_assign_default</strong>
+ <strong>(thread_act_t</strong> <var>thread</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>thread</var>
+<dd>
+[in thread send right]
+The thread to be assigned.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_assign_default</strong> function assigns <var>thread</var> to
+the default processor set.
+After the assignment is completed, the thread executes only on processors that
+are assigned to that processor set. Any previous assignment of the thread is
+nullified.
+<h3>NOTES</h3>
+<p>
+This variant of <strong>thread_assign</strong> exists because the control
+port for the default
+processor set is privileged, and therefore not available to most tasks.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="thread_assign.html"><strong>thread_assign</strong></a>,
+<a href="thread_get_assignment.html"><strong>thread_get_assignment</strong></a>,
+<a href="processor_set_create.html"><strong>processor_set_create</strong></a>,
+<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
+<a href="task_assign.html"><strong>task_assign</strong></a>.
-<h2>thread_basic_info</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Defines basic information for a thread.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct thread_basic_info</strong>
\r<strong>{</strong>
\r <strong>time_value_t</strong> <var>user_time</var><strong>;</strong>
\r <strong>time_value_t</strong> <var>system_time</var><strong>;</strong>
\r <strong>integer_t</strong> <var>cpu_usage</var><strong>;</strong>
\r <strong>policy_t</strong> <var>policy</var><strong>;</strong>
\r <strong>integer_t</strong> <var>run_state</var><strong>;</strong>
\r <strong>integer_t</strong> <var>flags</var><strong>;</strong>
\r <strong>integer_t</strong> <var>suspend_count</var><strong>;</strong>
\r <strong>integer_t</strong> <var>sleep_time</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct thread_basic_info* thread_basic_info_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>user_time</var>
\r<dd>
\rThe total user run time for the thread.
\r <p>
\r<dt> <var>system_time</var>
\r<dd>
\rThe total system run time for the thread.
\r <p>
\r<dt> <var>cpu_usage</var>
\r<dd>
\rScaled <strong>CPU</strong> usage percentage for the thread.
\r <p>
\r<dt> <var>policy</var>
\r<dd>
\rScheduling policy in effect
\r <p>
\r<dt> <var>run_state</var>
\r<dd>
\rThe thread's run state. Possible values are:
\r<dl>
\r <p>
\r<dt> <strong>TH_STATE_RUNNING</strong>
\r<dd>
\rThe thread is running normally.
\r <p>
\r<dt> <strong>TH_STATE_STOPPED</strong>
\r<dd>
\rThe thread is stopped.
\r <p>
\r<dt> <strong>TH_STATE_WAITING</strong>
\r<dd>
\rThe thread is waiting normally.
\r <p>
\r<dt> <strong>TH_STATE_UNINTERRUPTIBLE</strong>
\r<dd>
\rThe thread is in an un-interruptible wait state.
\r <p>
\r<dt> <strong>TH_STATE_HALTED</strong>
\r<dd>
\rThe thread is halted at a clean point.
\r</dl>
\r <p>
\r<dt> <var>flags</var>
\r<dd>
\rSwap/idle flags for the thread. Possible values are:
\r<dl>
\r <p>
\r<dt> <strong>TH_FLAGS_SWAPPED</strong>
\r<dd>
\rThe thread is swapped out.
\r <p>
\r<dt> <strong>TH_FLAGS_IDLE</strong>
\r<dd>
\rThe thread is an idle thread.
\r</dl>
\r <p>
\r<dt> <var>suspend_count</var>
\r<dd>
\rThe current suspend count for the thread.
\r <p>
\r<dt> <var>sleep_time</var>
\r<dd>
\rThe number of seconds that the thread has been sleeping.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_basic_info</strong> structure defines the basic information
\rarray for threads.
\rThe <strong>thread_info</strong> function returns this array for a specified thread.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="thread_info.html"><strong>thread_info</strong></a>.
\r<p>
\rData Structures:
\r<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
\r<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>,
\r<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>.
\r\ No newline at end of file
+<h2>thread_basic_info</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Defines basic information for a thread.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct thread_basic_info</strong>
+<strong>{</strong>
+ <strong>time_value_t</strong> <var>user_time</var><strong>;</strong>
+ <strong>time_value_t</strong> <var>system_time</var><strong>;</strong>
+ <strong>integer_t</strong> <var>cpu_usage</var><strong>;</strong>
+ <strong>policy_t</strong> <var>policy</var><strong>;</strong>
+ <strong>integer_t</strong> <var>run_state</var><strong>;</strong>
+ <strong>integer_t</strong> <var>flags</var><strong>;</strong>
+ <strong>integer_t</strong> <var>suspend_count</var><strong>;</strong>
+ <strong>integer_t</strong> <var>sleep_time</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct thread_basic_info* thread_basic_info_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>user_time</var>
+<dd>
+The total user run time for the thread.
+ <p>
+<dt> <var>system_time</var>
+<dd>
+The total system run time for the thread.
+ <p>
+<dt> <var>cpu_usage</var>
+<dd>
+Scaled <strong>CPU</strong> usage percentage for the thread.
+ <p>
+<dt> <var>policy</var>
+<dd>
+Scheduling policy in effect
+ <p>
+<dt> <var>run_state</var>
+<dd>
+The thread's run state. Possible values are:
+<dl>
+ <p>
+<dt> <strong>TH_STATE_RUNNING</strong>
+<dd>
+The thread is running normally.
+ <p>
+<dt> <strong>TH_STATE_STOPPED</strong>
+<dd>
+The thread is stopped.
+ <p>
+<dt> <strong>TH_STATE_WAITING</strong>
+<dd>
+The thread is waiting normally.
+ <p>
+<dt> <strong>TH_STATE_UNINTERRUPTIBLE</strong>
+<dd>
+The thread is in an un-interruptible wait state.
+ <p>
+<dt> <strong>TH_STATE_HALTED</strong>
+<dd>
+The thread is halted at a clean point.
+</dl>
+ <p>
+<dt> <var>flags</var>
+<dd>
+Swap/idle flags for the thread. Possible values are:
+<dl>
+ <p>
+<dt> <strong>TH_FLAGS_SWAPPED</strong>
+<dd>
+The thread is swapped out.
+ <p>
+<dt> <strong>TH_FLAGS_IDLE</strong>
+<dd>
+The thread is an idle thread.
+</dl>
+ <p>
+<dt> <var>suspend_count</var>
+<dd>
+The current suspend count for the thread.
+ <p>
+<dt> <var>sleep_time</var>
+<dd>
+The number of seconds that the thread has been sleeping.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_basic_info</strong> structure defines the basic information
+array for threads.
+The <strong>thread_info</strong> function returns this array for a specified thread.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="thread_info.html"><strong>thread_info</strong></a>.
+<p>
+Data Structures:
+<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
+<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>,
+<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>.
-<h2>thread_create</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Create a thread within a task.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_create</strong>
\r <strong>(task_t</strong> <var>parent_task</var>,
\r <strong>thread_act_t</strong> <var>child_thread</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>parent_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task that is to contain the new
\rthread.
\r<p>
\r<dt> <var>child_thread</var>
\r<dd>
\r[out thread send right]
\rThe kernel-assigned name for the new thread.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_create</strong> function creates a new thread within
\r<var>parent_task</var>. The new thread has a suspend count of one and
\rno processor state.
\r<p>
\rThe new thread holds a send right for its thread kernel port.
\rA send right for the
\rthread's kernel port is also returned to the calling task or
\rthread in <var>child_thread</var>.
\rThe new thread's exception ports are set to <strong>MACH_PORT_NULL</strong>.
\r<h3>NOTES</h3>
\r<p>
\rTo get a new thread running, first use <strong>thread_set_state</strong>
\rto set a processor state
\rfor the thread. Then, use <strong>thread_resume</strong> to schedule
\rthe thread for execution.
\rAlternately, use <strong>thread_create_running</strong>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_create.html"><strong>task_create</strong></a>,
\r<a href="task_threads.html"><strong>task_threads</strong></a>,
\r<a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>,
\r<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
\r<a href="thread_resume.html"><strong>thread_resume</strong></a>,
\r<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>,
\r<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
\r<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
\r<a href="thread_terminate.html"><strong>thread_terminate</strong></a>,
\r<a href="thread_create_running.html"><strong>thread_create_running</strong></a>.
\r\ No newline at end of file
+<h2>thread_create</h2>
+<hr>
+<p>
+<strong>Function</strong> - Create a thread within a task.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_create</strong>
+ <strong>(task_t</strong> <var>parent_task</var>,
+ <strong>thread_act_t</strong> <var>child_thread</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>parent_task</var>
+<dd>
+[in task send right]
+The port for the task that is to contain the new
+thread.
+<p>
+<dt> <var>child_thread</var>
+<dd>
+[out thread send right]
+The kernel-assigned name for the new thread.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_create</strong> function creates a new thread within
+<var>parent_task</var>. The new thread has a suspend count of one and
+no processor state.
+<p>
+The new thread holds a send right for its thread kernel port.
+A send right for the
+thread's kernel port is also returned to the calling task or
+thread in <var>child_thread</var>.
+The new thread's exception ports are set to <strong>MACH_PORT_NULL</strong>.
+<h3>NOTES</h3>
+<p>
+To get a new thread running, first use <strong>thread_set_state</strong>
+to set a processor state
+for the thread. Then, use <strong>thread_resume</strong> to schedule
+the thread for execution.
+Alternately, use <strong>thread_create_running</strong>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_create.html"><strong>task_create</strong></a>,
+<a href="task_threads.html"><strong>task_threads</strong></a>,
+<a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>,
+<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
+<a href="thread_resume.html"><strong>thread_resume</strong></a>,
+<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>,
+<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
+<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
+<a href="thread_terminate.html"><strong>thread_terminate</strong></a>,
+<a href="thread_create_running.html"><strong>thread_create_running</strong></a>.
-<h2>thread_create_running</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Optimized creation of a running thread.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_create_running</strong>
\r <strong>(task_t</strong> <var>parent_task</var>,
\r <strong>thread_state_flavor_t</strong> <var>flavor</var>,
\r <strong>thread_state_t</strong> <var>state</var>,
\r <strong>thread_act_t</strong> <var>child_thread</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>parent_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task that is to contain the new
\rthread.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of state to establish. Valid values correspond to
\rsupported machine architecture features.
\r<p>
\r<dt> <var>state</var>
\r<dd>
\r[pointer to in structure]
\rState information for the specified thread.
\r<p>
\r<dt> <var>child_thread</var>
\r<dd>
\r[out thread send right]
\rThe kernel-assigned name for the new thread.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_create_running</strong> function creates a new thread
\rwithin <var>parent_task</var>.
\rThe new thread has is not suspended. Its initial state is given
\rby <var>state</var>. <var>flavor</var> specifies the type of state to set.
\r<p>
\rThe format of the state to set is machine specific; it is defined in
\r\*L<mach/thread_status.h>\*O.
\r<p>
\rThe new thread holds a send right for its thread kernel port.
\rA send right for the
\rthread's kernel port is also returned to the calling task or
\rthread in <var>child_thread</var>.
\rThe new thread's exception ports are set to <strong>MACH_PORT_NULL</strong>.
\r<h3>NOTES</h3>
\r<p>
\rThis is an optimized form of the sequence: <strong>thread_create</strong>,
\r<strong>thread_set_state</strong>
\rand <strong>thread_resume</strong>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_create.html"><strong>task_create</strong></a>,
\r<a href="task_threads.html"><strong>task_threads</strong></a>,
\r<a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>,
\r<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
\r<a href="thread_resume.html"><strong>thread_resume</strong></a>,
\r<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>,
\r<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
\r<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
\r<a href="thread_terminate.html"><strong>thread_terminate</strong></a>,
\r<a href="thread_create.html"><strong>thread_create</strong></a>.
\r\ No newline at end of file
+<h2>thread_create_running</h2>
+<hr>
+<p>
+<strong>Function</strong> - Optimized creation of a running thread.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_create_running</strong>
+ <strong>(task_t</strong> <var>parent_task</var>,
+ <strong>thread_state_flavor_t</strong> <var>flavor</var>,
+ <strong>thread_state_t</strong> <var>state</var>,
+ <strong>thread_act_t</strong> <var>child_thread</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>parent_task</var>
+<dd>
+[in task send right]
+The port for the task that is to contain the new
+thread.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of state to establish. Valid values correspond to
+supported machine architecture features.
+<p>
+<dt> <var>state</var>
+<dd>
+[pointer to in structure]
+State information for the specified thread.
+<p>
+<dt> <var>child_thread</var>
+<dd>
+[out thread send right]
+The kernel-assigned name for the new thread.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_create_running</strong> function creates a new thread
+within <var>parent_task</var>.
+The new thread has is not suspended. Its initial state is given
+by <var>state</var>. <var>flavor</var> specifies the type of state to set.
+<p>
+The format of the state to set is machine specific; it is defined in
+\*L<mach/thread_status.h>\*O.
+<p>
+The new thread holds a send right for its thread kernel port.
+A send right for the
+thread's kernel port is also returned to the calling task or
+thread in <var>child_thread</var>.
+The new thread's exception ports are set to <strong>MACH_PORT_NULL</strong>.
+<h3>NOTES</h3>
+<p>
+This is an optimized form of the sequence: <strong>thread_create</strong>,
+<strong>thread_set_state</strong>
+and <strong>thread_resume</strong>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_create.html"><strong>task_create</strong></a>,
+<a href="task_threads.html"><strong>task_threads</strong></a>,
+<a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>,
+<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
+<a href="thread_resume.html"><strong>thread_resume</strong></a>,
+<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>,
+<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
+<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
+<a href="thread_terminate.html"><strong>thread_terminate</strong></a>,
+<a href="thread_create.html"><strong>thread_create</strong></a>.
-<h2>thread_depress_abort</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Cancel thread scheduling depression.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_depress_abort</strong>
\r <strong>(thread_act_t</strong> <var>thread</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>thread</var>
\r<dd>
\r[in thread send right]
\rThread whose scheduling depression is canceled.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_depress_abort</strong> function cancels any scheduling depression
\reffective for <var>thread</var> caused by a <strong>thread_switch</strong> call.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="thread_abort.html"><strong>thread_abort</strong></a>,
\r<a href="thread_switch.html"><strong>thread_switch</strong></a>.
\r\ No newline at end of file
+<h2>thread_depress_abort</h2>
+<hr>
+<p>
+<strong>Function</strong> - Cancel thread scheduling depression.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_depress_abort</strong>
+ <strong>(thread_act_t</strong> <var>thread</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>thread</var>
+<dd>
+[in thread send right]
+Thread whose scheduling depression is canceled.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_depress_abort</strong> function cancels any scheduling depression
+effective for <var>thread</var> caused by a <strong>thread_switch</strong> call.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="thread_abort.html"><strong>thread_abort</strong></a>,
+<a href="thread_switch.html"><strong>thread_switch</strong></a>.
-<h2>thread_get_assignment</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return the processor set to which a thread is assigned.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_get_assignment</strong>
\r <strong>(thread_act_t</strong> <var>thread</var>,
\r <strong>processor_set_name_t</strong> <var>processor_set</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>thread</var>
\r<dd>
\r[in thread send right]
\rThe thread whose assignment is desired.
\r<p>
\r<dt> <var>processor_set</var>
\r<dd>
\r[out processor-set-name send right]
\rThe name port for the processor
\rset into which the thread is assigned.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_get_assignment</strong> function returns the name
\rport to the processor set to which <var>thread</var> is currently assigned.
\rThis port can only be used to obtain information about the processor set.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="thread_assign.html"><strong>thread_assign</strong></a>,
\r<a href="thread_assign_default.html"><strong>thread_assign_default</strong></a>,
\r<a href="processor_set_create.html"><strong>processor_set_create</strong></a>,
\r<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
\r<a href="task_assign.html"><strong>task_assign</strong></a>.
\r\ No newline at end of file
+<h2>thread_get_assignment</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return the processor set to which a thread is assigned.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_get_assignment</strong>
+ <strong>(thread_act_t</strong> <var>thread</var>,
+ <strong>processor_set_name_t</strong> <var>processor_set</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>thread</var>
+<dd>
+[in thread send right]
+The thread whose assignment is desired.
+<p>
+<dt> <var>processor_set</var>
+<dd>
+[out processor-set-name send right]
+The name port for the processor
+set into which the thread is assigned.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_get_assignment</strong> function returns the name
+port to the processor set to which <var>thread</var> is currently assigned.
+This port can only be used to obtain information about the processor set.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="thread_assign.html"><strong>thread_assign</strong></a>,
+<a href="thread_assign_default.html"><strong>thread_assign_default</strong></a>,
+<a href="processor_set_create.html"><strong>processor_set_create</strong></a>,
+<a href="processor_set_info.html"><strong>processor_set_info</strong></a>,
+<a href="task_assign.html"><strong>task_assign</strong></a>.
-<h2>thread_get_exception_ports</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return a send right to an exception port.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_get_exception_ports</strong>
\r <strong>(thread_act_t</strong> <var>thread</var>,
\r <strong>exception_mask_t</strong> <var>exception_types</var>,
\r <strong>exception_mask_array_t</strong> <var>old_exception_masks</var>,
\r <strong>old_exception_masks</strong> <var>old_exception_count</var>,
\r <strong>exception_port_array_t</strong> <var>old_exception_ports</var>,
\r <strong>exception_behavior_array_t</strong> <var>old_behaviors</var>,
\r <strong>exception_flavor_array_t</strong> <var>old_flavors</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>thread</var>
\r<dd>
\r[in thread send right]
\rThe thread for which to return the exception
\rports.
\r<p>
\r<dt> <var>exception_types</var>
\r<dd>
\r[in scalar]
\rA flag word indicating the types of exceptions for which the
\rexception ports are desired:
\r<dl>
\r<p>
\r<dt> <strong>EXC_MASK_BAD_ACCESS</strong>
\r<dd>
\rCould not access memory.
\r<p>
\r<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
\r<dd>
\rInstruction failed. Illegal or undefined instruction or operand.
\r<p>
\r<dt> <strong>EXC_MASK_ARITHMETIC</strong>
\r<dd>
\rArithmetic exception.
\r<p>
\r<dt> <strong>EXC_MASK_EMULATION</strong>
\r<dd>
\rEmulation instruction. Emulation support instruction
\rencountered.
\r<p>
\r<dt> <strong>EXC_MASK_SOFTWARE</strong>
\r<dd>
\rSoftware generated exception.
\r<p>
\r<dt> <strong>EXC_MASK_BREAKPOINT</strong>
\r<dd>
\rTrace, breakpoint, etc.
\r<p>
\r<dt> <strong>EXC_MASK_SYSCALL</strong>
\r<dd>
\rSystem call requested.
\r<p>
\r<dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
\r<dd>
\rSystem call with a number in the Mach call range requested.
\r</dl>
\r<p>
\r<dt> <var>old_exception_masks</var>
\r<dd>
\r[out array of <var>exception_mask_t</var>]
\rAn array, each element being a mask
\rspecifying for which exception types the corresponding element of the
\rother arrays apply.
\r<p>
\r<dt> <var>old_exception_count</var>
\r<dd>
\r[pointer to in/out scalar]
\rOn input, the maximum size of the array
\rbuffers; on output, the number of returned <exception type mask,
\rexception port, behavior, flavor> sets returned.
\r<p>
\r<dt> <var>old_exception_ports</var>
\r<dd>
\r[out array of exception send rights]
\rThe returned exception ports.
\r<p>
\r<dt> <var>old_behaviors</var>
\r<dd>
\r[out array of <var>exception_behavior_t</var>]
\rThe type of exception message to
\rbe sent. Defined types are:
\r<dl>
\r<p>
\r<dt> <strong>EXCEPTION_DEFAULT</strong>
\r<dd>
\rSend a <strong>catch_exception_raise</strong> message including the thread
\ridentity.
\r<p>
\r<dt> <strong>EXCEPTION_STATE</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state</strong> message including the
\rthread state.
\r<p>
\r<dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state_identity</strong> message
\rincluding the thread identity and state.
\r</dl>
\r<p>
\r<dt> <var>old_flavors</var>
\r<dd>
\r[out array of <var>thread_state_flavor_t</var>]
\rThe type of state to be sent with
\rthe exception message. These types are defined in \*L<mach/thread_states.h>\*O.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_get_exception_ports</strong> function returns send
\rrights for a specified
\rset of exception ports belonging to <var>thread</var>. The call returns
\ra set of quadruples
\r<exception type mask, exception port, behavior, flavor> for each unique set of
\r<exception port, behavior, flavor> in effect for the thread where
\rthe exception
\rtype mask indicates for which exception types the other values apply.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_EXCEPTION_PROTECTED</strong>
\r<dd>
\rOne of the requested exception ports is protected and cannot be returned.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,
\r<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
\r<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
\r<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
\r<a href="thread_create.html"><strong>thread_create</strong></a>,
\r<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
\r<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
\r<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>.
\r\ No newline at end of file
+<h2>thread_get_exception_ports</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return a send right to an exception port.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_get_exception_ports</strong>
+ <strong>(thread_act_t</strong> <var>thread</var>,
+ <strong>exception_mask_t</strong> <var>exception_types</var>,
+ <strong>exception_mask_array_t</strong> <var>old_exception_masks</var>,
+ <strong>old_exception_masks</strong> <var>old_exception_count</var>,
+ <strong>exception_port_array_t</strong> <var>old_exception_ports</var>,
+ <strong>exception_behavior_array_t</strong> <var>old_behaviors</var>,
+ <strong>exception_flavor_array_t</strong> <var>old_flavors</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>thread</var>
+<dd>
+[in thread send right]
+The thread for which to return the exception
+ports.
+<p>
+<dt> <var>exception_types</var>
+<dd>
+[in scalar]
+A flag word indicating the types of exceptions for which the
+exception ports are desired:
+<dl>
+<p>
+<dt> <strong>EXC_MASK_BAD_ACCESS</strong>
+<dd>
+Could not access memory.
+<p>
+<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
+<dd>
+Instruction failed. Illegal or undefined instruction or operand.
+<p>
+<dt> <strong>EXC_MASK_ARITHMETIC</strong>
+<dd>
+Arithmetic exception.
+<p>
+<dt> <strong>EXC_MASK_EMULATION</strong>
+<dd>
+Emulation instruction. Emulation support instruction
+encountered.
+<p>
+<dt> <strong>EXC_MASK_SOFTWARE</strong>
+<dd>
+Software generated exception.
+<p>
+<dt> <strong>EXC_MASK_BREAKPOINT</strong>
+<dd>
+Trace, breakpoint, etc.
+<p>
+<dt> <strong>EXC_MASK_SYSCALL</strong>
+<dd>
+System call requested.
+<p>
+<dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
+<dd>
+System call with a number in the Mach call range requested.
+</dl>
+<p>
+<dt> <var>old_exception_masks</var>
+<dd>
+[out array of <var>exception_mask_t</var>]
+An array, each element being a mask
+specifying for which exception types the corresponding element of the
+other arrays apply.
+<p>
+<dt> <var>old_exception_count</var>
+<dd>
+[pointer to in/out scalar]
+On input, the maximum size of the array
+buffers; on output, the number of returned <exception type mask,
+exception port, behavior, flavor> sets returned.
+<p>
+<dt> <var>old_exception_ports</var>
+<dd>
+[out array of exception send rights]
+The returned exception ports.
+<p>
+<dt> <var>old_behaviors</var>
+<dd>
+[out array of <var>exception_behavior_t</var>]
+The type of exception message to
+be sent. Defined types are:
+<dl>
+<p>
+<dt> <strong>EXCEPTION_DEFAULT</strong>
+<dd>
+Send a <strong>catch_exception_raise</strong> message including the thread
+identity.
+<p>
+<dt> <strong>EXCEPTION_STATE</strong>
+<dd>
+Send a <strong>catch_exception_raise_state</strong> message including the
+thread state.
+<p>
+<dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
+<dd>
+Send a <strong>catch_exception_raise_state_identity</strong> message
+including the thread identity and state.
+</dl>
+<p>
+<dt> <var>old_flavors</var>
+<dd>
+[out array of <var>thread_state_flavor_t</var>]
+The type of state to be sent with
+the exception message. These types are defined in \*L<mach/thread_states.h>\*O.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_get_exception_ports</strong> function returns send
+rights for a specified
+set of exception ports belonging to <var>thread</var>. The call returns
+a set of quadruples
+<exception type mask, exception port, behavior, flavor> for each unique set of
+<exception port, behavior, flavor> in effect for the thread where
+the exception
+type mask indicates for which exception types the other values apply.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_EXCEPTION_PROTECTED</strong>
+<dd>
+One of the requested exception ports is protected and cannot be returned.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,
+<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
+<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
+<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
+<a href="thread_create.html"><strong>thread_create</strong></a>,
+<a href="thread_set_exception_ports.html"><strong>thread_set_exception_ports</strong></a>,
+<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
+<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>.
-<h2>thread_get_special_port</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return a send right to the caller-specified special port.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_get_special_port</strong>
\r <strong>(thread_act_t</strong> <var>thread</var>,
\r <strong>int</strong> <var>which_port</var>,
\r <strong>thread</strong> <var>special_port</var><strong>);</strong>
\r</pre>
\r\r<h4>Macro form:</h4>
\r\r<pre>
\r<strong>kern_return_t thread_get_kernel_port</strong>
\r <strong>(thread_act_t</strong> <var>thread</var>,
\r <strong>thread</strong> <var>special_port</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>thread</var>
\r<dd>
\r[in thread send right]
\rThe thread for which to return the port's send
\rright.
\r<p>
\r<dt> <var>which_port</var>
\r<dd>
\r[in scalar]
\rThe special port for which the send right is requested. Valid
\rvalues are:
\r<dl>
\r<p>
\r<dt> <strong>THREAD_KERNEL_PORT</strong>
\r<dd>
\r[thread-self send right] The port used to name the thread.
\rUsed to invoke operations that affect the thread. This is the
\rport returned by <strong>mach_thread_self</strong>.
\r</dl>
\r<p>
\r<dt> <var>special_port</var>
\r<dd>
\r[out thread-special send right]
\rThe returned value for the port.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_get_special_port</strong> function returns a send
\rright for a special port
\rbelonging to <var>thread</var>.
\r<p>
\rThe thread kernel port is a port for which the kernel holds the
\rreceive right. The
\rkernel uses this port to identify the thread.
\r<p>
\rIf one thread has a send right for the kernel port of another
\rthread, it can use the
\rport to perform kernel operations for the other thread. Send
\rrights for a kernel
\rport normally are held only by the thread to which the port belongs, or by the
\rtask that contains the thread. Using the <strong>mach_msg</strong>
\rfunction, however, any
\rthread can pass a send right for its kernel port to another thread.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,
\r<a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>,
\r<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>,
\r<a href="thread_create.html"><strong>thread_create</strong></a>,
\r<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>.
\r\ No newline at end of file
+<h2>thread_get_special_port</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return a send right to the caller-specified special port.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_get_special_port</strong>
+ <strong>(thread_act_t</strong> <var>thread</var>,
+ <strong>int</strong> <var>which_port</var>,
+ <strong>thread</strong> <var>special_port</var><strong>);</strong>
+</pre>
+
+<h4>Macro form:</h4>
+
+<pre>
+<strong>kern_return_t thread_get_kernel_port</strong>
+ <strong>(thread_act_t</strong> <var>thread</var>,
+ <strong>thread</strong> <var>special_port</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>thread</var>
+<dd>
+[in thread send right]
+The thread for which to return the port's send
+right.
+<p>
+<dt> <var>which_port</var>
+<dd>
+[in scalar]
+The special port for which the send right is requested. Valid
+values are:
+<dl>
+<p>
+<dt> <strong>THREAD_KERNEL_PORT</strong>
+<dd>
+[thread-self send right] The port used to name the thread.
+Used to invoke operations that affect the thread. This is the
+port returned by <strong>mach_thread_self</strong>.
+</dl>
+<p>
+<dt> <var>special_port</var>
+<dd>
+[out thread-special send right]
+The returned value for the port.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_get_special_port</strong> function returns a send
+right for a special port
+belonging to <var>thread</var>.
+<p>
+The thread kernel port is a port for which the kernel holds the
+receive right. The
+kernel uses this port to identify the thread.
+<p>
+If one thread has a send right for the kernel port of another
+thread, it can use the
+port to perform kernel operations for the other thread. Send
+rights for a kernel
+port normally are held only by the thread to which the port belongs, or by the
+task that contains the thread. Using the <strong>mach_msg</strong>
+function, however, any
+thread can pass a send right for its kernel port to another thread.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,
+<a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>,
+<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>,
+<a href="thread_create.html"><strong>thread_create</strong></a>,
+<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>.
-<h2>thread_get_state</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return the execution state for a thread.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_get_state</strong>
\r <strong>(thread_act_t</strong> <var>target_thread</var>,
\r <strong>thread_state_flavor_t</strong> <var>flavor</var>,
\r <strong>thread_state_t</strong> <var>old_state</var>,
\r <strong>mach_msg_type_number_t</strong> <var>old_state_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_thread</var>
\r<dd>
\r[in thread send right]
\rThe thread for which the execution state is to be
\rreturned. The calling thread cannot specify itself.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of execution state to be returned. Valid values
\rcorrespond to supported machined architectures.
\r<p>
\r<dt> <var>old_state</var>
\r<dd>
\r[out structure]
\rState information for the specified thread.
\r<p>
\r<dt> <var>old_state_count</var>
\r<dd>
\r[in/out scalar]
\rOn input, the maximum size of the buffer; on output, the
\rsize returned (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_get_state</strong> function returns the execution
\rstate (for example, the
\rmachine registers) for <var>target_thread</var>. flavor specifies the type
\rof state information
\rreturned.
\r<p>
\rThe format of the data returned is machine specific; it is defined in
\r\*L<mach/thread_status.h>\*O.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_info.html"><strong>task_info</strong></a>,
\r<a href="thread_info.html"><strong>thread_info</strong></a>,
\r<a href="thread_set_state.html"><strong>thread_set_state</strong></a>.
\r\ No newline at end of file
+<h2>thread_get_state</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return the execution state for a thread.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_get_state</strong>
+ <strong>(thread_act_t</strong> <var>target_thread</var>,
+ <strong>thread_state_flavor_t</strong> <var>flavor</var>,
+ <strong>thread_state_t</strong> <var>old_state</var>,
+ <strong>mach_msg_type_number_t</strong> <var>old_state_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_thread</var>
+<dd>
+[in thread send right]
+The thread for which the execution state is to be
+returned. The calling thread cannot specify itself.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of execution state to be returned. Valid values
+correspond to supported machined architectures.
+<p>
+<dt> <var>old_state</var>
+<dd>
+[out structure]
+State information for the specified thread.
+<p>
+<dt> <var>old_state_count</var>
+<dd>
+[in/out scalar]
+On input, the maximum size of the buffer; on output, the
+size returned (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_get_state</strong> function returns the execution
+state (for example, the
+machine registers) for <var>target_thread</var>. flavor specifies the type
+of state information
+returned.
+<p>
+The format of the data returned is machine specific; it is defined in
+\*L<mach/thread_status.h>\*O.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_info.html"><strong>task_info</strong></a>,
+<a href="thread_info.html"><strong>thread_info</strong></a>,
+<a href="thread_set_state.html"><strong>thread_set_state</strong></a>.
-<h2>thread_info</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return information about a thread.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_info</strong>
\r <strong>(thread_act_t</strong> <var>target_thread</var>,
\r <strong>thread_flavor_t</strong> <var>flavor</var>,
\r <strong>thread_info_t</strong> <var>thread_info</var>,
\r <strong>mach_msg_type_number_t</strong> <var>thread_info_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_thread</var>
\r<dd>
\r[in thread send right]
\rThe thread for which the information is to be
\rreturned.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of information to be returned. Valid values are:
\r<dl>
\r<p>
\r<dt> <strong>THREAD_BASIC_INFO</strong>
\r<dd>
\rReturns basic information about the thread, such as the
\rthread's run state and suspend count. The returned structure is
\r<strong>thread_basic_info</strong>.
\r<p>
\r<dt> <strong>THREAD_SCHED_FIFO_INFO</strong>
\r<dd>
\rReturns FIFO scheduling policy information about the thread.
\rThe returned structure is <strong>policy_fifo_info</strong>.
\r<p>
\r<dt> <strong>THREAD_SCHED_RR_INFO</strong>
\r<dd>
\rReturns round-robin scheduling policy information about the
\rthread. The returned structure is <strong>policy_rr_info</strong>.
\r<p>
\r<dt> <strong>THREAD_SCHED_TIMESHARE_INFO</strong>
\r<dd>
\rReturns timeshare scheduling policy information about the
\rthread. The returned structure is <strong>policy_timeshare_info</strong>.
\r</dl>
\r<p>
\r<dt> <var>thread_info</var>
\r<dd>
\r[out structure]
\rInformation about the specified thread.
\r<p>
\r<dt> <var>thread_info_count</var>
\r<dd>
\r[in/out scalar]
\rOn input, the maximum size of the buffer; on output, the
\rsize returned (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_info</strong> function returns an information structure
\rof type <var>flavor</var>.
\r<h3>NOTES</h3>
\r<p>
\rAt any given time, a thread has only one scheduling policy in
\reffect for it. Thus,
\ronly one of the scheduling information structures will be valid,
\rthat so indicated
\rby the policy value returned by <strong>THREAD_BASIC_INFO</strong>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_info.html"><strong>task_info</strong></a>,
\r<a href="task_threads.html"><strong>task_threads</strong></a>,
\r<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
\r<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>,
\r<a href="thread_set_state.html"><strong>thread_set_state</strong></a>.
\r<p>
\rData Structures:
\r<a href="thread_basic_info.html"><strong>thread_basic_info</strong></a>,
\r<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>,
\r<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
\r<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>.
\r\ No newline at end of file
+<h2>thread_info</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return information about a thread.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_info</strong>
+ <strong>(thread_act_t</strong> <var>target_thread</var>,
+ <strong>thread_flavor_t</strong> <var>flavor</var>,
+ <strong>thread_info_t</strong> <var>thread_info</var>,
+ <strong>mach_msg_type_number_t</strong> <var>thread_info_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_thread</var>
+<dd>
+[in thread send right]
+The thread for which the information is to be
+returned.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of information to be returned. Valid values are:
+<dl>
+<p>
+<dt> <strong>THREAD_BASIC_INFO</strong>
+<dd>
+Returns basic information about the thread, such as the
+thread's run state and suspend count. The returned structure is
+<strong>thread_basic_info</strong>.
+<p>
+<dt> <strong>THREAD_SCHED_FIFO_INFO</strong>
+<dd>
+Returns FIFO scheduling policy information about the thread.
+The returned structure is <strong>policy_fifo_info</strong>.
+<p>
+<dt> <strong>THREAD_SCHED_RR_INFO</strong>
+<dd>
+Returns round-robin scheduling policy information about the
+thread. The returned structure is <strong>policy_rr_info</strong>.
+<p>
+<dt> <strong>THREAD_SCHED_TIMESHARE_INFO</strong>
+<dd>
+Returns timeshare scheduling policy information about the
+thread. The returned structure is <strong>policy_timeshare_info</strong>.
+</dl>
+<p>
+<dt> <var>thread_info</var>
+<dd>
+[out structure]
+Information about the specified thread.
+<p>
+<dt> <var>thread_info_count</var>
+<dd>
+[in/out scalar]
+On input, the maximum size of the buffer; on output, the
+size returned (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_info</strong> function returns an information structure
+of type <var>flavor</var>.
+<h3>NOTES</h3>
+<p>
+At any given time, a thread has only one scheduling policy in
+effect for it. Thus,
+only one of the scheduling information structures will be valid,
+that so indicated
+by the policy value returned by <strong>THREAD_BASIC_INFO</strong>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_info.html"><strong>task_info</strong></a>,
+<a href="task_threads.html"><strong>task_threads</strong></a>,
+<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
+<a href="thread_set_special_port.html"><strong>thread_set_special_port</strong></a>,
+<a href="thread_set_state.html"><strong>thread_set_state</strong></a>.
+<p>
+Data Structures:
+<a href="thread_basic_info.html"><strong>thread_basic_info</strong></a>,
+<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>,
+<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
+<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>.
-<h2>thread_policy</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set target thread's scheduling policy state.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_policy</strong>
\r <strong>(thread_act_t</strong> <var>thread</var>,
\r <strong>policy_t</strong> <var>policy</var>,
\r <strong>policy_base_t</strong> <var>base</var>,
\r <strong>base</strong> <var>base_count</var>,
\r <strong>boolean_t</strong> <var>set_limit</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>thread</var>
\r<dd>
\r[in thread send right]
\rThe thread scheduling policy is to be set.
\r<p>
\r<dt> <var>policy</var>
\r<dd>
\r[in scalar]
\rPolicy to be set. The values currently defined are <strong>POLICY_TIMESHARE</strong>,
\r<strong>POLICY_RR</strong> (round robin) and <strong>POLICY_FIFO</strong> (firstin, first-out).
\r<p>
\r<dt> <var>base</var>
\r<dd>
\r[pointer to in structure]
\rBase scheduling policy specific data,
\r<strong>policy_fifo_base</strong>, <strong>policy_rr_base</strong> or <strong>policy_timeshare_base</strong>.
\r<p>
\r<dt> <var>base_count</var>
\r<dd>
\r[in scalar]
\rThe size of the buffer (in natural-sized units).
\r<p>
\r<dt> <var>set_limit</var>
\r<dd>
\r[in scalar]
\rTrue if the thread's scheduling limits should be restricted to
\rallow no more service than specified by <var>base</var>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_policy</strong> function sets the scheduling policy
\rto be applied to thread. <var>policy</var> must be a scheduling policy
\rcurrently "enabled" for the thread's assigned processor set.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_POLICY</strong>
\r<dd>
\rThe processor set to which <var>thread</var> is currently assigned does
\rnot currently enable <var>policy</var>.
\r<p>
\r<dt> <strong>KERN_POLICY_LIMIT</strong>
\r<dd>
\rThe specified scheduling attributes exceeds the thread's limits.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>,
\r<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>,
\r<a href="task_policy.html"><strong>task_policy</strong></a>,
\r<a href="task_set_policy.html"><strong>task_set_policy</strong></a>.
\r<p>
\rData Structures:
\r<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
\r<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>,
\r<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>.
\r\ No newline at end of file
+<h2>thread_policy</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set target thread's scheduling policy state.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_policy</strong>
+ <strong>(thread_act_t</strong> <var>thread</var>,
+ <strong>policy_t</strong> <var>policy</var>,
+ <strong>policy_base_t</strong> <var>base</var>,
+ <strong>base</strong> <var>base_count</var>,
+ <strong>boolean_t</strong> <var>set_limit</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>thread</var>
+<dd>
+[in thread send right]
+The thread scheduling policy is to be set.
+<p>
+<dt> <var>policy</var>
+<dd>
+[in scalar]
+Policy to be set. The values currently defined are <strong>POLICY_TIMESHARE</strong>,
+<strong>POLICY_RR</strong> (round robin) and <strong>POLICY_FIFO</strong> (firstin, first-out).
+<p>
+<dt> <var>base</var>
+<dd>
+[pointer to in structure]
+Base scheduling policy specific data,
+<strong>policy_fifo_base</strong>, <strong>policy_rr_base</strong> or <strong>policy_timeshare_base</strong>.
+<p>
+<dt> <var>base_count</var>
+<dd>
+[in scalar]
+The size of the buffer (in natural-sized units).
+<p>
+<dt> <var>set_limit</var>
+<dd>
+[in scalar]
+True if the thread's scheduling limits should be restricted to
+allow no more service than specified by <var>base</var>.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_policy</strong> function sets the scheduling policy
+to be applied to thread. <var>policy</var> must be a scheduling policy
+currently "enabled" for the thread's assigned processor set.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_POLICY</strong>
+<dd>
+The processor set to which <var>thread</var> is currently assigned does
+not currently enable <var>policy</var>.
+<p>
+<dt> <strong>KERN_POLICY_LIMIT</strong>
+<dd>
+The specified scheduling attributes exceeds the thread's limits.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>,
+<a href="thread_set_policy.html"><strong>thread_set_policy</strong></a>,
+<a href="task_policy.html"><strong>task_policy</strong></a>,
+<a href="task_set_policy.html"><strong>task_set_policy</strong></a>.
+<p>
+Data Structures:
+<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
+<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>,
+<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>.
-<h2>thread_resume</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Resume a thread.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_resume</strong>
\r <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_thread</var>
\r<dd>
\r[in thread send right]
\rThe thread to be resumed.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_resume</strong> function decrements the suspend count
\rfor <var>target_thread</var>
\rby one. The thread is resumed if its suspend count goes to zero.
\rIf the suspend
\rcount is still positive, <strong>thread_resume</strong> must be repeated
\runtil the count reaches
\rzero.
\r<h3>NOTES</h3>
\r<p>
\rAn attempt to lower the suspend count below zero is ignored.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_resume.html"><strong>task_resume</strong></a>,
\r<a href="task_suspend.html"><strong>task_suspend</strong></a>,
\r<a href="thread_create.html"><strong>thread_create</strong></a>,
\r<a href="thread_info.html"><strong>thread_info</strong></a>,
\r<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
\r<a href="thread_terminate.html"><strong>thread_terminate</strong></a>.
\r\ No newline at end of file
+<h2>thread_resume</h2>
+<hr>
+<p>
+<strong>Function</strong> - Resume a thread.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_resume</strong>
+ <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_thread</var>
+<dd>
+[in thread send right]
+The thread to be resumed.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_resume</strong> function decrements the suspend count
+for <var>target_thread</var>
+by one. The thread is resumed if its suspend count goes to zero.
+If the suspend
+count is still positive, <strong>thread_resume</strong> must be repeated
+until the count reaches
+zero.
+<h3>NOTES</h3>
+<p>
+An attempt to lower the suspend count below zero is ignored.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_resume.html"><strong>task_resume</strong></a>,
+<a href="task_suspend.html"><strong>task_suspend</strong></a>,
+<a href="thread_create.html"><strong>thread_create</strong></a>,
+<a href="thread_info.html"><strong>thread_info</strong></a>,
+<a href="thread_suspend.html"><strong>thread_suspend</strong></a>,
+<a href="thread_terminate.html"><strong>thread_terminate</strong></a>.
-<h2>thread_sample</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Perform periodic PC sampling for a thread.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_sample</strong>
\r <strong>(thread_act_t</strong> <var>sample_thread</var>,
\r <strong>mach_port_make_send_t</strong> <var>reply_port</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>sample_thread</var>
\r<dd>
\r[in thread send right]
\rThread whose PC is to be sampled
\r<p>
\r<dt> <var>reply_port</var>
\r<dd>
\r[in sample receive (to be converted to send) right]
\rPort to which PC
\rsample buffers are sent. A value of <strong>MACH_PORT_NULL</strong> stops PC
\rsampling for the thread.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_sample</strong> function causes the program counter
\r(PC) of the specified
\r<var>sample_thread</var> to be sampled periodically (whenever the thread happens to be
\rrunning at the time of the kernel's "hardclock" interrupt).
\rThe set of PC sample
\rvalues obtained are saved in buffers which are sent to the specified
\r<var>reply_port</var> in
\r<strong>receive_samples</strong> messages.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_sample.html"><strong>task_sample</strong></a>,
\r<a href="receive_samples.html"><strong>receive_samples</strong></a>.
\r\ No newline at end of file
+<h2>thread_sample</h2>
+<hr>
+<p>
+<strong>Function</strong> - Perform periodic PC sampling for a thread.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_sample</strong>
+ <strong>(thread_act_t</strong> <var>sample_thread</var>,
+ <strong>mach_port_make_send_t</strong> <var>reply_port</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>sample_thread</var>
+<dd>
+[in thread send right]
+Thread whose PC is to be sampled
+<p>
+<dt> <var>reply_port</var>
+<dd>
+[in sample receive (to be converted to send) right]
+Port to which PC
+sample buffers are sent. A value of <strong>MACH_PORT_NULL</strong> stops PC
+sampling for the thread.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_sample</strong> function causes the program counter
+(PC) of the specified
+<var>sample_thread</var> to be sampled periodically (whenever the thread happens to be
+running at the time of the kernel's "hardclock" interrupt).
+The set of PC sample
+values obtained are saved in buffers which are sent to the specified
+<var>reply_port</var> in
+<strong>receive_samples</strong> messages.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_sample.html"><strong>task_sample</strong></a>,
+<a href="receive_samples.html"><strong>receive_samples</strong></a>.
-<h2>thread_set_exception_ports</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set exception ports for a thread.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_set_exception_ports</strong>
\r <strong>(thread_act_t</strong> <var>thread</var>,
\r <strong>exception_mask_t</strong> <var>exception_types</var>,
\r <strong>mach_port_t</strong> <var>exception_port</var>,
\r <strong>exception_behavior_t</strong> <var>behavior</var>,
\r <strong>thread_state_flavor_t</strong> <var>flavor</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>thread</var>
\r<dd>
\r[in thread send right]
\rThe thread for which to set the ports.
\r<p>
\r<dt> <var>exception_types</var>
\r<dd>
\r[in scalar]
\rA flag word indicating the types of exceptions for which the
\rexception port applies:
\r<dl>
\r<p>
\r<dt> <strong>EXC_MASK_BAD_ACCESS</strong>
\r<dd>
\rCould not access memory.
\r<p>
\r<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
\r<dd>
\rInstruction failed. Illegal or undefined instruction or operand.
\r<p>
\r<dt> <strong>EXC_MASK_ARITHMETIC</strong>
\r<dd>
\rArithmetic exception.
\r<p>
\r<dt> <strong>EXC_MASK_EMULATION</strong>
\r<dd>
\rEmulation instruction. Emulation support instruction
\rencountered.
\r<p>
\r<dt> <strong>EXC_MASK_SOFTWARE</strong>
\r<dd>
\rSoftware generated exception.
\r<p>
\r<dt> <strong>EXC_MASK_BREAKPOINT</strong>
\r<dd>
\rTrace, breakpoint, etc.
\r<p>
\r<dt> <strong>EXC_MASK_SYSCALL</strong>
\r<dd>
\rSystem call requested.
\r<p>
\r<dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
\r<dd>
\rSystem call with a number in the Mach call range requested.
\r</dl>
\r<p>
\r<dt> <var>exception_port</var>
\r<dd>
\r[in exception send right]
\rThe exception port for all selected exception
\rtypes.
\r<p>
\r<dt> <var>behavior</var>
\r<dd>
\r[in scalar]
\rThe type of exception message to be sent. Defined types are:
\r<dl>
\r<p>
\r<dt> <strong>EXCEPTION_DEFAULT</strong>
\r<dd>
\rSend a <strong>catch_exception_raise</strong> message including the thread
\ridentity.
\r<p>
\r<dt> <strong>EXCEPTION_DEFAULT_PROTECTED</strong>
\r<dd>
\rSend a <strong>catch_exception_raise</strong> message including the thread
\ridentity. Mark the exception port (and associated exceptions)
\ras protected.
\r<p>
\r<dt> <strong>EXCEPTION_STATE</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state</strong> message including the
\rthread state.
\r<p>
\r<dt> <strong>EXCEPTION_STATE_PROTECTED</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state</strong> message including the
\rthread state. Mark the exception port (and associated
\rexceptions) as protected.
\r<p>
\r<dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state_identity</strong> message
\rincluding the thread identity and state.
\r<p>
\r<dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong>
\r<dd>
\rSend a <strong>catch_exception_raise_state_identity</strong> message
\rincluding the thread identity and state. Mark the exception port
\r(and associated exceptions) as protected.
\r</dl>
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of state to be sent with the exception message.
\rThese types are defined in \*L<mach/thread_states.h>\*O.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_set_exception_ports</strong> function sets a specified
\rset of exception
\rports belonging to <var>thread</var>.
\r<h3>NOTES</h3>
\r<p>
\rIf the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is
\rthe host name port, Mach kernel traps are executed by the kernel as expected;
\rany other value causes the attempted execution of these system call numbers to
\rbe considered an exception.
\r<p>
\rA "protected" exception port is one which cannot be fetched and for which
\rexception processing cannot be aborted (<strong>thread_abort</strong>).
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,
\r<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
\r<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
\r<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
\r<a href="thread_create.html"><strong>thread_create</strong></a>,
\r<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
\r<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
\r<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>,
\r<a href="thread_abort.html"><strong>thread_abort</strong></a>.
\r\ No newline at end of file
+<h2>thread_set_exception_ports</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set exception ports for a thread.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_set_exception_ports</strong>
+ <strong>(thread_act_t</strong> <var>thread</var>,
+ <strong>exception_mask_t</strong> <var>exception_types</var>,
+ <strong>mach_port_t</strong> <var>exception_port</var>,
+ <strong>exception_behavior_t</strong> <var>behavior</var>,
+ <strong>thread_state_flavor_t</strong> <var>flavor</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>thread</var>
+<dd>
+[in thread send right]
+The thread for which to set the ports.
+<p>
+<dt> <var>exception_types</var>
+<dd>
+[in scalar]
+A flag word indicating the types of exceptions for which the
+exception port applies:
+<dl>
+<p>
+<dt> <strong>EXC_MASK_BAD_ACCESS</strong>
+<dd>
+Could not access memory.
+<p>
+<dt> <strong>EXC_MASK_BAD_INSTRUCTION</strong>
+<dd>
+Instruction failed. Illegal or undefined instruction or operand.
+<p>
+<dt> <strong>EXC_MASK_ARITHMETIC</strong>
+<dd>
+Arithmetic exception.
+<p>
+<dt> <strong>EXC_MASK_EMULATION</strong>
+<dd>
+Emulation instruction. Emulation support instruction
+encountered.
+<p>
+<dt> <strong>EXC_MASK_SOFTWARE</strong>
+<dd>
+Software generated exception.
+<p>
+<dt> <strong>EXC_MASK_BREAKPOINT</strong>
+<dd>
+Trace, breakpoint, etc.
+<p>
+<dt> <strong>EXC_MASK_SYSCALL</strong>
+<dd>
+System call requested.
+<p>
+<dt> <strong>EXC_MASK_MACH_SYSCALL</strong>
+<dd>
+System call with a number in the Mach call range requested.
+</dl>
+<p>
+<dt> <var>exception_port</var>
+<dd>
+[in exception send right]
+The exception port for all selected exception
+types.
+<p>
+<dt> <var>behavior</var>
+<dd>
+[in scalar]
+The type of exception message to be sent. Defined types are:
+<dl>
+<p>
+<dt> <strong>EXCEPTION_DEFAULT</strong>
+<dd>
+Send a <strong>catch_exception_raise</strong> message including the thread
+identity.
+<p>
+<dt> <strong>EXCEPTION_DEFAULT_PROTECTED</strong>
+<dd>
+Send a <strong>catch_exception_raise</strong> message including the thread
+identity. Mark the exception port (and associated exceptions)
+as protected.
+<p>
+<dt> <strong>EXCEPTION_STATE</strong>
+<dd>
+Send a <strong>catch_exception_raise_state</strong> message including the
+thread state.
+<p>
+<dt> <strong>EXCEPTION_STATE_PROTECTED</strong>
+<dd>
+Send a <strong>catch_exception_raise_state</strong> message including the
+thread state. Mark the exception port (and associated
+exceptions) as protected.
+<p>
+<dt> <strong>EXCEPTION_STATE_IDENTITY</strong>
+<dd>
+Send a <strong>catch_exception_raise_state_identity</strong> message
+including the thread identity and state.
+<p>
+<dt> <strong>EXCEPTION_STATE_IDENTITY_PROTECTED</strong>
+<dd>
+Send a <strong>catch_exception_raise_state_identity</strong> message
+including the thread identity and state. Mark the exception port
+(and associated exceptions) as protected.
+</dl>
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of state to be sent with the exception message.
+These types are defined in \*L<mach/thread_states.h>\*O.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_set_exception_ports</strong> function sets a specified
+set of exception
+ports belonging to <var>thread</var>.
+<h3>NOTES</h3>
+<p>
+If the value of the <strong>EXC_MACH_SYSCALL</strong> exception class exception port is
+the host name port, Mach kernel traps are executed by the kernel as expected;
+any other value causes the attempted execution of these system call numbers to
+be considered an exception.
+<p>
+A "protected" exception port is one which cannot be fetched and for which
+exception processing cannot be aborted (<strong>thread_abort</strong>).
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,
+<a href="task_get_exception_ports.html"><strong>task_get_exception_ports</strong></a>,
+<a href="task_set_exception_ports.html"><strong>task_set_exception_ports</strong></a>,
+<a href="task_swap_exception_ports.html"><strong>task_swap_exception_ports</strong></a>,
+<a href="thread_create.html"><strong>thread_create</strong></a>,
+<a href="thread_get_exception_ports.html"><strong>thread_get_exception_ports</strong></a>,
+<a href="TS_exception_ports.html"><strong>thread_swap_exception_ports</strong></a>,
+<a href="catch_exception_raise.html"><strong>catch_exception_raise</strong></a>,
+<a href="thread_abort.html"><strong>thread_abort</strong></a>.
-<h2>thread_set_policy</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set target thread's scheduling policy state. (Protected Interface.)
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_set_policy</strong>
\r <strong>(thread_act_t</strong> <var>thread</var>,
\r <strong>processor_set_t</strong> <var>processor_set</var>,
\r <strong>policy_t</strong> <var>policy</var>,
\r <strong>policy_base_t</strong> <var>base</var>,
\r <strong>mach_msg_type_number_t</strong> <var>base_count</var>,
\r <strong>policy_limit_t</strong> <var>limit</var>,
\r <strong>mach_msg_type_number_</strong> <var>limit_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>thread</var>
\r<dd>
\r[in thread send right]
\rThe thread scheduling policy is to be set.
\r<p>
\r<dt> <var>processor_set</var>
\r<dd>
\r[in processor-set-control send right]
\rThe control port for the processor
\rset to which the thread is currently assigned.
\r<p>
\r<dt> <var>policy</var>
\r<dd>
\r[in scalar]
\rPolicy to be set. The values currently defined are <strong>POLICY_TIMESHARE</strong>,
\r<strong>POLICY_RR</strong> (round robin) and <strong>POLICY_FIFO</strong> (firstin, first-out).
\r<p>
\r<dt> <var>base</var>
\r<dd>
\r[pointer to in structure]
\rBase policy specific data, <strong>policy_fifo_base</strong>,
\r<strong>policy_rr_base</strong> or <strong>policy_timeshare_base</strong>.
\r<p>
\r<dt> <var>base_count</var>
\r<dd>
\r[in scalar]
\rThe size of the buffer (in natural-sized units).
\r<p>
\r<dt> <var>limit</var>
\r<dd>
\r[pointer to in structure]
\rPolicy specific limits, <strong>policy_fifo_limit</strong>,
\r<strong>policy_rr_limit</strong> or <strong>policy_timeshare_limit</strong>.
\r<p>
\r<dt> <var>limit_count</var>
\r<dd>
\r[in scalar]
\rThe size of the buffer (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_set_policy</strong> function sets the scheduling
\rattributes, both base and limit, for <var>thread</var>.
\r<var>policy</var> may be any policy implemented by the processor set
\rwhether or not it is enabled.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_PROCESSOR_SET</strong>
\r<dd>
\r<var>processor_set</var> is not the thread's processor set control port.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>,
\r<a href="thread_policy.html"><strong>thread_policy</strong></a>,
\r<a href="task_policy.html"><strong>task_policy</strong></a>,
\r<a href="task_set_policy.html"><strong>task_set_policy</strong></a>.
\r<p>
\rData Structures:
\r<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
\r<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>,
\r<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>.
\r\ No newline at end of file
+<h2>thread_set_policy</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set target thread's scheduling policy state. (Protected Interface.)
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_set_policy</strong>
+ <strong>(thread_act_t</strong> <var>thread</var>,
+ <strong>processor_set_t</strong> <var>processor_set</var>,
+ <strong>policy_t</strong> <var>policy</var>,
+ <strong>policy_base_t</strong> <var>base</var>,
+ <strong>mach_msg_type_number_t</strong> <var>base_count</var>,
+ <strong>policy_limit_t</strong> <var>limit</var>,
+ <strong>mach_msg_type_number_</strong> <var>limit_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>thread</var>
+<dd>
+[in thread send right]
+The thread scheduling policy is to be set.
+<p>
+<dt> <var>processor_set</var>
+<dd>
+[in processor-set-control send right]
+The control port for the processor
+set to which the thread is currently assigned.
+<p>
+<dt> <var>policy</var>
+<dd>
+[in scalar]
+Policy to be set. The values currently defined are <strong>POLICY_TIMESHARE</strong>,
+<strong>POLICY_RR</strong> (round robin) and <strong>POLICY_FIFO</strong> (firstin, first-out).
+<p>
+<dt> <var>base</var>
+<dd>
+[pointer to in structure]
+Base policy specific data, <strong>policy_fifo_base</strong>,
+<strong>policy_rr_base</strong> or <strong>policy_timeshare_base</strong>.
+<p>
+<dt> <var>base_count</var>
+<dd>
+[in scalar]
+The size of the buffer (in natural-sized units).
+<p>
+<dt> <var>limit</var>
+<dd>
+[pointer to in structure]
+Policy specific limits, <strong>policy_fifo_limit</strong>,
+<strong>policy_rr_limit</strong> or <strong>policy_timeshare_limit</strong>.
+<p>
+<dt> <var>limit_count</var>
+<dd>
+[in scalar]
+The size of the buffer (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_set_policy</strong> function sets the scheduling
+attributes, both base and limit, for <var>thread</var>.
+<var>policy</var> may be any policy implemented by the processor set
+whether or not it is enabled.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_PROCESSOR_SET</strong>
+<dd>
+<var>processor_set</var> is not the thread's processor set control port.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="P_set_policy_control.html"><strong>processor_set_policy_control</strong></a>,
+<a href="thread_policy.html"><strong>thread_policy</strong></a>,
+<a href="task_policy.html"><strong>task_policy</strong></a>,
+<a href="task_set_policy.html"><strong>task_set_policy</strong></a>.
+<p>
+Data Structures:
+<a href="policy_fifo_info.html"><strong>policy_fifo_info</strong></a>,
+<a href="policy_rr_info.html"><strong>policy_rr_info</strong></a>,
+<a href="policy_timeshare_info.html"><strong>policy_timeshare_info</strong></a>.
-<h2>thread_set_special_port</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set caller-specified special port belonging to the target thread.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_set_special_port</strong>
\r <strong>(thread_act_t</strong> <var>thread</var>,
\r <strong>int</strong> <var>which_port</var>,
\r <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
\r</pre>
\r\r<h4>Macro form:</h4>
\r<pre>
\r<strong>kern_return_t thread_set_kernel_port</strong>
\r <strong>(thread_act_t</strong> <var>thread</var>,
\r <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>thread</var>
\r<dd>
\r[in thread send right]
\rThe thread for which to set the port.
\r<p>
\r<dt> <var>which_port</var>
\r<dd>
\r[in scalar]
\rThe special port to be set. Valid values are:
\r<dl>
\r<p>
\r<dt> <strong>THREAD_KERNEL_PORT</strong>
\r<dd>
\r[thread-self port] The thread's kernel port. Used by the kernel
\rto receive messages from the thread. This is the port returned
\rby <strong>mach_thread_self</strong>.
\r</dl>
\r<p>
\r<dt> <var>special_port</var>
\r<dd>
\r[in thread-special send right]
\rThe value for the port.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_set_special_port</strong> function sets a special
\rport belonging to <var>thread</var>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,
\r<a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>,
\r<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>,
\r<a href="thread_create.html"><strong>thread_create</strong></a>,
\r<a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>.
\r\ No newline at end of file
+<h2>thread_set_special_port</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set caller-specified special port belonging to the target thread.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_set_special_port</strong>
+ <strong>(thread_act_t</strong> <var>thread</var>,
+ <strong>int</strong> <var>which_port</var>,
+ <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
+</pre>
+
+<h4>Macro form:</h4>
+<pre>
+<strong>kern_return_t thread_set_kernel_port</strong>
+ <strong>(thread_act_t</strong> <var>thread</var>,
+ <strong>mach_port_t</strong> <var>special_port</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>thread</var>
+<dd>
+[in thread send right]
+The thread for which to set the port.
+<p>
+<dt> <var>which_port</var>
+<dd>
+[in scalar]
+The special port to be set. Valid values are:
+<dl>
+<p>
+<dt> <strong>THREAD_KERNEL_PORT</strong>
+<dd>
+[thread-self port] The thread's kernel port. Used by the kernel
+to receive messages from the thread. This is the port returned
+by <strong>mach_thread_self</strong>.
+</dl>
+<p>
+<dt> <var>special_port</var>
+<dd>
+[in thread-special send right]
+The value for the port.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_set_special_port</strong> function sets a special
+port belonging to <var>thread</var>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_thread_self.html"><strong>mach_thread_self</strong></a>,
+<a href="task_get_special_port.html"><strong>task_get_special_port</strong></a>,
+<a href="task_set_special_port.html"><strong>task_set_special_port</strong></a>,
+<a href="thread_create.html"><strong>thread_create</strong></a>,
+<a href="thread_get_special_port.html"><strong>thread_get_special_port</strong></a>.
-<h2>thread_set_state</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set the target thread's user-mode execution state.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_set_state</strong>
\r <strong>(thread_act_t</strong> <var>target_thread</var>,
\r <strong>thread_state_flavor_t</strong> <var>flavor</var>,
\r <strong>thread_state_t</strong> <var>new_state</var>,
\r <strong>target_thread</strong> <var>new_state_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_thread</var>
\r<dd>
\r[in thread send right]
\rThe thread for which to set the execution state.
\rThe calling thread cannot specify itself.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of state to set. Valid values correspond to
\rsupported machine architecture features.
\r<p>
\r<dt> <var>new_state</var>
\r<dd>
\r[pointer to in structure]
\rState information for the specified thread.
\r<p>
\r<dt> <var>new_state_count</var>
\r<dd>
\r[in scalar]
\rThe size of the buffer (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_set_state</strong> function sets the execution state
\r(for example, the
\rmachine registers) for <var>target_thread</var>. <var>flavor</var> specifies the type
\rof state to set.
\r<p>
\rThe format of the state to set is machine specific; it is defined in
\r<strong>mach/thread_status.h</strong>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_info.html"><strong>task_info</strong></a>,
\r<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
\r<a href="thread_info.html"><strong>thread_info</strong></a>.
\r\ No newline at end of file
+<h2>thread_set_state</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set the target thread's user-mode execution state.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_set_state</strong>
+ <strong>(thread_act_t</strong> <var>target_thread</var>,
+ <strong>thread_state_flavor_t</strong> <var>flavor</var>,
+ <strong>thread_state_t</strong> <var>new_state</var>,
+ <strong>target_thread</strong> <var>new_state_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_thread</var>
+<dd>
+[in thread send right]
+The thread for which to set the execution state.
+The calling thread cannot specify itself.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of state to set. Valid values correspond to
+supported machine architecture features.
+<p>
+<dt> <var>new_state</var>
+<dd>
+[pointer to in structure]
+State information for the specified thread.
+<p>
+<dt> <var>new_state_count</var>
+<dd>
+[in scalar]
+The size of the buffer (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_set_state</strong> function sets the execution state
+(for example, the
+machine registers) for <var>target_thread</var>. <var>flavor</var> specifies the type
+of state to set.
+<p>
+The format of the state to set is machine specific; it is defined in
+<strong>mach/thread_status.h</strong>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_info.html"><strong>task_info</strong></a>,
+<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
+<a href="thread_info.html"><strong>thread_info</strong></a>.
-<h2>thread_suspend</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Suspend a thread.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_suspend</strong>
\r <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_thread</var>
\r<dd>
\r[in thread send right]
\rThe thread to be suspended.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_suspend</strong> function increments the suspend
\rcount for <var>target_thread</var>
\rand prevents the thread from executing any more user-level instructions.
\r<p>
\rIn this context, a user-level instruction can be either a machine instruction
\rexecuted in user mode or a system trap instruction, including
\ra page fault. If a
\rthread is currently executing within a system trap, the kernel
\rcode may continue
\rto execute until it reaches the system return code or it may
\rsuspend within the
\rkernel code. In either case, the system trap returns when the thread resumes.
\r<p>
\rTo resume a suspended thread, use <strong>thread_resume</strong>. If
\rthe suspend count is
\rgreater than one, <strong>thread_resume</strong> must be repeated that
\rnumber of times.
\r<h3>CAUTIONS</h3>
\r<p>
\rUnpredictable results may occur if a program suspends a thread and alters its
\ruser state so that its direction is changed upon resuming. Note that the
\r<strong>thread_abort</strong> function allows a system call to be aborted
\ronly if it is progressing in a
\rpredictable way.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_resume.html"><strong>task_resume</strong></a>,
\r<a href="task_suspend.html"><strong>task_suspend</strong></a>,
\r<a href="thread_abort.html"><strong>thread_abort</strong></a>,
\r<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
\r<a href="thread_info.html"><strong>thread_info</strong></a>,
\r<a href="thread_resume.html"><strong>thread_resume</strong></a>,
\r<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
\r<a href="thread_terminate.html"><strong>thread_terminate</strong></a>.
\r\ No newline at end of file
+<h2>thread_suspend</h2>
+<hr>
+<p>
+<strong>Function</strong> - Suspend a thread.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_suspend</strong>
+ <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_thread</var>
+<dd>
+[in thread send right]
+The thread to be suspended.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_suspend</strong> function increments the suspend
+count for <var>target_thread</var>
+and prevents the thread from executing any more user-level instructions.
+<p>
+In this context, a user-level instruction can be either a machine instruction
+executed in user mode or a system trap instruction, including
+a page fault. If a
+thread is currently executing within a system trap, the kernel
+code may continue
+to execute until it reaches the system return code or it may
+suspend within the
+kernel code. In either case, the system trap returns when the thread resumes.
+<p>
+To resume a suspended thread, use <strong>thread_resume</strong>. If
+the suspend count is
+greater than one, <strong>thread_resume</strong> must be repeated that
+number of times.
+<h3>CAUTIONS</h3>
+<p>
+Unpredictable results may occur if a program suspends a thread and alters its
+user state so that its direction is changed upon resuming. Note that the
+<strong>thread_abort</strong> function allows a system call to be aborted
+only if it is progressing in a
+predictable way.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_resume.html"><strong>task_resume</strong></a>,
+<a href="task_suspend.html"><strong>task_suspend</strong></a>,
+<a href="thread_abort.html"><strong>thread_abort</strong></a>,
+<a href="thread_get_state.html"><strong>thread_get_state</strong></a>,
+<a href="thread_info.html"><strong>thread_info</strong></a>,
+<a href="thread_resume.html"><strong>thread_resume</strong></a>,
+<a href="thread_set_state.html"><strong>thread_set_state</strong></a>,
+<a href="thread_terminate.html"><strong>thread_terminate</strong></a>.
-<h2>thread_switch</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Cause context switch with options.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_switch</strong>
\r <strong>(mach_port_t</strong> <var>new_thread</var>,
\r <strong>int</strong> <var>option</var>,
\r <strong>mach_msg_timeout_t</strong> <var>time</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>new_thread</var>
\r<dd>
\r[in thread send right]
\rThread to which the processor should switch
\rcontext.
\r<p>
\r<dt> <var>option</var>
\r<dd>
\r[in scalar]
\rOptions applicable to the context switch.
\r<p>
\r<dt> <var>time</var>
\r<dd>
\r[in scalar]
\rTime duration during which the thread should be affected by
\r<var>option</var>.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_switch</strong> function provides low-level access
\rto the scheduler's
\rcontext switching code. <var>new_thread</var> is a hint that implements
\rhand-off scheduling.
\rThe operating system will attempt to switch directly to the new thread
\r(bypassing the normal logic that selects the next thread to run)
\rif possible. Since this is a hint, it may be incorrect; it is ignored if it
\rdoesn't specify a thread on the same host as the current thread or if
\rthe scheduler cannot switch to that thread (i.e.,
\rnot runable or already running on another processor). In this
\rcase, the normal
\rlogic to select the next thread to run is used; the current thread
\rmay continue
\rrunning if there is no other appropriate thread to run.
\r<p>
\rThe <var>option</var> argument specifies the interpretation and use of <var>time</var>.
\rThe possible values (from \*L<mach/thread_switch.h>\*O) are:
\r<dl>
\r<dt> <strong>SWITCH_OPTION_NONE</strong>
\r<dd>
\rThe <var>time</var> argument is ignored.
\r<dt> <strong>SWITCH_OPTION_WAIT</strong>
\r<dd>
\rThe thread is blocked for the specified <var>time</var>. This wait cannot be
\rcanceled by <strong>thread_resume</strong>;
\ronly <strong>thread_abort</strong> can terminate this wait.
\r<dt> <strong>SWITCH_OPTION_DEPRESS</strong>
\r<dd>
\rThe thread's scheduling attributes are temporarily set so as to provide
\rit with the lowest possible service for duration <var>time</var>. The scheduling
\rdepression is aborted when <var>time</var> has passed, when the current thread is
\rnext run (either via hand-off scheduling or because the processor set
\rhas nothing better to do), or when <strong>thread_abort</strong> or
\r<strong>thread_depress_abort</strong> is applied to the current thread.
\rChanging the thread's scheduling attributes (via <strong>thread_policy</strong>)
\rwill not affect this depression.
\r<dt> <strong>SWITCH_OPTION_IDLE</strong>
\r<dd>
\rThis option is similar to <strong>SWITCH_OPTION_DEPRESS</strong> however, the
\rthread's scheduling attributes are temporarily set so as to place it
\rat a service level that is below all runnable threads for
\rduration <var>time</var>. The scheduling depression is aborted
\rwhen <var>time</var> has passed, when the current thread is
\rnext run (either via hand-off scheduling or because the processor set
\rhas nothing better to do), or when <strong>thread_abort</strong> or
\r<strong>thread_depress_abort</strong> is applied to the current thread.
\rChanging the thread's scheduling attributes (via <strong>thread_policy</strong>)
\rwill not affect this depression.
\r</dl>
\r<p>
\rThe minimum time and units of time can be obtained as the <var>min_timeout</var>
\rvalue from the <strong>HOST_SCHED_INFO</strong> flavor of <strong>host_info</strong>.
\r<h3>NOTES</h3>
\r<p>
\r<strong>thread_switch</strong> is often called when the current thread
\rcan proceed no further
\rfor some reason; the various options and arguments allow information about
\rthis reason to be transmitted to the kernel. The <var>new_thread</var>
\rargument (hand-off
\rscheduling) is useful when the identity of the thread that must make progress
\rbefore the current thread runs again is known. The <strong>SWITCH_OPTION_WAIT</strong>
\roption is used when the amount of time that the current thread
\rmust wait before it
\rcan do anything useful can be estimated and is fairly short,
\respecially when the
\ridentity of the thread for which this thread must wait is not known.
\r<h3>CAUTIONS</h3>
\r<p>
\rUsers should beware of calling <strong>thread_switch</strong> with an
\rinvalid hint (e.g., <strong>THREAD_NULL</strong>) and no option.
\rBecause the time-sharing scheduler varies the
\rpriority of threads based on usage, this may result in a waste
\rof CPU time if the
\rthread that must be run is of lower priority. The use of the
\r<strong>SWITCH_OPTION_DEPRESS</strong> option in this situation is highly recommended.
\r<p>
\r<strong>thread_switch</strong> ignores policies. Users relying on the
\rpreemption semantics of a
\rfixed time policy should be aware that <strong>thread_switch</strong>
\rignores these semantics;
\rit will run the specified <var>new_thread</var> independent of its scheduling
\rattributes and
\rthose of any threads that could run instead.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="thread_abort.html"><strong>thread_abort</strong></a>,
\r<a href="thread_depress_abort.html"><strong>thread_depress_abort</strong></a>.
\r\ No newline at end of file
+<h2>thread_switch</h2>
+<hr>
+<p>
+<strong>Function</strong> - Cause context switch with options.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_switch</strong>
+ <strong>(mach_port_t</strong> <var>new_thread</var>,
+ <strong>int</strong> <var>option</var>,
+ <strong>mach_msg_timeout_t</strong> <var>time</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>new_thread</var>
+<dd>
+[in thread send right]
+Thread to which the processor should switch
+context.
+<p>
+<dt> <var>option</var>
+<dd>
+[in scalar]
+Options applicable to the context switch.
+<p>
+<dt> <var>time</var>
+<dd>
+[in scalar]
+Time duration during which the thread should be affected by
+<var>option</var>.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_switch</strong> function provides low-level access
+to the scheduler's
+context switching code. <var>new_thread</var> is a hint that implements
+hand-off scheduling.
+The operating system will attempt to switch directly to the new thread
+(bypassing the normal logic that selects the next thread to run)
+if possible. Since this is a hint, it may be incorrect; it is ignored if it
+doesn't specify a thread on the same host as the current thread or if
+the scheduler cannot switch to that thread (i.e.,
+not runable or already running on another processor). In this
+case, the normal
+logic to select the next thread to run is used; the current thread
+may continue
+running if there is no other appropriate thread to run.
+<p>
+The <var>option</var> argument specifies the interpretation and use of <var>time</var>.
+The possible values (from \*L<mach/thread_switch.h>\*O) are:
+<dl>
+<dt> <strong>SWITCH_OPTION_NONE</strong>
+<dd>
+The <var>time</var> argument is ignored.
+<dt> <strong>SWITCH_OPTION_WAIT</strong>
+<dd>
+The thread is blocked for the specified <var>time</var>. This wait cannot be
+canceled by <strong>thread_resume</strong>;
+only <strong>thread_abort</strong> can terminate this wait.
+<dt> <strong>SWITCH_OPTION_DEPRESS</strong>
+<dd>
+The thread's scheduling attributes are temporarily set so as to provide
+it with the lowest possible service for duration <var>time</var>. The scheduling
+depression is aborted when <var>time</var> has passed, when the current thread is
+next run (either via hand-off scheduling or because the processor set
+has nothing better to do), or when <strong>thread_abort</strong> or
+<strong>thread_depress_abort</strong> is applied to the current thread.
+Changing the thread's scheduling attributes (via <strong>thread_policy</strong>)
+will not affect this depression.
+<dt> <strong>SWITCH_OPTION_IDLE</strong>
+<dd>
+This option is similar to <strong>SWITCH_OPTION_DEPRESS</strong> however, the
+thread's scheduling attributes are temporarily set so as to place it
+at a service level that is below all runnable threads for
+duration <var>time</var>. The scheduling depression is aborted
+when <var>time</var> has passed, when the current thread is
+next run (either via hand-off scheduling or because the processor set
+has nothing better to do), or when <strong>thread_abort</strong> or
+<strong>thread_depress_abort</strong> is applied to the current thread.
+Changing the thread's scheduling attributes (via <strong>thread_policy</strong>)
+will not affect this depression.
+</dl>
+<p>
+The minimum time and units of time can be obtained as the <var>min_timeout</var>
+value from the <strong>HOST_SCHED_INFO</strong> flavor of <strong>host_info</strong>.
+<h3>NOTES</h3>
+<p>
+<strong>thread_switch</strong> is often called when the current thread
+can proceed no further
+for some reason; the various options and arguments allow information about
+this reason to be transmitted to the kernel. The <var>new_thread</var>
+argument (hand-off
+scheduling) is useful when the identity of the thread that must make progress
+before the current thread runs again is known. The <strong>SWITCH_OPTION_WAIT</strong>
+option is used when the amount of time that the current thread
+must wait before it
+can do anything useful can be estimated and is fairly short,
+especially when the
+identity of the thread for which this thread must wait is not known.
+<h3>CAUTIONS</h3>
+<p>
+Users should beware of calling <strong>thread_switch</strong> with an
+invalid hint (e.g., <strong>THREAD_NULL</strong>) and no option.
+Because the time-sharing scheduler varies the
+priority of threads based on usage, this may result in a waste
+of CPU time if the
+thread that must be run is of lower priority. The use of the
+<strong>SWITCH_OPTION_DEPRESS</strong> option in this situation is highly recommended.
+<p>
+<strong>thread_switch</strong> ignores policies. Users relying on the
+preemption semantics of a
+fixed time policy should be aware that <strong>thread_switch</strong>
+ignores these semantics;
+it will run the specified <var>new_thread</var> independent of its scheduling
+attributes and
+those of any threads that could run instead.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="thread_abort.html"><strong>thread_abort</strong></a>,
+<a href="thread_depress_abort.html"><strong>thread_depress_abort</strong></a>.
-<h2>thread_terminate</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Destroy a thread.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_terminate</strong>
\r <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_thread</var>
\r<dd>
\r[in thread send right]
\rThe thread to be destroyed.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_terminate</strong> function kills <var>target_thread</var>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_terminate.html"><strong>task_terminate</strong></a>,
\r<a href="task_threads.html"><strong>task_threads</strong></a>,
\r<a href="thread_create.html"><strong>thread_create</strong></a>,
\r<a href="thread_resume.html"><strong>thread_resume</strong></a>,
\r<a href="thread_suspend.html"><strong>thread_suspend</strong></a>.
\r\ No newline at end of file
+<h2>thread_terminate</h2>
+<hr>
+<p>
+<strong>Function</strong> - Destroy a thread.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_terminate</strong>
+ <strong>(thread_act_t</strong> <var>target_thread</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_thread</var>
+<dd>
+[in thread send right]
+The thread to be destroyed.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_terminate</strong> function kills <var>target_thread</var>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_terminate.html"><strong>task_terminate</strong></a>,
+<a href="task_threads.html"><strong>task_threads</strong></a>,
+<a href="thread_create.html"><strong>thread_create</strong></a>,
+<a href="thread_resume.html"><strong>thread_resume</strong></a>,
+<a href="thread_suspend.html"><strong>thread_suspend</strong></a>.
-<h2>thread_wire</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Mark the thread as privileged with respect to kernel resources.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t thread_wire</strong>
\r <strong>(host_priv_t</strong> <var>host_priv</var>,
\r <strong>thread_act_t</strong> <var>thread</var>,
\r <strong>boolean_t</strong> <var>wired</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host_priv</var>
\r<dd>
\r[in host-control send right]
\rThe privileged control port for the host on
\rwhich the thread executes.
\r<p>
\r<dt> <var>thread</var>
\r<dd>
\r[in thread send right]
\rThe thread to be wired.
\r<p>
\r<dt> <var>wired</var>
\r<dd>
\r[in scalar]
\r<strong>TRUE</strong> if the thread is to be wired.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>thread_wire</strong> function marks the thread as "wired".
\rA "wired" thread is
\ralways eligible to be scheduled and can consume physical memory even when
\rfree memory is scarce. This property should be assigned to threads in the
\rdefault page-out path. Threads not in the default page-out path
\rshould not have
\rthis property to prevent the kernel's free list of pages from being exhausted.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ARGUMENT</strong>
\r<dd>
\r<var>thread</var> is not a thread port.
\r.P
\r<var>host_priv</var> is not the control port for the host on which <var>thread</var>
\rexecutes.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_wire.html"><strong>vm_wire</strong></a>.
\r\ No newline at end of file
+<h2>thread_wire</h2>
+<hr>
+<p>
+<strong>Function</strong> - Mark the thread as privileged with respect to kernel resources.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t thread_wire</strong>
+ <strong>(host_priv_t</strong> <var>host_priv</var>,
+ <strong>thread_act_t</strong> <var>thread</var>,
+ <strong>boolean_t</strong> <var>wired</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host_priv</var>
+<dd>
+[in host-control send right]
+The privileged control port for the host on
+which the thread executes.
+<p>
+<dt> <var>thread</var>
+<dd>
+[in thread send right]
+The thread to be wired.
+<p>
+<dt> <var>wired</var>
+<dd>
+[in scalar]
+<strong>TRUE</strong> if the thread is to be wired.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>thread_wire</strong> function marks the thread as "wired".
+A "wired" thread is
+always eligible to be scheduled and can consume physical memory even when
+free memory is scarce. This property should be assigned to threads in the
+default page-out path. Threads not in the default page-out path
+should not have
+this property to prevent the kernel's free list of pages from being exhausted.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ARGUMENT</strong>
+<dd>
+<var>thread</var> is not a thread port.
+.P
+<var>host_priv</var> is not the control port for the host on which <var>thread</var>
+executes.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="vm_wire.html"><strong>vm_wire</strong></a>.
-<h2>tvalspec</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Defines format of system time values.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct tvalspec</strong>
\r<strong>{</strong>
\r <strong>unsigned int</strong> <var>tv_sec</var><strong>;</strong>
\r <strong>clock_res_t</strong> <var>tv_nsec</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct tvalspec tvalspec_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>tv_sec</var>
\r<dd>
\rSeconds.
\r<p>
\r<dt> <var>tv_nsec</var>
\r<dd>
\rNanoseconds.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>tvalspec</strong> structure defines the format of the time
\rstructure supplied to or
\rreturned from the kernel. This definition conforms to the Posix
\r1003.4 <var>timespec</var>
\rdefinition where the <var>tv_nsec</var> structure member is valid
\rif (0 =< <var>tv_nsec</var> < 109) and
\rthe time period described is ((<var>tv_sec</var> * 109) + <var>tv_nsec</var>) nanoseconds.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="clock_get_time.html"><strong>clock_get_time</strong></a>,
\r<a href="clock_set_time.html"><strong>clock_set_time</strong></a>,
\r<a href="clock_sleep.html"><strong>clock_sleep</strong></a>,
\r<a href="clock_alarm.html"><strong>clock_alarm</strong></a>,
\r<a href="clock_alarm_reply.html"><strong>clock_alarm_reply</strong></a>.
\r<p>
\rData Structures:
\r<a href="mapped_tvalspec.html"><strong>mapped_tvalspec</strong></a>.
\r\ No newline at end of file
+<h2>tvalspec</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Defines format of system time values.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct tvalspec</strong>
+<strong>{</strong>
+ <strong>unsigned int</strong> <var>tv_sec</var><strong>;</strong>
+ <strong>clock_res_t</strong> <var>tv_nsec</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct tvalspec tvalspec_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>tv_sec</var>
+<dd>
+Seconds.
+<p>
+<dt> <var>tv_nsec</var>
+<dd>
+Nanoseconds.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>tvalspec</strong> structure defines the format of the time
+structure supplied to or
+returned from the kernel. This definition conforms to the Posix
+1003.4 <var>timespec</var>
+definition where the <var>tv_nsec</var> structure member is valid
+if (0 =< <var>tv_nsec</var> < 109) and
+the time period described is ((<var>tv_sec</var> * 109) + <var>tv_nsec</var>) nanoseconds.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="clock_get_time.html"><strong>clock_get_time</strong></a>,
+<a href="clock_set_time.html"><strong>clock_set_time</strong></a>,
+<a href="clock_sleep.html"><strong>clock_sleep</strong></a>,
+<a href="clock_alarm.html"><strong>clock_alarm</strong></a>,
+<a href="clock_alarm_reply.html"><strong>clock_alarm_reply</strong></a>.
+<p>
+Data Structures:
+<a href="mapped_tvalspec.html"><strong>mapped_tvalspec</strong></a>.
-<h2>vm_allocate</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Allocate a region of virtual memory.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_allocate</strong>
\r <strong>(vm_task_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>address</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>boolean_t</strong> <var>anywhere</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task in whose address space the
\rregion is to be allocated.
\r<p>
\r<dt> <var>address</var>
\r<dd>
\r[pointer to in/out scalar]
\rThe starting address for the region. If the
\rregion as specified by the given starting address and size would not lie
\rwithin the task's un-allocated memory, the kernel does not allocate the
\rregion. If allocated, the kernel returns the starting address actually used
\rfor the allocated region.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes to allocate.
\r<p>
\r<dt> <var>anywhere</var>
\r<dd>
\r[in scalar]
\rPlacement indicator. The valid values are:
\r<dl>
\r<p>
\r<dt> <strong>TRUE</strong>
\r<dd>
\rThe kernel allocates the region in the next unused space that
\ris sufficient within the address space. The kernel returns the
\rstarting address actually used in <var>address</var>.
\r<p>
\r<dt> <strong>FALSE</strong>
\r<dd>
\rThe kernel allocates the region starting at <var>address</var> unless that
\rspace is already allocated.
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_allocate</strong> function allocates a region of virtual
\rmemory in the specified
\rtask's address space. A new region is always zero filled.
\r<p>
\rIf <var>anywhere</var> is <strong>TRUE</strong>, the returned
\r<var>address</var> will be at
\ra page boundary; otherwise, the region starts at the beginning
\rof the virtual page
\rcontaining <var>address</var>.
\r<var>size</var> is always rounded up to an integral number of pages.
\rBecause of this rounding to virtual page boundaries, the amount of memory
\rallocated may be greater than <var>size</var>. Use <strong>host_page_size</strong> to find
\rthe current virtual page size.
\r<p>
\rInitially, there are no access restrictions on any of the pages of the newly
\rallocated region. Child tasks inherit the new region as a copy.
\r<h3>NOTES</h3>
\r<p>
\rTo establish different protections or inheritance for the new region, use the
\r<strong>vm_protect</strong> and <strong>vm_inherit</strong> functions.
\r<p>
\rA task's address space can contain both explicitly allocated memory and
\rautomatically allocated memory. The <strong>vm_allocate</strong> function
\rexplicitly allocates
\rmemory. The kernel automatically allocates memory to hold out-of-line data
\rpassed in a message (and received with <strong>mach_msg</strong>). The kernel allocates
\rmemory for the passed data as an integral number of pages.
\r<p>
\rThis interface is machine word length dependent because of the virtual address
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ADDRESS</strong>
\r<dd>
\rThe specified address is illegal or reserved.
\r<p>
\r<dt> <strong>KERN_NO_SPACE</strong>
\r<dd>
\rThere is not enough space in the task's address space to allocate the
\rnew region.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>,
\r<a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
\r<a href="vm_protect.html"><strong>vm_protect</strong></a>,
\r<a href="vm_region.html"><strong>vm_region</strong></a>,
\r<a href="host_page_size.html"><strong>host_page_size</strong></a>.
\r\r\ No newline at end of file
+<h2>vm_allocate</h2>
+<hr>
+<p>
+<strong>Function</strong> - Allocate a region of virtual memory.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t vm_allocate</strong>
+ <strong>(vm_task_t</strong> <var>target_task</var>,
+ <strong>vm_address_t</strong> <var>address</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>boolean_t</strong> <var>anywhere</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The port for the task in whose address space the
+region is to be allocated.
+<p>
+<dt> <var>address</var>
+<dd>
+[pointer to in/out scalar]
+The starting address for the region. If the
+region as specified by the given starting address and size would not lie
+within the task's un-allocated memory, the kernel does not allocate the
+region. If allocated, the kernel returns the starting address actually used
+for the allocated region.
+<p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The number of bytes to allocate.
+<p>
+<dt> <var>anywhere</var>
+<dd>
+[in scalar]
+Placement indicator. The valid values are:
+<dl>
+<p>
+<dt> <strong>TRUE</strong>
+<dd>
+The kernel allocates the region in the next unused space that
+is sufficient within the address space. The kernel returns the
+starting address actually used in <var>address</var>.
+<p>
+<dt> <strong>FALSE</strong>
+<dd>
+The kernel allocates the region starting at <var>address</var> unless that
+space is already allocated.
+</dl>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_allocate</strong> function allocates a region of virtual
+memory in the specified
+task's address space. A new region is always zero filled.
+<p>
+If <var>anywhere</var> is <strong>TRUE</strong>, the returned
+<var>address</var> will be at
+a page boundary; otherwise, the region starts at the beginning
+of the virtual page
+containing <var>address</var>.
+<var>size</var> is always rounded up to an integral number of pages.
+Because of this rounding to virtual page boundaries, the amount of memory
+allocated may be greater than <var>size</var>. Use <strong>host_page_size</strong> to find
+the current virtual page size.
+<p>
+Initially, there are no access restrictions on any of the pages of the newly
+allocated region. Child tasks inherit the new region as a copy.
+<h3>NOTES</h3>
+<p>
+To establish different protections or inheritance for the new region, use the
+<strong>vm_protect</strong> and <strong>vm_inherit</strong> functions.
+<p>
+A task's address space can contain both explicitly allocated memory and
+automatically allocated memory. The <strong>vm_allocate</strong> function
+explicitly allocates
+memory. The kernel automatically allocates memory to hold out-of-line data
+passed in a message (and received with <strong>mach_msg</strong>). The kernel allocates
+memory for the passed data as an integral number of pages.
+<p>
+This interface is machine word length dependent because of the virtual address
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ADDRESS</strong>
+<dd>
+The specified address is illegal or reserved.
+<p>
+<dt> <strong>KERN_NO_SPACE</strong>
+<dd>
+There is not enough space in the task's address space to allocate the
+new region.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>,
+<a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
+<a href="vm_protect.html"><strong>vm_protect</strong></a>,
+<a href="vm_region.html"><strong>vm_region</strong></a>,
+<a href="host_page_size.html"><strong>host_page_size</strong></a>.
+
-<h2>vm_behavior_set</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Specify expected access patterns for the target VM region.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_behavior_set</strong>
\r <strong>(vm_task_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>address</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>vm_behavior_t</strong> <var>behavior</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task in whose address space the
\rmemory object behavior is to be set.
\r<p>
\r<dt> <var>address</var>
\r<dd>
\r[in scalar]
\rThe starting address for the memory region.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes in the region.
\r<p>
\r<dt> <var>behavior</var>
\r<dd>
\r[in scalar]
\rThe expected reference pattern for the memory. Possible
\rvalues are:
\r<dl>
\r<p>
\r<dt> <strong>VM_BEHAVIOR_DEFAULT</strong>
\r<dd>
\rThe system's default behavior. Assumes strong locality of
\rreference, so LRU page replacement, possibly with pre-fetch,
\rwould be appropriate.
\r<p>
\r<dt> <strong>VM_BEHAVIOR_RANDOM</strong>
\r<dd>
\rNo particular order expected. Assumes weak locality of
\rreference, so LRU page replacement may be ineffective.
\r<p>
\r<dt> <strong>VM_BEHAVIOR_SEQUENTIAL</strong>
\r<dd>
\rForward sequential order.
\r<p>
\r<dt> <strong>VM_BEHAVIOR_RSEQNTL</strong>
\r<dd>
\rReverse sequential order.
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_behavior_set</strong> function informs the kernel of
\rthe expected access
\rpattern for a region of memory. The kernel uses this information
\rto bias its prefetch and page
\rreplacement algorithms.
\r<p>
\rThe region starts at the beginning of the virtual page containing
\r<var>address</var>; it ends at the end of the virtual page containing
\r<var>address</var> + <var>size</var> - 1. Because of this
\rrounding to virtual page boundaries, the amount of memory affected may be
\rgreater than <var>size</var>. Use <strong>host_page_size</strong>
\rto find the current virtual page size.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the virtual address
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ADDRESS</strong>
\r<dd>
\rThe specified address is illegal or reserved.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_region.html"><strong>vm_region</strong></a>,
\r<a href="host_page_size.html"><strong>host_page_size</strong></a>.
\r\ No newline at end of file
+<h2>vm_behavior_set</h2>
+<hr>
+<p>
+<strong>Function</strong> - Specify expected access patterns for the target VM region.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t vm_behavior_set</strong>
+ <strong>(vm_task_t</strong> <var>target_task</var>,
+ <strong>vm_address_t</strong> <var>address</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>vm_behavior_t</strong> <var>behavior</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The port for the task in whose address space the
+memory object behavior is to be set.
+<p>
+<dt> <var>address</var>
+<dd>
+[in scalar]
+The starting address for the memory region.
+<p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The number of bytes in the region.
+<p>
+<dt> <var>behavior</var>
+<dd>
+[in scalar]
+The expected reference pattern for the memory. Possible
+values are:
+<dl>
+<p>
+<dt> <strong>VM_BEHAVIOR_DEFAULT</strong>
+<dd>
+The system's default behavior. Assumes strong locality of
+reference, so LRU page replacement, possibly with pre-fetch,
+would be appropriate.
+<p>
+<dt> <strong>VM_BEHAVIOR_RANDOM</strong>
+<dd>
+No particular order expected. Assumes weak locality of
+reference, so LRU page replacement may be ineffective.
+<p>
+<dt> <strong>VM_BEHAVIOR_SEQUENTIAL</strong>
+<dd>
+Forward sequential order.
+<p>
+<dt> <strong>VM_BEHAVIOR_RSEQNTL</strong>
+<dd>
+Reverse sequential order.
+</dl>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_behavior_set</strong> function informs the kernel of
+the expected access
+pattern for a region of memory. The kernel uses this information
+to bias its prefetch and page
+replacement algorithms.
+<p>
+The region starts at the beginning of the virtual page containing
+<var>address</var>; it ends at the end of the virtual page containing
+<var>address</var> + <var>size</var> - 1. Because of this
+rounding to virtual page boundaries, the amount of memory affected may be
+greater than <var>size</var>. Use <strong>host_page_size</strong>
+to find the current virtual page size.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the virtual address
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ADDRESS</strong>
+<dd>
+The specified address is illegal or reserved.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="vm_region.html"><strong>vm_region</strong></a>,
+<a href="host_page_size.html"><strong>host_page_size</strong></a>.
-<h2>vm_copy</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Copy a region of virtual memory.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_copy</strong>
\r <strong>(vm_task_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>source_address</var>,
\r <strong>vm_size_t</strong> <var>count</var>,
\r <strong>vm_address_t</strong> <var>dest_address</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task whose memory is to be copied.
\r<p>
\r<dt> <var>source_address</var>
\r<dd>
\r[in scalar]
\rThe starting address for the source region. The address must
\rbe on a page boundary.
\r<p>
\r<dt> <var>count</var>
\r<dd>
\r[in scalar]
\rThe number of bytes in the source region. The number of
\rbytes must convert to an integral number of virtual pages.
\r<p>
\r<dt> <var>dest_address</var>
\r<dd>
\r[in scalar]
\rThe starting address for the destination region. The address
\rmust be on a page boundary.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_copy</strong> function copies a source region to a destination
\rregion within the
\rsame task's virtual memory. It is semantically equivalent to
\r<strong>vm_read</strong> followed
\rby <strong>vm_write</strong>. The destination region can overlap the source region.
\r<p>
\rThe destination region must already be allocated. The source region must be
\rreadable, and the destination region must be writable.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the virtual address
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_PROTECTION_FAILURE</strong>
\r<dd>
\rThe source region is protected against reading, or the destination
\rregion is protected against writing.
\r<p>
\r<dt> <strong>KERN_INVALID_ADDRESS</strong>
\r<dd>
\rAn address is illegal or specifies a non-allocated region, or there is not
\renough memory following one of the addresses.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_protect.html"><strong>vm_protect</strong></a>,
\r<a href="vm_read.html"><strong>vm_read</strong></a>,
\r<a href="vm_write.html"><strong>vm_write</strong></a>,
\r<a href="host_page_size.html"><strong>host_page_size</strong></a>.
\r\ No newline at end of file
+<h2>vm_copy</h2>
+<hr>
+<p>
+<strong>Function</strong> - Copy a region of virtual memory.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t vm_copy</strong>
+ <strong>(vm_task_t</strong> <var>target_task</var>,
+ <strong>vm_address_t</strong> <var>source_address</var>,
+ <strong>vm_size_t</strong> <var>count</var>,
+ <strong>vm_address_t</strong> <var>dest_address</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The port for the task whose memory is to be copied.
+<p>
+<dt> <var>source_address</var>
+<dd>
+[in scalar]
+The starting address for the source region. The address must
+be on a page boundary.
+<p>
+<dt> <var>count</var>
+<dd>
+[in scalar]
+The number of bytes in the source region. The number of
+bytes must convert to an integral number of virtual pages.
+<p>
+<dt> <var>dest_address</var>
+<dd>
+[in scalar]
+The starting address for the destination region. The address
+must be on a page boundary.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_copy</strong> function copies a source region to a destination
+region within the
+same task's virtual memory. It is semantically equivalent to
+<strong>vm_read</strong> followed
+by <strong>vm_write</strong>. The destination region can overlap the source region.
+<p>
+The destination region must already be allocated. The source region must be
+readable, and the destination region must be writable.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the virtual address
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_PROTECTION_FAILURE</strong>
+<dd>
+The source region is protected against reading, or the destination
+region is protected against writing.
+<p>
+<dt> <strong>KERN_INVALID_ADDRESS</strong>
+<dd>
+An address is illegal or specifies a non-allocated region, or there is not
+enough memory following one of the addresses.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="vm_protect.html"><strong>vm_protect</strong></a>,
+<a href="vm_read.html"><strong>vm_read</strong></a>,
+<a href="vm_write.html"><strong>vm_write</strong></a>,
+<a href="host_page_size.html"><strong>host_page_size</strong></a>.
-<h2>vm_deallocate</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Deallocate a region of virtual memory.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_deallocate</strong>
\r <strong>(vm_task_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>address</var>,
\r <strong>vm_size_t</strong> <var>size</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task in whose address space the
\rregion is to be deallocated.
\r<p>
\r<dt> <var>address</var>
\r<dd>
\r[in scalar]
\rThe starting address for the region.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes to deallocate.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_deallocate</strong> function deallocates a region of
\rvirtual memory in the
\rspecified task's address space.
\rThe region starts at the beginning of the virtual page containing
\r<var>address</var> and ends
\rat the end of the virtual page containing <var>address</var>
\r+ <var>size</var> - 1. Because of this
\rrounding to virtual page boundaries, the amount of memory deallocated may be
\rgreater than <var>size</var>. Use <strong>host_page_size</strong>
\rto find the current virtual page size.
\r<p>
\r<strong>vm_deallocate</strong> affects only <var>target_task</var>. Other tasks
\rthat have access to the deallocated memory can continue to reference it.
\r<h3>NOTES</h3>
\r<p>
\r<strong>vm_deallocate</strong> can be used to deallocate memory passed
\ras out-of-line data in a
\rmessage.
\r<p>
\rThis interface is machine word length specific because of the virtual address
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ADDRESS</strong>
\r<dd>
\rThe address is illegal or specifies a non-allocated region.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="mach_msg.html"><strong>mach_msg</strong></a>,
\r<a href="vm_allocate.html"><strong>vm_allocate</strong></a>,
\r<a href="vm_map.html"><strong>vm_map</strong></a>,
\r<a href="host_page_size.html"><strong>host_page_size</strong></a>.
\r\ No newline at end of file
+<h2>vm_deallocate</h2>
+<hr>
+<p>
+<strong>Function</strong> - Deallocate a region of virtual memory.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t vm_deallocate</strong>
+ <strong>(vm_task_t</strong> <var>target_task</var>,
+ <strong>vm_address_t</strong> <var>address</var>,
+ <strong>vm_size_t</strong> <var>size</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The port for the task in whose address space the
+region is to be deallocated.
+<p>
+<dt> <var>address</var>
+<dd>
+[in scalar]
+The starting address for the region.
+<p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The number of bytes to deallocate.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_deallocate</strong> function deallocates a region of
+virtual memory in the
+specified task's address space.
+The region starts at the beginning of the virtual page containing
+<var>address</var> and ends
+at the end of the virtual page containing <var>address</var>
++ <var>size</var> - 1. Because of this
+rounding to virtual page boundaries, the amount of memory deallocated may be
+greater than <var>size</var>. Use <strong>host_page_size</strong>
+to find the current virtual page size.
+<p>
+<strong>vm_deallocate</strong> affects only <var>target_task</var>. Other tasks
+that have access to the deallocated memory can continue to reference it.
+<h3>NOTES</h3>
+<p>
+<strong>vm_deallocate</strong> can be used to deallocate memory passed
+as out-of-line data in a
+message.
+<p>
+This interface is machine word length specific because of the virtual address
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ADDRESS</strong>
+<dd>
+The address is illegal or specifies a non-allocated region.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="mach_msg.html"><strong>mach_msg</strong></a>,
+<a href="vm_allocate.html"><strong>vm_allocate</strong></a>,
+<a href="vm_map.html"><strong>vm_map</strong></a>,
+<a href="host_page_size.html"><strong>host_page_size</strong></a>.
-<h2>vm_inherit</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set a VM region's inheritance attribute.
\r<p>
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_inherit</strong>
\r <strong>(vm_task_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>address</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>vm_inherit_t</strong> <var>new_inheritance</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task whose address space contains
\rthe region.
\r<p>
\r<dt> <var>address</var>
\r<dd>
\r[in scalar]
\rThe starting address for the region.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes in the region.
\r<p>
\r<dt> <var>new_inheritance</var>
\r<dd>
\r[in scalar]
\rThe new inheritance attribute for the region. Valid values are:
\r<dl>
\r<p>
\r<dt> <strong>VM_INHERIT_SHARE</strong>
\r<dd>
\rAllows child tasks to share the region.
\r<p>
\r<dt> <strong>VM_INHERIT_COPY</strong>
\r<dd>
\rGives child tasks a copy of the region.
\r<p>
\r<dt> <strong>VM_INHERIT_NONE</strong>
\r<dd>
\rProvides no access to the region for child tasks.
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_inherit</strong> function sets the inheritance attribute
\rfor a region within the
\rspecified task's address space. The inheritance attribute determines
\rthe type of
\raccess established for child tasks at task creation.
\r<p>
\rBecause inheritance applies to virtual pages, the specified <var>address</var>
\rand <var>size</var> are
\rrounded to page boundaries, as follows: the region starts at
\rthe beginning of the
\rvirtual page containing <var>address</var>; it ends at the end of the virtual
\rpage containing
\r<var>address</var> + <var>size</var> - 1.
\rBecause of this rounding to virtual page boundaries, the
\ramount of memory affected may be greater than <var>size</var>. Use
\r<strong>host_page_size</strong> to find the current virtual page size.
\r<p>
\rA parent and a child task can share the same physical memory only if the
\rinheritance for the memory is set to <strong>VM_INHERIT_SHARE</strong> before
\rthe child task is
\rcreated. Other than through the use of an external memory manager (see
\r<strong>vm_map</strong>), this is the only way that two tasks can share memory.
\r<p>
\rNote that all the threads within a task share the task's memory.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the virtual address
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ADDRESS</strong>
\r<dd>
\rThe address is illegal or specifies a non-allocated region.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_create.html"><strong>task_create</strong></a>,
\r<a href="vm_map.html"><strong>vm_map</strong></a>,
\r<a href="vm_region.html"><strong>vm_region</strong></a>,
\r<a href="norma_task_clone.html"><strong>norma_task_create</strong></a>.
\r\ No newline at end of file
+<h2>vm_inherit</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set a VM region's inheritance attribute.
+<p>
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t vm_inherit</strong>
+ <strong>(vm_task_t</strong> <var>target_task</var>,
+ <strong>vm_address_t</strong> <var>address</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>vm_inherit_t</strong> <var>new_inheritance</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The port for the task whose address space contains
+the region.
+<p>
+<dt> <var>address</var>
+<dd>
+[in scalar]
+The starting address for the region.
+<p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The number of bytes in the region.
+<p>
+<dt> <var>new_inheritance</var>
+<dd>
+[in scalar]
+The new inheritance attribute for the region. Valid values are:
+<dl>
+<p>
+<dt> <strong>VM_INHERIT_SHARE</strong>
+<dd>
+Allows child tasks to share the region.
+<p>
+<dt> <strong>VM_INHERIT_COPY</strong>
+<dd>
+Gives child tasks a copy of the region.
+<p>
+<dt> <strong>VM_INHERIT_NONE</strong>
+<dd>
+Provides no access to the region for child tasks.
+</dl>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_inherit</strong> function sets the inheritance attribute
+for a region within the
+specified task's address space. The inheritance attribute determines
+the type of
+access established for child tasks at task creation.
+<p>
+Because inheritance applies to virtual pages, the specified <var>address</var>
+and <var>size</var> are
+rounded to page boundaries, as follows: the region starts at
+the beginning of the
+virtual page containing <var>address</var>; it ends at the end of the virtual
+page containing
+<var>address</var> + <var>size</var> - 1.
+Because of this rounding to virtual page boundaries, the
+amount of memory affected may be greater than <var>size</var>. Use
+<strong>host_page_size</strong> to find the current virtual page size.
+<p>
+A parent and a child task can share the same physical memory only if the
+inheritance for the memory is set to <strong>VM_INHERIT_SHARE</strong> before
+the child task is
+created. Other than through the use of an external memory manager (see
+<strong>vm_map</strong>), this is the only way that two tasks can share memory.
+<p>
+Note that all the threads within a task share the task's memory.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the virtual address
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ADDRESS</strong>
+<dd>
+The address is illegal or specifies a non-allocated region.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_create.html"><strong>task_create</strong></a>,
+<a href="vm_map.html"><strong>vm_map</strong></a>,
+<a href="vm_region.html"><strong>vm_region</strong></a>,
+<a href="norma_task_clone.html"><strong>norma_task_create</strong></a>.
-<h2>vm_machine_attribute</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Get/set the target memory region's special attributes.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_machine_attribute</strong>
\r <strong>(vm_task_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>address</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>vm_machine_attribute_t</strong> <var>attribute</var>,
\r <strong>vm_machine_attribute_val_t</strong> <var>value</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task in whose address space the
\rmemory object is to be manipulated.
\r<p>
\r<dt> <var>address</var>
\r<dd>
\r[in scalar]
\rThe starting address for the memory region. The granularity
\rof rounding of this value to page boundaries is implementation
\rdependent.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes in the region. The granularity of
\rrounding of this value to page boundaries is implementation dependent.
\r<p>
\r<dt> <var>attribute</var>
\r<dd>
\r[in scalar]
\rThe name of the attribute to be get/set. Possible values are:
\r<dl>
\r<p>
\r<dt> <strong>MATTR_CACHE</strong>
\r<dd>
\rCachability. Aside from the generic values listed below, the
\rfollowing special values are defined:
\r<dl>
\r<p>
\r<dt> <strong>MATTR_VAL_CACHE_FLUSH</strong>
\r<dd>
\rFlush from all caches
\r<p>
\r<dt> <strong>MATTR_VAL_DCACHE_FLUSH</strong>
\r<dd>
\rFlush from data caches
\r<p>
\r<dt> <strong>MATTR_VAL_ICACHE_FLUSH</strong>
\r<dd>
\rFlush from instruction caches
\r</dl>
\r<p>
\r<dt> <strong>MATTR_MIGRATE</strong>
\r<dd>
\rMigratability.
\r<p>
\r<dt> <strong>MATTR_REPLICATE</strong>
\r<dd>
\rReplicability.
\r</dl>
\r<p>
\r<dt> <var>value</var>
\r<dd>
\r[pointer to in/out scalar]
\rThe new value for the attribute. The old value
\ris also returned in this variable. The new value can be a specific value
\rlisted above, or one of the following generic values:
\r<dl>
\r<p>
\r<dt> <strong>MATTR_VAL_OFF</strong>
\r<dd>
\rTurn attribute off.
\r<p>
\r<dt> <strong>MATTR_VAL_ON</strong>
\r<dd>
\rTurn attribute on.
\r<p>
\r<dt> <strong>MATTR_VAL_GET</strong>
\r<dd>
\rNo change, just return current value.
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_machine_attribute</strong> function gets and sets special
\rattributes of the
\rmemory region implemented by the underlying <strong>pmap</strong> module. These attributes
\rare properties such as cachability, migratability and replicability.
\rThe behavior of this function is machine dependent.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the virtual address
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ADDRESS</strong>
\r<dd>
\rThe address is illegal or specifies a non-allocated region.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_wire.html"><strong>vm_wire</strong></a>.
\r\ No newline at end of file
+<h2>vm_machine_attribute</h2>
+<hr>
+<p>
+<strong>Function</strong> - Get/set the target memory region's special attributes.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t vm_machine_attribute</strong>
+ <strong>(vm_task_t</strong> <var>target_task</var>,
+ <strong>vm_address_t</strong> <var>address</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>vm_machine_attribute_t</strong> <var>attribute</var>,
+ <strong>vm_machine_attribute_val_t</strong> <var>value</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The port for the task in whose address space the
+memory object is to be manipulated.
+<p>
+<dt> <var>address</var>
+<dd>
+[in scalar]
+The starting address for the memory region. The granularity
+of rounding of this value to page boundaries is implementation
+dependent.
+<p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The number of bytes in the region. The granularity of
+rounding of this value to page boundaries is implementation dependent.
+<p>
+<dt> <var>attribute</var>
+<dd>
+[in scalar]
+The name of the attribute to be get/set. Possible values are:
+<dl>
+<p>
+<dt> <strong>MATTR_CACHE</strong>
+<dd>
+Cachability. Aside from the generic values listed below, the
+following special values are defined:
+<dl>
+<p>
+<dt> <strong>MATTR_VAL_CACHE_FLUSH</strong>
+<dd>
+Flush from all caches
+<p>
+<dt> <strong>MATTR_VAL_DCACHE_FLUSH</strong>
+<dd>
+Flush from data caches
+<p>
+<dt> <strong>MATTR_VAL_ICACHE_FLUSH</strong>
+<dd>
+Flush from instruction caches
+</dl>
+<p>
+<dt> <strong>MATTR_MIGRATE</strong>
+<dd>
+Migratability.
+<p>
+<dt> <strong>MATTR_REPLICATE</strong>
+<dd>
+Replicability.
+</dl>
+<p>
+<dt> <var>value</var>
+<dd>
+[pointer to in/out scalar]
+The new value for the attribute. The old value
+is also returned in this variable. The new value can be a specific value
+listed above, or one of the following generic values:
+<dl>
+<p>
+<dt> <strong>MATTR_VAL_OFF</strong>
+<dd>
+Turn attribute off.
+<p>
+<dt> <strong>MATTR_VAL_ON</strong>
+<dd>
+Turn attribute on.
+<p>
+<dt> <strong>MATTR_VAL_GET</strong>
+<dd>
+No change, just return current value.
+</dl>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_machine_attribute</strong> function gets and sets special
+attributes of the
+memory region implemented by the underlying <strong>pmap</strong> module. These attributes
+are properties such as cachability, migratability and replicability.
+The behavior of this function is machine dependent.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the virtual address
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ADDRESS</strong>
+<dd>
+The address is illegal or specifies a non-allocated region.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="vm_wire.html"><strong>vm_wire</strong></a>.
-<h2>vm_map</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Map the specified memory object to a region of virtual memory.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_map</strong>
\r <strong>(vm_task_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>address</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>vm_address_t</strong> <var>mask</var>,
\r <strong>boolean_t</strong> <var>anywhere</var>,
\r <strong>memory_object_t</strong> <var>memory_object</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>boolean_t</strong> <var>copy</var>,
\r <strong>vm_prot_t</strong> <var>cur_protection</var>,
\r <strong>vm_prot_t</strong> <var>max_protection</var>,
\r <strong>vm_inherit_t</strong> <var>inheritance</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task in whose address space the
\rmemory object is to be mapped.
\r<p>
\r<dt> <var>address</var>
\r<dd>
\r[pointer to in/out scalar]
\rThe starting address for the mapped object.
\rThe mapped object will start at the beginning of the page containing
\r<var>address</var>. If there is not enough room following the address, the kernel
\rdoes not map the object. The kernel returns the starting address
\ractually used for the mapped object.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes to allocate for the object. The kernel
\rrounds this number up to an integral number of virtual pages.
\r<p>
\r<dt> <var>mask</var>
\r<dd>
\r[in scalar]
\rAlignment restrictions for starting address. Bits turned on in
\rthe mask will not be turned on in the starting address.
\r<p>
\r<dt> <var>anywhere</var>
\r<dd>
\r[in scalar]
\rPlacement indicator. The valid values are:
\r<dl>
\r<p>
\r<dt> <strong>TRUE</strong>
\r<dd>
\rThe kernel allocates the region in the next unused space that
\ris sufficient within the address space. The kernel returns the
\rstarting address actually used in <var>address</var>.
\r<p>
\r<dt> <strong>FALSE</strong>
\r<dd>
\rThe kernel allocates the region starting at <var>address</var> unless that
\rspace is already allocated.
\r</dl>
\r<p>
\r<dt> <var>memory_object</var>
\r<dd>
\r[in memory-object send right]
\rThe port naming the
\rmemory object. If <strong>MEMORY_OBJECT_NULL</strong> is
\rspecified, the kernel allocates zero-filled memory, as with <strong>vm_allocate</strong>.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar]
\rAn offset within the memory object, in bytes. The kernel
\rmaps <var>address</var> to the specified offset.
\r<p>
\r<dt> <var>copy</var>
\r<dd>
\r[in scalar]
\rCopy indicator. If true, the kernel copies the region of the
\rmemory object to the specified task's address space. If false, the region
\ris directly mapped.
\r<p>
\r<dt> <var>cur_protection</var>
\r<dd>
\r[in scalar]
\rThe initial current protection for the region. Valid values are
\robtained by or'ing together the following values:
\r<dl>
\r<p>
\r<dt> <strong>VM_PROT_READ</strong>
\r<dd>
\rAllows read access.
\r<p>
\r<dt> <strong>VM_PROT_WRITE</strong>
\r<dd>
\rAllows write access.
\r<p>
\r<dt> <strong>VM_PROT_EXECUTE</strong>
\r<dd>
\rAllows execute access.
\r</dl>
\r<p>
\r<dt> <var>max_protection</var>
\r<dd>
\r[in scalar]
\rThe maximum protection for the region. Values are the same
\ras for <var>cur_protection</var>.
\r<p>
\r<dt> <var>inheritance</var>
\r<dd>
\r[in scalar]
\rThe initial inheritance attribute for the region. Valid values
\rare:
\r<dl>
\r<p>
\r<dt> <strong>VM_INHERIT_SHARE</strong>
\r<dd>
\rAllows child tasks to share the region.
\r<p>
\r<dt> <strong>VM_INHERIT_COPY</strong>
\r<dd>
\rGives child tasks a copy of the region.
\r<p>
\r<dt> <strong>VM_INHERIT_NONE</strong>
\r<dd>
\rProvides no access to the region for child tasks.
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_map</strong> function maps a portion of the specified
\rmemory object into the
\rvirtual address space belonging to <var>target_task</var>. The target task
\rcan be the calling
\rtask or another task, identified by its task kernel port.
\r<p>
\rThe portion of the memory object mapped is determined by <var>offset</var>
\rand <var>size</var>. The
\rkernel maps <var>address</var> to the offset, so that an access to the memory
\rstarts at the offset in the object.
\r<p>
\rThe <var>mask</var> parameter specifies additional alignment restrictions on
\rthe kernel's selection of the starting address. Uses for this mask include:
\r<ul>
\r<li>
\rForcing the memory address alignment for a mapping to be the same as the
\ralignment within the memory object.
\r<li>
\rQuickly finding the beginning of an allocated region by performing bit
\rarithmetic on an address known to be in the region.
\r<li>
\rEmulating a larger virtual page size.
\r</ul>
\r<p>
\rThe <var>cur_protection</var>, <var>max_protection</var>, and <var>inheritance</var>
\rparameters set the
\rprotection and inheritance attributes for the mapped object.
\rAs a rule, at least the
\rmaximum protection should be specified so that a server can make
\ra restricted (for
\rexample, read-only) mapping in a client atomically. The current
\rprotection and
\rinheritance parameters are provided for convenience so that the
\rcaller does not
\rhave to call <strong>vm_inherit</strong> and <strong>vm_protect</strong> separately.
\r<p>
\rThe same memory object can be mapped more than once and by more than one
\rtask. If an object is mapped by multiple tasks, the kernel maintains
\rconsistency
\rfor all the mappings if they use the same page alignment for <var>offset</var>
\rand are on
\rthe same host. In this case, the virtual memory to which the
\robject is mapped is
\rshared by all the tasks. Changes made by one task in its address space are
\rvisible to all the other tasks.
\rThe call will not return until the
\rmemory object is ready for
\ruse.
\r<h3>NOTES</h3>
\r<p>
\r<strong>vm_map</strong> allocates a region in a task's address space
\rand maps the specified
\rmemory object to this region. <strong>vm_allocate</strong> allocates
\ra zero-filled temporary
\rregion in a task's address space.
\r<p>
\rBefore a memory object can be mapped, a port naming it must be acquired from
\rthe memory manager serving it.
\r<p>
\rThis interface is machine word length specific because of the virtual address
\rparameter.
\r<h3>CAUTIONS</h3>
\r<p>
\rDo not attempt to map a memory object unless it has been provided by a
\rmemory manager that implements the memory object interface.
\rIf another type of port
\ris specified, a thread that accesses the mapped virtual memory may become
\rpermanently hung or may receive a memory exception.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_NO_SPACE</strong>
\r<dd>
\rThere is not enough space in the task's address space to allocate the
\rnew region for the memory object.
\r<p>
\r<dt> <strong>KERN_PROTECTION_FAILURE</strong>
\r<dd>
\r<var>max_protection</var> or <var>cur_protection</var> exceeds
\rthat permitted by <var>memory_object</var>.
\r<p>
\r<dt> <strong>KERN_INVALID_OBJECT</strong>
\r<dd>
\rThe memory manager failed to map the memory object.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_allocate.html"><strong>vm_allocate</strong></a>,
\r<a href="vm_remap.html"><strong>vm_remap</strong></a>.
\r\ No newline at end of file
+<h2>vm_map</h2>
+<hr>
+<p>
+<strong>Function</strong> - Map the specified memory object to a region of virtual memory.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t vm_map</strong>
+ <strong>(vm_task_t</strong> <var>target_task</var>,
+ <strong>vm_address_t</strong> <var>address</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>vm_address_t</strong> <var>mask</var>,
+ <strong>boolean_t</strong> <var>anywhere</var>,
+ <strong>memory_object_t</strong> <var>memory_object</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>boolean_t</strong> <var>copy</var>,
+ <strong>vm_prot_t</strong> <var>cur_protection</var>,
+ <strong>vm_prot_t</strong> <var>max_protection</var>,
+ <strong>vm_inherit_t</strong> <var>inheritance</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The port for the task in whose address space the
+memory object is to be mapped.
+<p>
+<dt> <var>address</var>
+<dd>
+[pointer to in/out scalar]
+The starting address for the mapped object.
+The mapped object will start at the beginning of the page containing
+<var>address</var>. If there is not enough room following the address, the kernel
+does not map the object. The kernel returns the starting address
+actually used for the mapped object.
+<p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The number of bytes to allocate for the object. The kernel
+rounds this number up to an integral number of virtual pages.
+<p>
+<dt> <var>mask</var>
+<dd>
+[in scalar]
+Alignment restrictions for starting address. Bits turned on in
+the mask will not be turned on in the starting address.
+<p>
+<dt> <var>anywhere</var>
+<dd>
+[in scalar]
+Placement indicator. The valid values are:
+<dl>
+<p>
+<dt> <strong>TRUE</strong>
+<dd>
+The kernel allocates the region in the next unused space that
+is sufficient within the address space. The kernel returns the
+starting address actually used in <var>address</var>.
+<p>
+<dt> <strong>FALSE</strong>
+<dd>
+The kernel allocates the region starting at <var>address</var> unless that
+space is already allocated.
+</dl>
+<p>
+<dt> <var>memory_object</var>
+<dd>
+[in memory-object send right]
+The port naming the
+memory object. If <strong>MEMORY_OBJECT_NULL</strong> is
+specified, the kernel allocates zero-filled memory, as with <strong>vm_allocate</strong>.
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar]
+An offset within the memory object, in bytes. The kernel
+maps <var>address</var> to the specified offset.
+<p>
+<dt> <var>copy</var>
+<dd>
+[in scalar]
+Copy indicator. If true, the kernel copies the region of the
+memory object to the specified task's address space. If false, the region
+is directly mapped.
+<p>
+<dt> <var>cur_protection</var>
+<dd>
+[in scalar]
+The initial current protection for the region. Valid values are
+obtained by or'ing together the following values:
+<dl>
+<p>
+<dt> <strong>VM_PROT_READ</strong>
+<dd>
+Allows read access.
+<p>
+<dt> <strong>VM_PROT_WRITE</strong>
+<dd>
+Allows write access.
+<p>
+<dt> <strong>VM_PROT_EXECUTE</strong>
+<dd>
+Allows execute access.
+</dl>
+<p>
+<dt> <var>max_protection</var>
+<dd>
+[in scalar]
+The maximum protection for the region. Values are the same
+as for <var>cur_protection</var>.
+<p>
+<dt> <var>inheritance</var>
+<dd>
+[in scalar]
+The initial inheritance attribute for the region. Valid values
+are:
+<dl>
+<p>
+<dt> <strong>VM_INHERIT_SHARE</strong>
+<dd>
+Allows child tasks to share the region.
+<p>
+<dt> <strong>VM_INHERIT_COPY</strong>
+<dd>
+Gives child tasks a copy of the region.
+<p>
+<dt> <strong>VM_INHERIT_NONE</strong>
+<dd>
+Provides no access to the region for child tasks.
+</dl>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_map</strong> function maps a portion of the specified
+memory object into the
+virtual address space belonging to <var>target_task</var>. The target task
+can be the calling
+task or another task, identified by its task kernel port.
+<p>
+The portion of the memory object mapped is determined by <var>offset</var>
+and <var>size</var>. The
+kernel maps <var>address</var> to the offset, so that an access to the memory
+starts at the offset in the object.
+<p>
+The <var>mask</var> parameter specifies additional alignment restrictions on
+the kernel's selection of the starting address. Uses for this mask include:
+<ul>
+<li>
+Forcing the memory address alignment for a mapping to be the same as the
+alignment within the memory object.
+<li>
+Quickly finding the beginning of an allocated region by performing bit
+arithmetic on an address known to be in the region.
+<li>
+Emulating a larger virtual page size.
+</ul>
+<p>
+The <var>cur_protection</var>, <var>max_protection</var>, and <var>inheritance</var>
+parameters set the
+protection and inheritance attributes for the mapped object.
+As a rule, at least the
+maximum protection should be specified so that a server can make
+a restricted (for
+example, read-only) mapping in a client atomically. The current
+protection and
+inheritance parameters are provided for convenience so that the
+caller does not
+have to call <strong>vm_inherit</strong> and <strong>vm_protect</strong> separately.
+<p>
+The same memory object can be mapped more than once and by more than one
+task. If an object is mapped by multiple tasks, the kernel maintains
+consistency
+for all the mappings if they use the same page alignment for <var>offset</var>
+and are on
+the same host. In this case, the virtual memory to which the
+object is mapped is
+shared by all the tasks. Changes made by one task in its address space are
+visible to all the other tasks.
+The call will not return until the
+memory object is ready for
+use.
+<h3>NOTES</h3>
+<p>
+<strong>vm_map</strong> allocates a region in a task's address space
+and maps the specified
+memory object to this region. <strong>vm_allocate</strong> allocates
+a zero-filled temporary
+region in a task's address space.
+<p>
+Before a memory object can be mapped, a port naming it must be acquired from
+the memory manager serving it.
+<p>
+This interface is machine word length specific because of the virtual address
+parameter.
+<h3>CAUTIONS</h3>
+<p>
+Do not attempt to map a memory object unless it has been provided by a
+memory manager that implements the memory object interface.
+If another type of port
+is specified, a thread that accesses the mapped virtual memory may become
+permanently hung or may receive a memory exception.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_NO_SPACE</strong>
+<dd>
+There is not enough space in the task's address space to allocate the
+new region for the memory object.
+<p>
+<dt> <strong>KERN_PROTECTION_FAILURE</strong>
+<dd>
+<var>max_protection</var> or <var>cur_protection</var> exceeds
+that permitted by <var>memory_object</var>.
+<p>
+<dt> <strong>KERN_INVALID_OBJECT</strong>
+<dd>
+The memory manager failed to map the memory object.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="vm_allocate.html"><strong>vm_allocate</strong></a>,
+<a href="vm_remap.html"><strong>vm_remap</strong></a>.
-<h2>vm_msync</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Synchronize the specified region of virtual memory.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_msync</strong>
\r <strong>(vm_task_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>address</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>target_task</strong> <var>sync_flags</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task whose address space contains
\rthe region.
\r<p>
\r<dt> <var>address</var>
\r<dd>
\r[in scalar]
\rThe starting address for the region.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes in the region.
\r<p>
\r<dt> <var>sync_flags</var>
\r<dd>
\r[in scalar]
\rThe bit-wise <strong>OR</strong> of flags affecting the synchronization.
\rSpecifying both <strong>VM_SYNC_SYNCHRONOUS</strong> and
\r<strong>VM_SYNC_ASYNCHRONOUS</strong> is invalid.
\r<dl>
\r<p>
\r<dt> <strong>VM_SYNC_INVALIDATE</strong>
\r<dd>
\rFlushes pages in the range. Only precious pages are returned to
\rthe memory manager unless either <strong>VM_SYNC_SYNCHRONOUS</strong> or
\r<strong>VM_SYNC_ASYNCHRONOUS</strong> is also set.
\r<p>
\r<dt> <strong>VM_SYNC_SYNCHRONOUS</strong>
\r<dd>
\rWrites dirty and precious pages back to the memory manager,
\rwaits for pages to reach backing storage.
\r<p>
\r<dt> <strong>VM_SYNC_ASYNCHRONOUS</strong>
\r<dd>
\rWrites dirty and precious pages back to the memory manager,
\rreturns without waiting for pages to reach backing storage.
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_msync</strong> function synchronizes the contents of
\ra memory range with its
\rbacking store image by flushing or cleaning the contents of the
\rspecified range
\rto the range's memory manager, engaging in a synchronization protocol with
\rthe manager (<strong>memory_object_synchronize</strong>).
\rThe client does not return from
\rthis call until the memory manager responds (to the kernel) with
\r<strong>memory_object_synchronize_completed</strong>.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the virtual address
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ADDRESS</strong>
\r<dd>
\rThe address is illegal or specifies a non-allocated region.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>,
\r<a href="MO_SY_completed.html"><strong>memory_object_synchronize_completed</strong></a>.
\r\ No newline at end of file
+<h2>vm_msync</h2>
+<hr>
+<p>
+<strong>Function</strong> - Synchronize the specified region of virtual memory.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t vm_msync</strong>
+ <strong>(vm_task_t</strong> <var>target_task</var>,
+ <strong>vm_address_t</strong> <var>address</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>target_task</strong> <var>sync_flags</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The port for the task whose address space contains
+the region.
+<p>
+<dt> <var>address</var>
+<dd>
+[in scalar]
+The starting address for the region.
+<p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The number of bytes in the region.
+<p>
+<dt> <var>sync_flags</var>
+<dd>
+[in scalar]
+The bit-wise <strong>OR</strong> of flags affecting the synchronization.
+Specifying both <strong>VM_SYNC_SYNCHRONOUS</strong> and
+<strong>VM_SYNC_ASYNCHRONOUS</strong> is invalid.
+<dl>
+<p>
+<dt> <strong>VM_SYNC_INVALIDATE</strong>
+<dd>
+Flushes pages in the range. Only precious pages are returned to
+the memory manager unless either <strong>VM_SYNC_SYNCHRONOUS</strong> or
+<strong>VM_SYNC_ASYNCHRONOUS</strong> is also set.
+<p>
+<dt> <strong>VM_SYNC_SYNCHRONOUS</strong>
+<dd>
+Writes dirty and precious pages back to the memory manager,
+waits for pages to reach backing storage.
+<p>
+<dt> <strong>VM_SYNC_ASYNCHRONOUS</strong>
+<dd>
+Writes dirty and precious pages back to the memory manager,
+returns without waiting for pages to reach backing storage.
+</dl>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_msync</strong> function synchronizes the contents of
+a memory range with its
+backing store image by flushing or cleaning the contents of the
+specified range
+to the range's memory manager, engaging in a synchronization protocol with
+the manager (<strong>memory_object_synchronize</strong>).
+The client does not return from
+this call until the memory manager responds (to the kernel) with
+<strong>memory_object_synchronize_completed</strong>.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the virtual address
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ADDRESS</strong>
+<dd>
+The address is illegal or specifies a non-allocated region.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_synchronize.html"><strong>memory_object_synchronize</strong></a>,
+<a href="MO_SY_completed.html"><strong>memory_object_synchronize_completed</strong></a>.
-<h2>vm_protect</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Set access privilege attribute for a region of virtual memory.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_protect</strong>
\r <strong>(vm_task_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>address</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>boolean_t</strong> <var>set_maximum</var>,
\r <strong>vm_prot_t</strong> <var>new_protection</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task whose address space contains
\rthe region.
\r<p>
\r<dt> <var>address</var>
\r<dd>
\r[in scalar]
\rThe starting address for the region.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes in the region.
\r<p>
\r<dt> <var>set_maximum</var>
\r<dd>
\r[in scalar]
\rMaximum/current indicator. If true, the new protection sets
\rthe maximum protection for the region. If false, the new protection sets
\rthe current protection for the region. If the maximum protection is set
\rbelow the current protection, the current protection is also
\r reset to the new
\rmaximum.
\r<p>
\r<dt> <var>new_protection</var>
\r<dd>
\r[in scalar]
\rThe new protection for the region. Valid values are obtained
\rby or'ing together the following values:
\r<dl>
\r<p>
\r<dt> <strong>VM_PROT_READ</strong>
\r<dd>
\rAllows read access.
\r<p>
\r<dt> <strong>VM_PROT_WRITE</strong>
\r<dd>
\rAllows write access.
\r<p>
\r<dt> <strong>VM_PROT_EXECUTE</strong>
\r<dd>
\rAllows execute access.
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_protect</strong> function sets access privileges for
\ra region within the specified
\rtask's address space.
\rThe <var>new_protection</var> parameter specifies a combination
\rof read, write, and
\rexecute accesses that are allowed (rather than prohibited).
\r<p>
\rThe region starts at the beginning of the virtual page containing
\r<var>address</var>; it ends
\rat the end of the virtual page containing <var>address</var> +
\r<var>size</var> - 1. Because of this
\rrounding to virtual page boundaries, the amount of memory protected may be
\rgreater than <var>size</var>. Use <strong>host_page_size</strong>
\rto find the current virtual page size.
\r<p>
\rThe enforcement of virtual memory protection is machine-dependent.
\rNominally read access requires <strong>VM_PROT_READ</strong> permission,
\rwrite access requires
\r<strong>VM_PROT_WRITE</strong> permission, and execute access requires
\r<strong>VM_PROT_EXECUTE</strong> permission. However, some combinations
\rof access rights may not be
\rsupported. In particular, the kernel interface allows write access to require
\r<strong>VM_PROT_READ</strong> and <strong>VM_PROT_WRITE</strong> permission and execute access to
\rrequire <strong>VM_PROT_READ</strong> permission.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the virtual address
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_PROTECTION_FAILURE</strong>
\r<dd>
\rThe new protection increased the current or maximum protection
\rbeyond the existing maximum protection.
\r<p>
\r<dt> <strong>KERN_INVALID_ADDRESS</strong>
\r<dd>
\rThe address is illegal or specifies a non-allocated region.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="host_page_size.html"><strong>host_page_size</strong></a>,
\r<a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
\r<a href="vm_region.html"><strong>vm_region</strong></a>.
\r\ No newline at end of file
+<h2>vm_protect</h2>
+<hr>
+<p>
+<strong>Function</strong> - Set access privilege attribute for a region of virtual memory.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t vm_protect</strong>
+ <strong>(vm_task_t</strong> <var>target_task</var>,
+ <strong>vm_address_t</strong> <var>address</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>boolean_t</strong> <var>set_maximum</var>,
+ <strong>vm_prot_t</strong> <var>new_protection</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The port for the task whose address space contains
+the region.
+<p>
+<dt> <var>address</var>
+<dd>
+[in scalar]
+The starting address for the region.
+<p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The number of bytes in the region.
+<p>
+<dt> <var>set_maximum</var>
+<dd>
+[in scalar]
+Maximum/current indicator. If true, the new protection sets
+the maximum protection for the region. If false, the new protection sets
+the current protection for the region. If the maximum protection is set
+below the current protection, the current protection is also
+ reset to the new
+maximum.
+<p>
+<dt> <var>new_protection</var>
+<dd>
+[in scalar]
+The new protection for the region. Valid values are obtained
+by or'ing together the following values:
+<dl>
+<p>
+<dt> <strong>VM_PROT_READ</strong>
+<dd>
+Allows read access.
+<p>
+<dt> <strong>VM_PROT_WRITE</strong>
+<dd>
+Allows write access.
+<p>
+<dt> <strong>VM_PROT_EXECUTE</strong>
+<dd>
+Allows execute access.
+</dl>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_protect</strong> function sets access privileges for
+a region within the specified
+task's address space.
+The <var>new_protection</var> parameter specifies a combination
+of read, write, and
+execute accesses that are allowed (rather than prohibited).
+<p>
+The region starts at the beginning of the virtual page containing
+<var>address</var>; it ends
+at the end of the virtual page containing <var>address</var> +
+<var>size</var> - 1. Because of this
+rounding to virtual page boundaries, the amount of memory protected may be
+greater than <var>size</var>. Use <strong>host_page_size</strong>
+to find the current virtual page size.
+<p>
+The enforcement of virtual memory protection is machine-dependent.
+Nominally read access requires <strong>VM_PROT_READ</strong> permission,
+write access requires
+<strong>VM_PROT_WRITE</strong> permission, and execute access requires
+<strong>VM_PROT_EXECUTE</strong> permission. However, some combinations
+of access rights may not be
+supported. In particular, the kernel interface allows write access to require
+<strong>VM_PROT_READ</strong> and <strong>VM_PROT_WRITE</strong> permission and execute access to
+require <strong>VM_PROT_READ</strong> permission.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the virtual address
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_PROTECTION_FAILURE</strong>
+<dd>
+The new protection increased the current or maximum protection
+beyond the existing maximum protection.
+<p>
+<dt> <strong>KERN_INVALID_ADDRESS</strong>
+<dd>
+The address is illegal or specifies a non-allocated region.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="host_page_size.html"><strong>host_page_size</strong></a>,
+<a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
+<a href="vm_region.html"><strong>vm_region</strong></a>.
-<h2>vm_read</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Read the specified range of target task's address space.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_read</strong>
\r <strong>(vm_task_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>address</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>size</strong> <var>data_out</var>,
\r <strong>target_task</strong> <var>data_count</var><strong>);</strong>
\r</pre>
\r\r<h4>Overwrite form:</h4>
\r<pre>
\r<strong>kern_return_t vm_read_overwrite</strong>
\r <strong>(vm_task_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>address</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>pointer_t</strong> <var>data_in</var>,
\r <strong>target_task</strong> <var>data_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task whose memory is to be read.
\r<p>
\r<dt> <var>address</var>
\r<dd>
\r[in scalar]
\rThe address at which to start the read.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes to read.
\r<p>
\r<dt> <var>data_out</var>
\r<dd>
\rOut-pointer to dynamic array of bytes returned by the read.
\r<p>
\r<dt> <var>data_in</var>
\r<dd>
\rIn-pointer to array of bytes that will be overwritten with the data returned by the read.
\r<p>
\r<dt> <var>data_count</var>
\r<dd>
\r[in/out scalar]
\rOn input, the maximum size of the buffer; on output, the
\rsize returned (in natural-sized units).
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_read</strong> and <strong>vm_read_overwrite</strong>
\rfunctions read a portion of a task's virtual
\rmemory (they enable tasks to read other tasks' memory).
\rThe <strong>vm_read</strong> function returns the data in a dynamically
\rallocated array of bytes; the <strong>vm_read_overwrite</strong> function
\rplaces the data into a caller-specified buffer (the <var>data_in</var>
\rparameter).
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the virtual address
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_PROTECTION_FAILURE</strong>
\r<dd>
\rSpecified memory is valid, but does not permit reading.
\r<p>
\r<dt> <strong>KERN_INVALID_ADDRESS</strong>
\r<dd>
\rThe address is illegal or specifies a non-allocated region, or there are
\rless than <var>size</var> bytes of data following the address, or the region
\rspecified by the <var>data_in</var> parameter cannot be written to.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_copy.html"><strong>vm_copy</strong></a>,
\r<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>,
\r<a href="vm_write.html"><strong>vm_write</strong></a>.
\r\ No newline at end of file
+<h2>vm_read</h2>
+<hr>
+<p>
+<strong>Function</strong> - Read the specified range of target task's address space.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t vm_read</strong>
+ <strong>(vm_task_t</strong> <var>target_task</var>,
+ <strong>vm_address_t</strong> <var>address</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>size</strong> <var>data_out</var>,
+ <strong>target_task</strong> <var>data_count</var><strong>);</strong>
+</pre>
+
+<h4>Overwrite form:</h4>
+<pre>
+<strong>kern_return_t vm_read_overwrite</strong>
+ <strong>(vm_task_t</strong> <var>target_task</var>,
+ <strong>vm_address_t</strong> <var>address</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>pointer_t</strong> <var>data_in</var>,
+ <strong>target_task</strong> <var>data_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The port for the task whose memory is to be read.
+<p>
+<dt> <var>address</var>
+<dd>
+[in scalar]
+The address at which to start the read.
+<p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The number of bytes to read.
+<p>
+<dt> <var>data_out</var>
+<dd>
+Out-pointer to dynamic array of bytes returned by the read.
+<p>
+<dt> <var>data_in</var>
+<dd>
+In-pointer to array of bytes that will be overwritten with the data returned by the read.
+<p>
+<dt> <var>data_count</var>
+<dd>
+[in/out scalar]
+On input, the maximum size of the buffer; on output, the
+size returned (in natural-sized units).
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_read</strong> and <strong>vm_read_overwrite</strong>
+functions read a portion of a task's virtual
+memory (they enable tasks to read other tasks' memory).
+The <strong>vm_read</strong> function returns the data in a dynamically
+allocated array of bytes; the <strong>vm_read_overwrite</strong> function
+places the data into a caller-specified buffer (the <var>data_in</var>
+parameter).
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the virtual address
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_PROTECTION_FAILURE</strong>
+<dd>
+Specified memory is valid, but does not permit reading.
+<p>
+<dt> <strong>KERN_INVALID_ADDRESS</strong>
+<dd>
+The address is illegal or specifies a non-allocated region, or there are
+less than <var>size</var> bytes of data following the address, or the region
+specified by the <var>data_in</var> parameter cannot be written to.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="vm_copy.html"><strong>vm_copy</strong></a>,
+<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>,
+<a href="vm_write.html"><strong>vm_write</strong></a>.
-<h2>vm_region</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Return description of a virtual memory region.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_region</strong>
\r <strong>(vm_task_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>address</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>vm_region_flavor_t</strong> <var>flavor</var>,
\r <strong>vm_region_info_t</strong> <var>info</var>,
\r <strong>mach_msg_type_number_t</strong> <var>info_count</var>,
\r <strong>memory_object_name_t</strong> <var>object_name</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task whose address space contains
\rthe region.
\r<p>
\r<dt> <var>address</var>
\r<dd>
\r[pointer to in/out scalar]
\rThe address at which to start looking for a
\rregion. The function returns the starting address actually used.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[out scalar]
\rThe number of bytes in the located region. The number
\rconverts to an integral number of virtual pages.
\r<p>
\r<dt> <var>flavor</var>
\r<dd>
\r[in scalar]
\rThe type of information to be returned. Valid values are:
\r<dl>
\r<p>
\r<dt> <strong>VM_REGION_BASIC_INFO</strong>
\r<dd>
\rBasic information about the region (size, inheritance, etc.).
\rThis information is declared by the
\r <strong>vm_region_basic_info</strong> structure.
\r</dl>
\r<p>
\r<dt> <var>info</var>
\r<dd>
\r[out structure]
\rReturned region information.
\r<p>
\r<dt> <var>info_count</var>
\r<dd>
\r[in/out scalar]
\rOn input, the maximum size of the buffer; on output, the
\rsize returned (in natural-sized units).
\r<p>
\r<dt> <var>object_name</var>
\r<dd>
\r This parameter is no longer used.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_region</strong> function returns information on a region
\rwithin the specified
\rtask's address space.
\rThe function begins looking at <var>address</var> and continues until it
\rfinds an allocated
\rregion. If the input address is within a region, the function
\ruses the start of that
\rregion. The starting address for the located region is returned in <var>address</var>.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the virtual address
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ADDRESS</strong>
\r<dd>
\rThere is no region at or beyond the specified starting address.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_allocate.html"><strong>vm_allocate</strong></a>,
\r<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>,
\r<a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
\r<a href="vm_protect.html"><strong>vm_protect</strong></a>,
\r<a href="vm_behavior_set.html"><strong>vm_behavior_set</strong></a>.
\r<p>
\rData Structures:
\r<a href="vm_region_basic_info.html"><strong>vm_region_basic_info</strong></a>.
\r\ No newline at end of file
+<h2>vm_region</h2>
+<hr>
+<p>
+<strong>Function</strong> - Return description of a virtual memory region.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t vm_region</strong>
+ <strong>(vm_task_t</strong> <var>target_task</var>,
+ <strong>vm_address_t</strong> <var>address</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>vm_region_flavor_t</strong> <var>flavor</var>,
+ <strong>vm_region_info_t</strong> <var>info</var>,
+ <strong>mach_msg_type_number_t</strong> <var>info_count</var>,
+ <strong>memory_object_name_t</strong> <var>object_name</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The port for the task whose address space contains
+the region.
+<p>
+<dt> <var>address</var>
+<dd>
+[pointer to in/out scalar]
+The address at which to start looking for a
+region. The function returns the starting address actually used.
+<p>
+<dt> <var>size</var>
+<dd>
+[out scalar]
+The number of bytes in the located region. The number
+converts to an integral number of virtual pages.
+<p>
+<dt> <var>flavor</var>
+<dd>
+[in scalar]
+The type of information to be returned. Valid values are:
+<dl>
+<p>
+<dt> <strong>VM_REGION_BASIC_INFO</strong>
+<dd>
+Basic information about the region (size, inheritance, etc.).
+This information is declared by the
+ <strong>vm_region_basic_info</strong> structure.
+</dl>
+<p>
+<dt> <var>info</var>
+<dd>
+[out structure]
+Returned region information.
+<p>
+<dt> <var>info_count</var>
+<dd>
+[in/out scalar]
+On input, the maximum size of the buffer; on output, the
+size returned (in natural-sized units).
+<p>
+<dt> <var>object_name</var>
+<dd>
+ This parameter is no longer used.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_region</strong> function returns information on a region
+within the specified
+task's address space.
+The function begins looking at <var>address</var> and continues until it
+finds an allocated
+region. If the input address is within a region, the function
+uses the start of that
+region. The starting address for the located region is returned in <var>address</var>.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the virtual address
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ADDRESS</strong>
+<dd>
+There is no region at or beyond the specified starting address.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="vm_allocate.html"><strong>vm_allocate</strong></a>,
+<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>,
+<a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
+<a href="vm_protect.html"><strong>vm_protect</strong></a>,
+<a href="vm_behavior_set.html"><strong>vm_behavior_set</strong></a>.
+<p>
+Data Structures:
+<a href="vm_region_basic_info.html"><strong>vm_region_basic_info</strong></a>.
-<h2>vm_region_basic_info</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Defines the attributes of a task's memory region.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct vm_region_basic_info</strong>
\r<strong>{</strong>
\r <strong>vm_prot_t</strong> <var>protection</var><strong>;</strong>
\r <strong>vm_prot_t</strong> <var>max_protection</var><strong>;</strong>
\r <strong>vm_inherit_t</strong> <var>inheritance</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>shared</var><strong>;</strong>
\r <strong>boolean_t</strong> <var>reserved</var><strong>;</strong>
\r <strong>vm_offset_t</strong> <var>offset</var><strong>;</strong>
\r <strong>vm_behavior_t</strong> <var>behavior</var><strong>;</strong>
\r <strong>unsigned short</strong> <var>user_wired_count</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct vm_region_basic_info* vm_region_basic_info_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>protection</var>
\r<dd>
\rThe current protection for the region.
\r<p>
\r<dt> <var>max_protection</var>
\r<dd>
\rThe maximum protection allowed for the region.
\r<p>
\r<dt> <var>inheritance</var>
\r<dd>
\rThe inheritance attribute for the region.
\r<p>
\r<dt> <var>shared</var>
\r<dd>
\rShared indicator. If true, the region is shared by another task. If false,
\rthe region is not shared.
\r<p>
\r<dt> <var>reserved</var>
\r<dd>
\rIf true the region is protected from random allocation.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\rThe region's offset into the memory object. The region begins at this
\roffset.
\r<p>
\r<dt> <var>behavior</var>
\r<dd>
\rExpected reference pattern for the memory. Valid values are:
\r<dl>
\r<p>
\r<dt> <strong>VM_BEHAVIOR_DEFAULT</strong>
\r<dd>
\rThe system's default behavior.
\r<p>
\r<dt> <strong>VM_BEHAVIOR_RANDOM</strong>
\r<dd>
\rNo particular order expected.
\r<p>
\r<dt> <strong>VM_BEHAVIOR_SEQUENTIAL</strong>
\r<dd>
\rForward sequential order.
\r<p>
\r<dt> <strong>VM_BEHAVIOR_RSEQNTL</strong>
\r<dd>
\rReverse sequential order.
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_region_basic_info</strong> structure defines the attributes
\rof a memory region returned by <strong>vm_region</strong>.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_region.html"><strong>vm_region</strong></a>,
\r<a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
\r<a href="vm_protect.html"><strong>vm_protect</strong></a>.
\r\ No newline at end of file
+<h2>vm_region_basic_info</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Defines the attributes of a task's memory region.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct vm_region_basic_info</strong>
+<strong>{</strong>
+ <strong>vm_prot_t</strong> <var>protection</var><strong>;</strong>
+ <strong>vm_prot_t</strong> <var>max_protection</var><strong>;</strong>
+ <strong>vm_inherit_t</strong> <var>inheritance</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>shared</var><strong>;</strong>
+ <strong>boolean_t</strong> <var>reserved</var><strong>;</strong>
+ <strong>vm_offset_t</strong> <var>offset</var><strong>;</strong>
+ <strong>vm_behavior_t</strong> <var>behavior</var><strong>;</strong>
+ <strong>unsigned short</strong> <var>user_wired_count</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct vm_region_basic_info* vm_region_basic_info_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>protection</var>
+<dd>
+The current protection for the region.
+<p>
+<dt> <var>max_protection</var>
+<dd>
+The maximum protection allowed for the region.
+<p>
+<dt> <var>inheritance</var>
+<dd>
+The inheritance attribute for the region.
+<p>
+<dt> <var>shared</var>
+<dd>
+Shared indicator. If true, the region is shared by another task. If false,
+the region is not shared.
+<p>
+<dt> <var>reserved</var>
+<dd>
+If true the region is protected from random allocation.
+<p>
+<dt> <var>offset</var>
+<dd>
+The region's offset into the memory object. The region begins at this
+offset.
+<p>
+<dt> <var>behavior</var>
+<dd>
+Expected reference pattern for the memory. Valid values are:
+<dl>
+<p>
+<dt> <strong>VM_BEHAVIOR_DEFAULT</strong>
+<dd>
+The system's default behavior.
+<p>
+<dt> <strong>VM_BEHAVIOR_RANDOM</strong>
+<dd>
+No particular order expected.
+<p>
+<dt> <strong>VM_BEHAVIOR_SEQUENTIAL</strong>
+<dd>
+Forward sequential order.
+<p>
+<dt> <strong>VM_BEHAVIOR_RSEQNTL</strong>
+<dd>
+Reverse sequential order.
+</dl>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_region_basic_info</strong> structure defines the attributes
+of a memory region returned by <strong>vm_region</strong>.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="vm_region.html"><strong>vm_region</strong></a>,
+<a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
+<a href="vm_protect.html"><strong>vm_protect</strong></a>.
-<h2>vm_remap</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Map memory objects in one task's address space to that of another task's.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_remap</strong>
\r <strong>(mach_port_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>target_address</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>vm_address_t</strong> <var>mask</var>,
\r <strong>boolean_t</strong> <var>anywhere</var>,
\r <strong>mach_port_t</strong> <var>source_task</var>,
\r <strong>vm_address_t</strong> <var>source_address</var>,
\r <strong>boolean_t</strong> <var>copy</var>,
\r <strong>vm_prot_t</strong> <var>cur_protection</var>,
\r <strong>vm_prot_t</strong> <var>max_protection</var>,
\r <strong>vm_inherit_t</strong> <var>inheritance</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task in whose address space the
\rmemory is to be mapped.
\r <p>
\r<dt> <var>target_address</var>
\r<dd>
\r[pointer to in/out scalar]
\rThe starting address for the mapped memory
\rin the target task. The mapped memory will start at the beginning of
\rthe page containing <var>target_address</var>. If there is not enough room
\rfollowing the address, the kernel does not map the memory. The kernel
\rreturns the starting address actually used for the mapped memory.
\r <p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes to map. The kernel rounds this number
\rup to an integral number of virtual pages.
\r<p>
\r<dt> <var>mask</var>
\r<dd>
\r[in scalar]
\rAlignment restrictions for starting address. Bits turned on in
\rthe mask will not be turned on in the starting address.
\r<p>
\r<dt> <var>anywhere</var>
\r<dd>
\r[in scalar]
\rPlacement indicator.
\r The valid values are:
\r<dl>
\r<p>
\r <dt> <strong>TRUE</strong>
\r<dd>
\rThe kernel allocates the region in the next unused space that
\ris sufficient within the address space. The kernel returns the
\rstarting address actually used in <var>address</var>.
\r<p>
\r<dt> <strong>FALSE</strong>
\r<dd>
\rThe kernel allocates the region starting at <var>address</var> unless that
\rspace is already allocated.
\r</dl>
\r<p>
\r<dt> <var>source_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task whose address space is to be
\rmapped.
\r<p>
\r<dt> <var>source_address</var>
\r<dd>
\r[in scalar]
\rThe starting address for the memory to be mapped from the
\rsource task. The memory to be mapped will start at the beginning of
\rthe page containing <var>source_address</var>. If not enough memory exists
\rfollowing the address, the kernel does not map the memory.
\r<p>
\r<dt> <var>copy</var>
\r<dd>
\r[in scalar]
\rCopy indicator. If true, the kernel copies the region for the
\rmemory to the specified task's address space. If false, the region is
\rmapped read-write.
\r<p>
\r<dt> <var>cur_protection</var>
\r<dd>
\r[out scalar]
\rThe most restrictive current protection for the memory in
\rthe region. Valid values are obtained by or'ing together the following
\rvalues:
\r<dl>
\r<p>
\r <dt> <strong>VM_PROT_READ</strong>
\r<dd>
\rAllows read access.
\r<p>
\r<dt> <strong>VM_PROT_WRITE</strong>
\r<dd>
\rAllows write access.
\r<p>
\r<dt> <strong>VM_PROT_EXECUTE</strong>
\r<dd>
\rAllows execute access.
\r</dl>
\r<p>
\r<dt> <var>max_protection</var>
\r<dd>
\r[out scalar]
\rThe most restrictive maximum protection for the memory
\rin the region. Values are the same as for <var>cur_protection</var>.
\r<p>
\r<dt> <var>inheritance</var>
\r<dd>
\r[in scalar]
\rThe initial inheritance attribute for the region. Valid values
\rare:
\r<dl>
\r<p>
\r <dt> <strong>VM_INHERIT_SHARE</strong>
\r<dd>
\rAllows child tasks to share the region.
\r<p>
\r<dt> <strong>VM_INHERIT_COPY</strong>
\r<dd>
\rGives child tasks a copy of the region.
\r<p>
\r<dt> <strong>VM_INHERIT_NONE</strong>
\r<dd>
\rProvides no access to the region for child tasks.
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_remap</strong> function maps the memory objects underlying
\ra portion of the
\rspecified <var>source_task</var>'s virtual address space into the address
\rspace belonging to
\r<var>target_task</var>. The target task can be the calling task or another
\rtask, identified by
\rits task kernel port. The effect is as if the target task performed
\ra <strong>vm_map</strong> call
\rgiven the same memory object, maximum protection, current
\rprotection, and inheritance as the source task.
\rHowever, the two
\rtasks must reside on the same host. The kernel maps the memory objects
\rstarting at <var>target_address</var>, so that access to <var>target_address</var>
\ris as if the source task
\raccessed its <var>source_address</var>.
\r<p>
\rThe <var>mask</var> parameter
\rspecifies additional alignment restrictions on the kernel's
\rselection of the starting address. Uses for this mask include:
\r<ul>
\r<li>
\rForcing the memory address alignment for a mapping to be the same as the
\ralignment within the source task.
\r<li>
\rQuickly finding the beginning of an allocated region by performing bit
\rarithmetic on an address known to be in the region.
\r<li>
\rEmulating a larger virtual page size.
\r</ul>
\rThe <var>cur_protection</var> and <var>max_protection</var> parameters return the protection
\rattributes for the mapped memory. If all memory within the range had the same
\rattributes, these attributes are returned; otherwise the call returns the most
\rrestrictive values for any memory in the region.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the virtual address
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r <dt> <strong>KERN_NO_SPACE</strong>
\r<dd>
\rThere is not enough space in the task's address space to allocate the
\rnew region for the memory object.
\r<p>
\r<dt> <strong>KERN_PROTECTION_FAILURE</strong>
\r<dd>
\rSpecified memory is valid, but the backing memory manager is
\rnot permitted by the requesting task.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_map.html"><strong>vm_map</strong></a>,
\r<a href="vm_read.html"><strong>vm_read</strong></a>,
\r<a href="vm_write.html"><strong>vm_write</strong></a>.
\r\ No newline at end of file
+<h2>vm_remap</h2>
+<hr>
+<p>
+<strong>Function</strong> - Map memory objects in one task's address space to that of another task's.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t vm_remap</strong>
+ <strong>(mach_port_t</strong> <var>target_task</var>,
+ <strong>vm_address_t</strong> <var>target_address</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>vm_address_t</strong> <var>mask</var>,
+ <strong>boolean_t</strong> <var>anywhere</var>,
+ <strong>mach_port_t</strong> <var>source_task</var>,
+ <strong>vm_address_t</strong> <var>source_address</var>,
+ <strong>boolean_t</strong> <var>copy</var>,
+ <strong>vm_prot_t</strong> <var>cur_protection</var>,
+ <strong>vm_prot_t</strong> <var>max_protection</var>,
+ <strong>vm_inherit_t</strong> <var>inheritance</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The port for the task in whose address space the
+memory is to be mapped.
+ <p>
+<dt> <var>target_address</var>
+<dd>
+[pointer to in/out scalar]
+The starting address for the mapped memory
+in the target task. The mapped memory will start at the beginning of
+the page containing <var>target_address</var>. If there is not enough room
+following the address, the kernel does not map the memory. The kernel
+returns the starting address actually used for the mapped memory.
+ <p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The number of bytes to map. The kernel rounds this number
+up to an integral number of virtual pages.
+<p>
+<dt> <var>mask</var>
+<dd>
+[in scalar]
+Alignment restrictions for starting address. Bits turned on in
+the mask will not be turned on in the starting address.
+<p>
+<dt> <var>anywhere</var>
+<dd>
+[in scalar]
+Placement indicator.
+ The valid values are:
+<dl>
+<p>
+ <dt> <strong>TRUE</strong>
+<dd>
+The kernel allocates the region in the next unused space that
+is sufficient within the address space. The kernel returns the
+starting address actually used in <var>address</var>.
+<p>
+<dt> <strong>FALSE</strong>
+<dd>
+The kernel allocates the region starting at <var>address</var> unless that
+space is already allocated.
+</dl>
+<p>
+<dt> <var>source_task</var>
+<dd>
+[in task send right]
+The port for the task whose address space is to be
+mapped.
+<p>
+<dt> <var>source_address</var>
+<dd>
+[in scalar]
+The starting address for the memory to be mapped from the
+source task. The memory to be mapped will start at the beginning of
+the page containing <var>source_address</var>. If not enough memory exists
+following the address, the kernel does not map the memory.
+<p>
+<dt> <var>copy</var>
+<dd>
+[in scalar]
+Copy indicator. If true, the kernel copies the region for the
+memory to the specified task's address space. If false, the region is
+mapped read-write.
+<p>
+<dt> <var>cur_protection</var>
+<dd>
+[out scalar]
+The most restrictive current protection for the memory in
+the region. Valid values are obtained by or'ing together the following
+values:
+<dl>
+<p>
+ <dt> <strong>VM_PROT_READ</strong>
+<dd>
+Allows read access.
+<p>
+<dt> <strong>VM_PROT_WRITE</strong>
+<dd>
+Allows write access.
+<p>
+<dt> <strong>VM_PROT_EXECUTE</strong>
+<dd>
+Allows execute access.
+</dl>
+<p>
+<dt> <var>max_protection</var>
+<dd>
+[out scalar]
+The most restrictive maximum protection for the memory
+in the region. Values are the same as for <var>cur_protection</var>.
+<p>
+<dt> <var>inheritance</var>
+<dd>
+[in scalar]
+The initial inheritance attribute for the region. Valid values
+are:
+<dl>
+<p>
+ <dt> <strong>VM_INHERIT_SHARE</strong>
+<dd>
+Allows child tasks to share the region.
+<p>
+<dt> <strong>VM_INHERIT_COPY</strong>
+<dd>
+Gives child tasks a copy of the region.
+<p>
+<dt> <strong>VM_INHERIT_NONE</strong>
+<dd>
+Provides no access to the region for child tasks.
+</dl>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_remap</strong> function maps the memory objects underlying
+a portion of the
+specified <var>source_task</var>'s virtual address space into the address
+space belonging to
+<var>target_task</var>. The target task can be the calling task or another
+task, identified by
+its task kernel port. The effect is as if the target task performed
+a <strong>vm_map</strong> call
+given the same memory object, maximum protection, current
+protection, and inheritance as the source task.
+However, the two
+tasks must reside on the same host. The kernel maps the memory objects
+starting at <var>target_address</var>, so that access to <var>target_address</var>
+is as if the source task
+accessed its <var>source_address</var>.
+<p>
+The <var>mask</var> parameter
+specifies additional alignment restrictions on the kernel's
+selection of the starting address. Uses for this mask include:
+<ul>
+<li>
+Forcing the memory address alignment for a mapping to be the same as the
+alignment within the source task.
+<li>
+Quickly finding the beginning of an allocated region by performing bit
+arithmetic on an address known to be in the region.
+<li>
+Emulating a larger virtual page size.
+</ul>
+The <var>cur_protection</var> and <var>max_protection</var> parameters return the protection
+attributes for the mapped memory. If all memory within the range had the same
+attributes, these attributes are returned; otherwise the call returns the most
+restrictive values for any memory in the region.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the virtual address
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+ <dt> <strong>KERN_NO_SPACE</strong>
+<dd>
+There is not enough space in the task's address space to allocate the
+new region for the memory object.
+<p>
+<dt> <strong>KERN_PROTECTION_FAILURE</strong>
+<dd>
+Specified memory is valid, but the backing memory manager is
+not permitted by the requesting task.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="vm_map.html"><strong>vm_map</strong></a>,
+<a href="vm_read.html"><strong>vm_read</strong></a>,
+<a href="vm_write.html"><strong>vm_write</strong></a>.
-<h2>vm_statistics</h2>
\r<hr>
\r<p>
\r<strong>Structure</strong> - Defines statistics for the kernel's use of virtual memory.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>struct vm_statistics</strong>
\r<strong>{</strong>
\r <strong>integer_t</strong> <var>free_count</var><strong>;</strong>
\r <strong>integer_t</strong> <var>active_count</var><strong>;</strong>
\r <strong>integer_t</strong> <var>inactive_count</var><strong>;</strong>
\r <strong>integer_t</strong> <var>wire_count</var><strong>;</strong>
\r <strong>integer_t</strong> <var>zero_fill_count</var><strong>;</strong>
\r <strong>integer_t</strong> <var>reactivations</var><strong>;</strong>
\r <strong>integer_t</strong> <var>pageins</var><strong>;</strong>
\r <strong>integer_t</strong> <var>pageouts</var><strong>;</strong>
\r <strong>integer_t</strong> <var>faults</var><strong>;</strong>
\r <strong>integer_t</strong> <var>cow_faults</var><strong>;</strong>
\r <strong>integer_t</strong> <var>lookups</var><strong>;</strong>
\r <strong>integer_t</strong> <var>hits</var><strong>;</strong>
\r<strong>};</strong>
\r\r<strong>typedef struct vm_statistics* vm_statistics_t;</strong>
\r</pre>
\r<h3>FIELDS</h3>
\r<dl>
\r<dt> <var>free_count</var>
\r<dd>
\rThe total number of free pages in the system.
\r<p>
\r<dt> <var>active_count</var>
\r<dd>
\rThe total number of pages currently in use and pageable.
\r<p>
\r<dt> <var>inactive_count</var>
\r<dd>
\rThe number of inactive pages.
\r<p>
\r<dt> <var>wire_count</var>
\r<dd>
\rThe number of pages that are wired in memory and cannot be paged
\rout.
\r<p>
\r<dt> <var>zero_fill_count</var>
\r<dd>
\rThe number of zero-fill pages.
\r<p>
\r<dt> <var>reactivations</var>
\r<dd>
\rThe number of reactivated pages.
\r<p>
\r<dt> <var>pageins</var>
\r<dd>
\rThe number of requests for pages from a pager (such as the i-node
\rpager).
\r<p>
\r<dt> <var>pageouts</var>
\r<dd>
\rThe number of pages that have been paged out.
\r<p>
\r<dt> <var>faults</var>
\r<dd>
\rThe number of times the <strong>vm_fault</strong> routine has been called.
\r<p>
\r<dt> <var>cow_faults</var>
\r<dd>
\rThe number of copy-on-write faults.
\r<p>
\r<dt> <var>lookups</var>
\r<dd>
\rThe number of object cache lookups.
\r<p>
\r<dt> <var>hits</var>
\r<dd>
\rThe number of object cache hits.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_statistics</strong> structure defines the statistics
\ravailable on the kernel's use of
\rvirtual memory. The statistics record virtual memory usage since
\rthe kernel was booted.
\r<p>
\rFor related information for a specific task, see the <strong>task_basic_info</strong>
\rstructure.
\r<h3>NOTES</h3>
\r<p>
\rThis structure is machine word length specific because of the memory sizes
\rreturned.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="task_info.html"><strong>task_info</strong></a>,
\r<a href="host_page_size.html"><strong>host_page_size</strong></a>.
\r<p>
\rData Structures:
\r<a href="task_basic_info.html"><strong>task_basic_info</strong></a>.
\r\r\ No newline at end of file
+<h2>vm_statistics</h2>
+<hr>
+<p>
+<strong>Structure</strong> - Defines statistics for the kernel's use of virtual memory.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>struct vm_statistics</strong>
+<strong>{</strong>
+ <strong>integer_t</strong> <var>free_count</var><strong>;</strong>
+ <strong>integer_t</strong> <var>active_count</var><strong>;</strong>
+ <strong>integer_t</strong> <var>inactive_count</var><strong>;</strong>
+ <strong>integer_t</strong> <var>wire_count</var><strong>;</strong>
+ <strong>integer_t</strong> <var>zero_fill_count</var><strong>;</strong>
+ <strong>integer_t</strong> <var>reactivations</var><strong>;</strong>
+ <strong>integer_t</strong> <var>pageins</var><strong>;</strong>
+ <strong>integer_t</strong> <var>pageouts</var><strong>;</strong>
+ <strong>integer_t</strong> <var>faults</var><strong>;</strong>
+ <strong>integer_t</strong> <var>cow_faults</var><strong>;</strong>
+ <strong>integer_t</strong> <var>lookups</var><strong>;</strong>
+ <strong>integer_t</strong> <var>hits</var><strong>;</strong>
+<strong>};</strong>
+
+<strong>typedef struct vm_statistics* vm_statistics_t;</strong>
+</pre>
+<h3>FIELDS</h3>
+<dl>
+<dt> <var>free_count</var>
+<dd>
+The total number of free pages in the system.
+<p>
+<dt> <var>active_count</var>
+<dd>
+The total number of pages currently in use and pageable.
+<p>
+<dt> <var>inactive_count</var>
+<dd>
+The number of inactive pages.
+<p>
+<dt> <var>wire_count</var>
+<dd>
+The number of pages that are wired in memory and cannot be paged
+out.
+<p>
+<dt> <var>zero_fill_count</var>
+<dd>
+The number of zero-fill pages.
+<p>
+<dt> <var>reactivations</var>
+<dd>
+The number of reactivated pages.
+<p>
+<dt> <var>pageins</var>
+<dd>
+The number of requests for pages from a pager (such as the i-node
+pager).
+<p>
+<dt> <var>pageouts</var>
+<dd>
+The number of pages that have been paged out.
+<p>
+<dt> <var>faults</var>
+<dd>
+The number of times the <strong>vm_fault</strong> routine has been called.
+<p>
+<dt> <var>cow_faults</var>
+<dd>
+The number of copy-on-write faults.
+<p>
+<dt> <var>lookups</var>
+<dd>
+The number of object cache lookups.
+<p>
+<dt> <var>hits</var>
+<dd>
+The number of object cache hits.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_statistics</strong> structure defines the statistics
+available on the kernel's use of
+virtual memory. The statistics record virtual memory usage since
+the kernel was booted.
+<p>
+For related information for a specific task, see the <strong>task_basic_info</strong>
+structure.
+<h3>NOTES</h3>
+<p>
+This structure is machine word length specific because of the memory sizes
+returned.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="task_info.html"><strong>task_info</strong></a>,
+<a href="host_page_size.html"><strong>host_page_size</strong></a>.
+<p>
+Data Structures:
+<a href="task_basic_info.html"><strong>task_basic_info</strong></a>.
+
-<h2>vm_wire</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Modify the target region's paging characteristics.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_wire</strong>
\r <strong>(host_priv_t</strong> <var>host</var>,
\r <strong>vm_task_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>address</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>vm_prot_t</strong> <var>wired_access</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>host</var>
\r<dd>
\r[in host-control send right]
\rThe control port for the host for which
\rinformation is to be obtained.
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task whose address space contains
\rthe region.
\r<p>
\r<dt> <var>address</var>
\r<dd>
\r[in scalar]
\rThe starting address for the region.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes in the region.
\r<p>
\r<dt> <var>wired_access</var>
\r<dd>
\r[in scalar]
\rThe pageability of the region. The following values cause
\rthe region to be wired and protected as specified
\r(values may be combined):
\r<dl>
\r<dt> <strong>VM_PROT_READ</strong>
\r<dt> <strong>VM_PROT_WRITE</strong>
\r<dt> <strong>VM_PROT_execute</strong>
\r</dl>
\r<p>
\rThe following value causes the region to be unwired (made pageable):
\r<dl>
\r<dt> <strong>VM_PROT_NONE</strong>
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_wire</strong> function sets the pageability privileges
\rfor a region within the
\rspecified task's address space. <var>wired_access</var> specifies the types
\rof accesses to
\rthe memory region which must not suffer from (internal) faults
\rof any kind after
\rthis call returns. A non-null <var>wired_access</var> value indicates that
\rthe page is to be
\r"wired" into memory; a null value indicates "un-wiring". The kernel maintains
\rfor the region a count of the number of times the region is wired. A page is
\rwired into physical memory if any task accessing it has a non-zero wired count
\rfor the page.
\r<p>
\rThe region starts at the beginning of the virtual page containing
\r<var>address</var>; it ends at the end of the virtual page containing
\r<var>address</var> + <var>size</var> - 1. Because of this
\rrounding to virtual page boundaries, the amount of memory affected may be
\rgreater than <var>size</var>. Use <strong>host_page_size</strong> to find the current
\rvirtual page size.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the virtual address
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_INVALID_ADDRESS</strong>
\r<dd>
\rThe address is illegal or specifies a non-allocated region.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="thread_wire.html"><strong>thread_wire</strong></a>.
\r\ No newline at end of file
+<h2>vm_wire</h2>
+<hr>
+<p>
+<strong>Function</strong> - Modify the target region's paging characteristics.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t vm_wire</strong>
+ <strong>(host_priv_t</strong> <var>host</var>,
+ <strong>vm_task_t</strong> <var>target_task</var>,
+ <strong>vm_address_t</strong> <var>address</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>vm_prot_t</strong> <var>wired_access</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>host</var>
+<dd>
+[in host-control send right]
+The control port for the host for which
+information is to be obtained.
+<p>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The port for the task whose address space contains
+the region.
+<p>
+<dt> <var>address</var>
+<dd>
+[in scalar]
+The starting address for the region.
+<p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The number of bytes in the region.
+<p>
+<dt> <var>wired_access</var>
+<dd>
+[in scalar]
+The pageability of the region. The following values cause
+the region to be wired and protected as specified
+(values may be combined):
+<dl>
+<dt> <strong>VM_PROT_READ</strong>
+<dt> <strong>VM_PROT_WRITE</strong>
+<dt> <strong>VM_PROT_execute</strong>
+</dl>
+<p>
+The following value causes the region to be unwired (made pageable):
+<dl>
+<dt> <strong>VM_PROT_NONE</strong>
+</dl>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_wire</strong> function sets the pageability privileges
+for a region within the
+specified task's address space. <var>wired_access</var> specifies the types
+of accesses to
+the memory region which must not suffer from (internal) faults
+of any kind after
+this call returns. A non-null <var>wired_access</var> value indicates that
+the page is to be
+"wired" into memory; a null value indicates "un-wiring". The kernel maintains
+for the region a count of the number of times the region is wired. A page is
+wired into physical memory if any task accessing it has a non-zero wired count
+for the page.
+<p>
+The region starts at the beginning of the virtual page containing
+<var>address</var>; it ends at the end of the virtual page containing
+<var>address</var> + <var>size</var> - 1. Because of this
+rounding to virtual page boundaries, the amount of memory affected may be
+greater than <var>size</var>. Use <strong>host_page_size</strong> to find the current
+virtual page size.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the virtual address
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_INVALID_ADDRESS</strong>
+<dd>
+The address is illegal or specifies a non-allocated region.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="thread_wire.html"><strong>thread_wire</strong></a>.
-<h2>vm_write</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Write data to the specified address in the target task's address space.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_write</strong>
\r <strong>(vm_task_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>address</var>,
\r <strong>pointer_t</strong> <var>data</var>,
\r <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task whose memory is to be
\rwritten.
\r<p>
\r<dt> <var>address</var>
\r<dd>
\r[in scalar]
\rThe address at which to start the write.
\r<p>
\r<dt> <var>data</var>
\r<dd>
\r[pointer to page aligned in array of bytes]
\rAn array of data to be
\rwritten.
\r<p>
\r<dt> <var>data_count</var>
\r<dd>
\r[in scalar]
\rThe number of bytes in the array.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_write</strong> function writes an array of data to a
\rtask's virtual memory. It
\rallows one task to write to another task's memory.
\r<p>
\rThe result of <strong>vm_write</strong> is as if <var>target_task</var> had directly
\rwritten into the set of
\rpages. Hence, <var>target_task</var> must have write permission to the pages.
\r<h3>NOTES</h3>
\r<p>
\rThis interface is machine word length specific because of the virtual address
\rparameter.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_PROTECTION_FAILURE</strong>
\r<dd>
\rSpecified memory is valid, but does not permit writing.
\r<p>
\r<dt> <strong>KERN_INVALID_ADDRESS</strong>
\r<dd>
\rThe address is illegal or specifies a non-allocated region.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_copy.html"><strong>vm_copy</strong></a>,
\r<a href="vm_protect.html"><strong>vm_protect</strong></a>,
\r<a href="vm_read.html"><strong>vm_read</strong></a>,
\r<a href="host_page_size.html"><strong>host_page_size</strong></a>.
\r\ No newline at end of file
+<h2>vm_write</h2>
+<hr>
+<p>
+<strong>Function</strong> - Write data to the specified address in the target task's address space.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t vm_write</strong>
+ <strong>(vm_task_t</strong> <var>target_task</var>,
+ <strong>vm_address_t</strong> <var>address</var>,
+ <strong>pointer_t</strong> <var>data</var>,
+ <strong>mach_msg_type_number_t</strong> <var>data_count</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The port for the task whose memory is to be
+written.
+<p>
+<dt> <var>address</var>
+<dd>
+[in scalar]
+The address at which to start the write.
+<p>
+<dt> <var>data</var>
+<dd>
+[pointer to page aligned in array of bytes]
+An array of data to be
+written.
+<p>
+<dt> <var>data_count</var>
+<dd>
+[in scalar]
+The number of bytes in the array.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_write</strong> function writes an array of data to a
+task's virtual memory. It
+allows one task to write to another task's memory.
+<p>
+The result of <strong>vm_write</strong> is as if <var>target_task</var> had directly
+written into the set of
+pages. Hence, <var>target_task</var> must have write permission to the pages.
+<h3>NOTES</h3>
+<p>
+This interface is machine word length specific because of the virtual address
+parameter.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_PROTECTION_FAILURE</strong>
+<dd>
+Specified memory is valid, but does not permit writing.
+<p>
+<dt> <strong>KERN_INVALID_ADDRESS</strong>
+<dd>
+The address is illegal or specifies a non-allocated region.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="vm_copy.html"><strong>vm_copy</strong></a>,
+<a href="vm_protect.html"><strong>vm_protect</strong></a>,
+<a href="vm_read.html"><strong>vm_read</strong></a>,
+<a href="host_page_size.html"><strong>host_page_size</strong></a>.
li r11,RESET_HANDLER_IGNORE ; Get set to ignore
stw r11,lo16(EXT(ResetHandler)-EXT(ExceptionVectorsStart)+RESETHANDLER_TYPE)(br0) ; Start ignoring these
mfsprg r13,1 /* Get the exception save area */
- li r11,T_RESET /* Set 'rupt code */
+ li r11,T_RESET /* Set interrupt code */
b .L_exception_entry /* Join common... */
/*
.L_handler300:
mtsprg 2,r13 /* Save R13 */
mtsprg 3,r11 /* Save R11 */
- li r11,T_DATA_ACCESS /* Set 'rupt code */
+ li r11,T_DATA_ACCESS /* Set interrupt code */
b .L_exception_entry /* Join common... */
.L_handler600:
mtsprg 2,r13 /* Save R13 */
mtsprg 3,r11 /* Save R11 */
- li r11,T_ALIGNMENT|T_FAM /* Set 'rupt code */
+ li r11,T_ALIGNMENT|T_FAM /* Set interrupt code */
b .L_exception_entry /* Join common... */
/*
mtcrf 255,r11 ; (BRINGUP)
#endif
- li r11,T_PROGRAM|T_FAM /* Set 'rupt code */
+ li r11,T_PROGRAM|T_FAM /* Set interrupt code */
b .L_exception_entry /* Join common... */
/*
.L_handler800:
mtsprg 2,r13 /* Save R13 */
mtsprg 3,r11 /* Save R11 */
- li r11,T_FP_UNAVAILABLE /* Set 'rupt code */
+ li r11,T_FP_UNAVAILABLE /* Set interrupt code */
b .L_exception_entry /* Join common... */
.L_handler900:
mtsprg 2,r13 /* Save R13 */
mtsprg 3,r11 /* Save R11 */
- li r11,T_DECREMENTER /* Set 'rupt code */
+ li r11,T_DECREMENTER /* Set interrupt code */
b .L_exception_entry /* Join common... */
/*
.L_handlerA00:
mtsprg 2,r13 /* Save R13 */
mtsprg 3,r11 /* Save R11 */
- li r11,T_IO_ERROR /* Set 'rupt code */
+ li r11,T_IO_ERROR /* Set interrupt code */
b .L_exception_entry /* Join common... */
/*
.L_handlerB00:
mtsprg 2,r13 /* Save R13 */
mtsprg 3,r11 /* Save R11 */
- li r11,T_RESERVED /* Set 'rupt code */
+ li r11,T_RESERVED /* Set interrupt code */
b .L_exception_entry /* Join common... */
rlwinm r11,r11,0,0,30 ; clear out bit 31
rlwimi r11,r13,1,0x40 ; move 0x6004 bit into position
lhz r11,lo16(scTable)(r11) ; get branch address from sc table
- mfctr r13 ; save caller's ctr in r13
+ mfctr r13 ; save callers ctr in r13
mtctr r11 ; set up branch to syscall handler
mfsprg r11,0 ; get per_proc, which most UFTs use
bctr ; dispatch (r11 in sprg3, r13 in sprg2, ctr in r13, per_proc in r11)
.L_handlerE00:
mtsprg 2,r13 /* Save R13 */
mtsprg 3,r11 /* Save R11 */
- li r11,T_FP_ASSIST /* Set 'rupt code */
+ li r11,T_FP_ASSIST /* Set interrupt code */
b .L_exception_entry /* Join common... */
PMIhandler:
mtsprg 2,r13 /* Save R13 */
mtsprg 3,r11 /* Save R11 */
- li r11,T_PERF_MON /* Set 'rupt code */
+ li r11,T_PERF_MON /* Set interrupt code */
b .L_exception_entry /* Join common... */
VMXhandler:
mtsprg 2,r13 /* Save R13 */
mtsprg 3,r11 /* Save R11 */
- li r11,T_VMX /* Set 'rupt code */
+ li r11,T_VMX /* Set interrupt code */
b .L_exception_entry /* Join common... */
.L_handler1300:
mtsprg 2,r13 /* Save R13 */
mtsprg 3,r11 /* Save R11 */
- li r11,T_INSTRUCTION_BKPT /* Set 'rupt code */
+ li r11,T_INSTRUCTION_BKPT /* Set interrupt code */
b .L_exception_entry /* Join common... */
/*
.L_handler1400:
mtsprg 2,r13 /* Save R13 */
mtsprg 3,r11 /* Save R11 */
- li r11,T_SYSTEM_MANAGEMENT /* Set 'rupt code */
+ li r11,T_SYSTEM_MANAGEMENT /* Set interrupt code */
b .L_exception_entry /* Join common... */
.L_handler1500:
mtsprg 2,r13 /* Save R13 */
mtsprg 3,r11 /* Save R11 */
- li r11,T_SOFT_PATCH /* Set 'rupt code */
+ li r11,T_SOFT_PATCH /* Set interrupt code */
b .L_exception_entry /* Join common... */
;
.L_handler1600:
mtsprg 2,r13 /* Save R13 */
mtsprg 3,r11 /* Save R11 */
- li r11,T_ALTIVEC_ASSIST /* Set 'rupt code */
+ li r11,T_ALTIVEC_ASSIST /* Set interrupt code */
b .L_exception_entry /* Join common... */
;
.L_handler1700:
mtsprg 2,r13 /* Save R13 */
mtsprg 3,r11 /* Save R11 */
- li r11,T_THERMAL /* Set 'rupt code */
+ li r11,T_THERMAL /* Set interrupt code */
b .L_exception_entry /* Join common... */
;
.L_handler1800:
mtsprg 2,r13 /* Save R13 */
mtsprg 3,r11 /* Save R11 */
- li r11,T_ARCHDEP0 /* Set 'rupt code */
+ li r11,T_ARCHDEP0 /* Set interrupt code */
b .L_exception_entry /* Join common... */
/*
.L_handler2000:
mtsprg 2,r13 /* Save R13 */
mtsprg 3,r11 /* Save R11 */
- li r11,T_INSTRUMENTATION /* Set 'rupt code */
+ li r11,T_INSTRUMENTATION /* Set interrupt code */
b .L_exception_entry /* Join common... */
* except the following:
*
* r11 = per_proc ptr (ie, sprg0)
- * r13 = holds caller's ctr register
- * sprg2 = holds caller's r13
- * sprg3 = holds caller's r11
+ * r13 = holds callers ctr register
+ * sprg2 = holds callers r13
+ * sprg3 = holds callers r11
*/
; Handle "vmm_dispatch" (0x6004), of which only some selectors are UFTs.
uftVMM:
- mtctr r13 ; restore caller's ctr
+ mtctr r13 ; restore callers ctr
lwz r11,spcFlags(r11) ; get the special flags word from per_proc
- mfcr r13 ; save caller's entire cr (we use all fields below)
+ mfcr r13 ; save callers entire cr (we use all fields below)
rlwinm r11,r11,16,16,31 ; Extract spcFlags upper bits
andi. r11,r11,hi16(runningVM|FamVMena|FamVMmode)
cmpwi cr0,r11,hi16(runningVM|FamVMena|FamVMmode) ; Test in VM FAM
uftIsPreemptiveTask:
uftIsPreemptiveTaskEnv:
- mtctr r13 ; restore caller's ctr
+ mtctr r13 ; restore callers ctr
lwz r11,spcFlags(r11) ; get the special flags word from per_proc
- mfcr r13,0x80 ; save caller's cr0 so we can use it
+ mfcr r13,0x80 ; save callers cr0 so we can use it
andi. r11,r11,bbNoMachSC|bbPreemptive ; Clear what we do not need
cmplwi r11,bbNoMachSC ; See if we are trapping syscalls
blt-- uftNormal80 ; No...
lwz r3,UAW+4(r11) ; get user assist word, assuming a 32-bit processor
LEXT(uft_uaw_nop_if_32bit)
ld r3,UAW(r11) ; get the whole doubleword if 64-bit (patched to nop if 32-bit)
- mtctr r13 ; restore caller's ctr
+ mtctr r13 ; restore callers ctr
b uftRFI ; done
uftFacilityStatus:
lwz r3,spcFlags(r11) ; get "special flags" word from per_proc
- mtctr r13 ; restore caller's ctr
+ mtctr r13 ; restore callers ctr
b uftRFI ; done
; Handle "Load MSR" UFT (0x7FF4). This is not used on 64-bit processors, though it would work.
uftLoadMSR:
- mfsrr1 r11 ; get caller's MSR
- mtctr r13 ; restore caller's ctr
- mfcr r13,0x80 ; save caller's cr0 so we can test PR
+ mfsrr1 r11 ; get callers MSR
+ mtctr r13 ; restore callers ctr
+ mfcr r13,0x80 ; save callers cr0 so we can test PR
rlwinm. r11,r11,0,MSR_PR_BIT,MSR_PR_BIT ; really in the kernel?
bne- uftNormal80 ; do not permit from user mode
mfsprg r11,0 ; restore per_proc
; sprg3 = callers r11
uftRestoreThenRFI: ; WARNING: can drop down to here
- mtcrf 0x80,r13 ; restore caller's cr0
+ mtcrf 0x80,r13 ; restore callers cr0
uftRFI:
.globl EXT(uft_nop_if_32bit)
LEXT(uft_nop_if_32bit)
lhz r24,PP_CPU_NUMBER(r11) ; Get the logical processor number
li r23,T_SYSTEM_CALL ; Get the system call id
- mtctr r13 ; Restore the caller's CTR
+ mtctr r13 ; Restore the callers CTR
sth r24,LTR_cpu(r20) ; Save processor number
li r24,64 ; Offset to third line
sth r23,LTR_excpt(r20) ; Set the exception code
lwz r20,tempr0(r11) ; Restore work register
lwz r21,tempr1(r11) ; Restore work register
lwz r25,tempr2(r11) ; Restore work register
- mtctr r13 ; Restore the caller's CTR
+ mtctr r13 ; Restore the callers CTR
lwz r22,tempr3(r11) ; Restore work register
lwz r23,tempr4(r11) ; Restore work register
lwz r24,tempr5(r11) ; Restore work register
lwz r20,tempr0(r11) ; Restore work register
lwz r21,tempr1(r11) ; Restore work register
lwz r25,tempr2(r11) ; Restore work register
- mtctr r13 ; Restore the caller's CTR
+ mtctr r13 ; Restore the callers CTR
lwz r22,tempr3(r11) ; Restore work register
lwz r23,tempr4(r11) ; Restore work register
b uftNormalSyscall ; Go pass it on along...
ld r20,tempr0(r11) ; Restore work register
ld r21,tempr1(r11) ; Restore work register
ld r25,tempr2(r11) ; Restore work register
- mtctr r13 ; Restore the caller's CTR
+ mtctr r13 ; Restore the callers CTR
ld r22,tempr3(r11) ; Restore work register
ld r23,tempr4(r11) ; Restore work register
ld r24,tempr5(r11) ; Restore work register
ld r20,tempr0(r11) ; Restore work register
ld r21,tempr1(r11) ; Restore work register
ld r25,tempr2(r11) ; Restore work register
- mtctr r13 ; Restore the caller's CTR
+ mtctr r13 ; Restore the callers CTR
ld r22,tempr3(r11) ; Restore work register
ld r23,tempr4(r11) ; Restore work register
li r11,T_SYSTEM_CALL|T_FAM ; Set system code call
* set up:
*
* ENTRY: interrupts off, VM off, in 64-bit mode if supported
- * Caller's r13 saved in sprg2.
- * Caller's r11 saved in sprg3.
+ * Callers r13 saved in sprg2.
+ * Callers r11 saved in sprg3.
* Exception code (ie, T_SYSTEM_CALL etc) in r11.
* All other registers are live.
*
/*
*
* Here we will save off a mess of registers, the special ones and R0-R12. We use the DCBZ
- * instruction to clear and allcoate a line in the cache. This way we won't take any cache
- * misses, so these stores won't take all that long. Except the first line that is because
- * we can't do a DCBZ if the L1 D-cache is off. The rest we will skip if they are
+ * instruction to clear and allcoate a line in the cache. This way we will not take any cache
+ * misses, so these stores will not take all that long. Except the first line that is because
+ * we can not do a DCBZ if the L1 D-cache is off. The rest we will skip if they are
* off also.
*
* Note that if we are attempting to sleep (as opposed to nap or doze) all interruptions
/*
- * Here's where we come back from some instruction emulator. If we come back with
+ * Here is where we come back from some instruction emulator. If we come back with
* T_IN_VAIN, the emulation is done and we should just reload state and directly
- * go back to the interrupted code. Otherwise, we'll check to see if
+ * go back to the interrupted code. Otherwise, we will check to see if
* we need to redrive with a different interrupt, i.e., DSI.
* Note that this we are actually not redriving the rupt, rather changing it
* into a different one. Thus we clear the redrive bit.
andc r7,r7,r0 ; Pin time at 0 if under minimum
subfe r2,r2,r2 ; 0 if diff > 2**32, -1 otherwise
sub r7,r7,r10 ; Negative if duration is less than (max - min)
- or r2,r2,r0 ; If the duration is negative, it isn't too big
+ or r2,r2,r0 ; If the duration is negative, it is not too big
srawi r0,r7,31 ; -1 if duration is too small
and r7,r7,r2 ; Clear duration if high part too big
and r7,r7,r0 ; Clear duration if low part too big
}
+/*
+ * kvtophys64(addr)
+ *
+ * Convert a kernel virtual address to a 64-bit physical address
+ */
+vm_map_offset_t kvtophys64(vm_map_offset_t va) {
+ ppnum_t pa = pmap_find_phys(kernel_pmap, (addr64_t)va);
+
+ if (!pa)
+ return (vm_map_offset_t)0;
+ return (((vm_map_offset_t)pa) << 12) | (va & 0xfff);
+}
+
/*
* void ignore_zero_fault(boolean_t) - Sets up to ignore or honor any fault on
* page 0 access for the current thread.
*/
extern vm_offset_t phystokv(vm_offset_t pa); /* Get kernel virtual address from physical */
extern vm_offset_t kvtophys(vm_offset_t va); /* Get physical address from kernel virtual */
+extern vm_map_offset_t kvtophys64(vm_map_offset_t va); /* Get 64-bit physical address from kernel virtual */
extern vm_offset_t pmap_map(vm_offset_t va,
vm_offset_t spa,
vm_offset_t epa,
projects / apple / xnu.git / commitdiff
