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_insert_right.man,v $
29 .\" Revision 2.6 93/05/10 19:31:26 rvb
30 .\" updated
31 .\" [93/04/21 16:03:35 lli]
32 .\"
33 .\" Revision 2.5 91/12/11 08:43:03 jsb
34 .\" Changed <mach/mach.h> to <mach.h>.
35 .\" [91/11/25 10:55:33 rpd]
36 .\"
37 .\" Revision 2.4 91/05/14 17:06:47 mrt
38 .\" Correcting copyright
39 .\"
40 .\" Revision 2.3 91/02/14 14:11:32 mrt
41 .\" Changed to new Mach copyright
42 .\" [91/02/12 18:11:43 mrt]
43 .\"
44 .\" Revision 2.2 90/08/07 18:37:11 rpd
45 .\" Created.
46 .\"
47 .TH mach_port_insert_right 2 4/13/87
48 .CM 4
49 .SH NAME
50 .nf
51 mach_port_insert_right \- inserts a port right into a task
52 .SH SYNOPSIS
53 .nf
54 .ft B
55 #include <mach.h>
56
57 kern_return_t
58 mach_port_insert_right(task, name, right, right_type)
59 mach_port_t task;
60 mach_port_t name;
61 mach_port_t right;
62 mach_msg_type_name_t right_type;
63 .fi
64 .ft P
65 .SH ARGUMENTS
66 .TP 12
67 .B
68 task
69 The task which gets the caller's right.
70 .TP 12
71 .B
72 name
73 The name by which \fBtask\fR will know the right.
74 .TP 12
75 .B
76 right
77 The port right.
78 .TP 12
79 .B
80 right_type
81 IPC type of the sent right; e.g., MACH_MSG_TYPE_COPY_SEND
82 or MACH_MSG_TYPE_MOVE_RECEIVE.
83 .SH DESCRIPTION
84 \fBmach_port_insert_right\fR
85 inserts into \fBtask\fR the caller's right for a port, using a specified
86 name for the right in the target task.
87
88 The specified \fBname\fR can't be one of the reserved values
89 MACH_PORT_NULL or MACH_PORT_DEAD. The right
90 can't be MACH_PORT_NULL or MACH_PORT_DEAD.
91
92 The argument \fBright_type\fR specifies a right to be inserted and
93 how that right should be extracted from the caller. It should
94 be a value appropriate for \fBmsgt_name\fR; see \fBmach_msg(2)\fR.
95
96 If \fBright_type\fR is
97 MACH_MSG_TYPE_MAKE_SEND, MACH_MSG_TYPE_MOVE_SEND, or
98 MACH_MSG_TYPE_COPY_SEND, then a send right is inserted.
99 If the target already holds send or receive
100 rights for the port, then \fBname\fR should denote those rights in the
101 target. Otherwise, \fBname\fR should be unused in the target. If the
102 target already has send rights, then those send rights gain an
103 additional user reference. Otherwise, the target gains a send right,
104 with a user reference count of one.
105
106 If \fBright_type\fR is MACH_MSG_TYPE_MAKE_SEND_ONCE or
107 MACH_MSG_TYPE_MOVE_SEND_ONCE, then a send-once right is inserted.
108 The \fBname\fR should be unused in the target.
109 The target gains a send-once right.
110
111 If \fBright_type\fR is MACH_MSG_TYPE_MOVE_RECEIVE, then a receive right
112 is inserted. If the target already holds send rights
113 for the port, then \fBname\fR should denote those rights in the target.
114 Otherwise, \fBname\fR should be unused in the target. The receive
115 right is moved into the target task.
116 .SH DIAGNOSTICS
117 .TP 25
118 KERN_SUCCESS
119 The call succeeded.
120 .TP 25
121 KERN_INVALID_TASK
122 \fBtask\fR was invalid.
123 .TP 25
124 KERN_INVALID_VALUE
125 \fBname\fR was MACH_PORT_NULL or MACH_PORT_DEAD.
126 .TP 25
127 KERN_NAME_EXISTS
128 \fBname\fR already denoted a right.
129 .TP 25
130 KERN_INVALID_VALUE
131 \fBright\fR was not a port right.
132 .TP 25
133 KERN_INVALID_CAPABILITY
134 \fBright\fR was null or dead.
135 .TP 25
136 KERN_UREFS_OVERFLOW
137 Inserting the right would overflow \fBname\fR's user-reference count.
138 .TP 25
139 KERN_RIGHT_EXISTS
140 \fBtask\fR already had rights for the port, with a different name.
141 .TP 25
142 KERN_RESOURCE_SHORTAGE
143 The kernel ran out of memory.
144 .PP
145 The \fBmach_port_insert_right\fR call is actually an RPC to \fBtask\fR,
146 normally a send right for a task port, but potentially any send right.
147 In addition to the normal diagnostic
148 return codes from the call's server (normally the kernel),
149 the call may return \fBmach_msg(2)\fR return codes.
150 .SH SEE ALSO
151 mach_port_extract_right(2), mach_msg(2).
Cache object: 85007e4ca42d0dea486d4d9cb2f6ea19
|