1 .\"
2 .\" Mach Operating System
3 .\" Copyright (c) 1991,1990 Carnegie Mellon University
4 .\" All Rights Reserved.
5 .\"
6 .\" Permission to use, copy, modify and distribute this software and its
7 .\" documentation is hereby granted, provided that both the copyright
8 .\" notice and this permission notice appear in all copies of the
9 .\" software, derivative works or modified versions, and any portions
10 .\" thereof, and that both notices appear in supporting documentation.
11 .\"
12 .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
13 .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
14 .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
15 .\"
16 .\" Carnegie Mellon requests users of this software to return to
17 .\"
18 .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
19 .\" School of Computer Science
20 .\" Carnegie Mellon University
21 .\" Pittsburgh PA 15213-3890
22 .\"
23 .\" any improvements or extensions that they make and grant Carnegie Mellon
24 .\" the rights to redistribute these changes.
25 .\"
26 .\"
27 .\" HISTORY
28 .\" $Log: mach_port_extract_right.man,v $
29 .\" Revision 2.6 93/05/10 19:31:13 rvb
30 .\" updated
31 .\" [93/04/21 16:03:22 lli]
32 .\"
33 .\" Revision 2.5 91/12/11 08:42:52 jsb
34 .\" Changed <mach/mach.h> to <mach.h>.
35 .\" [91/11/25 10:55:22 rpd]
36 .\"
37 .\" Revision 2.4 91/05/14 17:06:16 mrt
38 .\" Correcting copyright
39 .\"
40 .\" Revision 2.3 91/02/14 14:11:11 mrt
41 .\" Changed to new Mach copyright
42 .\" [91/02/12 18:11:23 mrt]
43 .\"
44 .\" Revision 2.2 90/08/07 18:36:37 rpd
45 .\" Created.
46 .\"
47 .TH mach_port_extract_right 2 4/13/87
48 .CM 4
49 .SH NAME
50 .nf
51 mach_port_extract_right \- extracts a port right from a task
52 .SH SYNOPSIS
53 .nf
54 .ft B
55 #include <mach.h>
56
57 kern_return_t
58 mach_port_extract_right(task, name, desired_type, right, acquired_type)
59 mach_port_t task;
60 mach_port_t name;
61 mach_msg_type_name_t desired_type;
62 mach_port_t *right; /* out */
63 mach_msg_type_name_t *acquired_type; /* out */
64 .fi
65 .ft P
66 .SH ARGUMENTS
67 .TP 12
68 .B
69 task
70 The task holding the port right.
71 .TP 12
72 .B
73 name
74 The task's name for the port right.
75 .TP 12
76 .B
77 desired_type
78 IPC type, specifying how the right should be extracted.
79 .TP 12
80 .B
81 right
82 The extracted right.
83 .TP 12
84 .B
85 acquired_type
86 The type of the extracted right.
87 .SH DESCRIPTION
88 \fBmach_port_extract_right\fR extracts a port right
89 from the target task and returns it to the caller
90 as if the task sent the right voluntarily, using \fBdesired_type\fR
91 as the value of \fBmsgt_name\fR. See \fBmach_msg(2)\fR.
92
93 The returned value of \fBacquired_type\fR will be MACH_MSG_TYPE_PORT_SEND
94 if a send right is extracted, MACH_MSG_TYPE_PORT_RECEIVE
95 if a receive right is extracted, and MACH_MSG_TYPE_PORT_SEND_ONCE
96 if a send-once right is extracted.
97 .SH DIAGNOSTICS
98 .TP 25
99 KERN_SUCCESS
100 The call succeeded.
101 .TP 25
102 KERN_INVALID_TASK
103 \fBtask\fR was invalid.
104 .TP 25
105 KERN_INVALID_NAME
106 \fBname\fR did not denote a right.
107 .TP 25
108 KERN_INVALID_RIGHT
109 \fBname\fR denoted an invalid right.
110 .TP 25
111 KERN_INVALID_VALUE
112 \fBdesired_type\fR was invalid.
113 .PP
114 The \fBmach_port_extract_right\fR call is actually an RPC to \fBtask\fR,
115 normally a send right for a task port, but potentially any send right.
116 In addition to the normal diagnostic
117 return codes from the call's server (normally the kernel),
118 the call may return \fBmach_msg(2)\fR return codes.
119 .SH SEE ALSO
120 mach_port_insert_right(2), mach_msg(2).
Cache object: 82f1fd22ba94ac13ac74c5eb474acbd0
|