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_allocate_name.man,v $
29 .\" Revision 2.6 93/05/10 19:31:02 rvb
30 .\" updated
31 .\" [93/04/21 16:03:13 lli]
32 .\"
33 .\" Revision 2.1.1.1 93/04/21 16:01:37 lli
34 .\" updated
35 .\"
36 .\" Revision 2.5 91/12/11 08:42:42 jsb
37 .\" Updated for MK62 (sequence numbers).
38 .\" [91/11/26 11:01:31 rpd]
39 .\"
40 .\" Changed <mach/mach.h> to <mach.h>.
41 .\" [91/11/25 10:55:13 rpd]
42 .\"
43 .\" Revision 2.4 91/05/14 17:05:53 mrt
44 .\" Correcting copyright
45 .\"
46 .\" Revision 2.3 91/02/14 14:10:59 mrt
47 .\" Changed to new Mach copyright
48 .\" [91/02/12 18:11:12 mrt]
49 .\"
50 .\" Revision 2.2 90/08/07 18:36:03 rpd
51 .\" Created.
52 .\"
53 .TH mach_port_allocate_name 2 4/13/87
54 .CM 4
55 .SH NAME
56 .nf
57 mach_port_allocate_name \- creates a port right
58 .SH SYNOPSIS
59 .nf
60 .ft B
61 #include <mach.h>
62
63 kern_return_t
64 mach_port_allocate_name(task, right, name)
65 mach_port_t task;
66 mach_port_right_t right;
67 mach_port_t name;
68 .fi
69 .ft P
70 .SH ARGUMENTS
71 .TP 12
72 .B
73 task
74 The task acquiring the port right.
75 .TP 12
76 .B
77 right
78 The kind of right which will be created.
79 .TP 12
80 .B
81 name
82 The task's name for the port right.
83 .SH DESCRIPTION
84 \fBmach_port_allocate_name\fR creates a new right in the specified task,
85 with a specified name for the new right.
86
87 The \fBright\fR argument takes the following values:
88 .TP 12
89 MACH_PORT_RIGHT_RECEIVE
90 \fBmach_port_allocate_name\fR
91 creates a port. The new port is not a member
92 of any port set. It doesn't have any extant send or send-once rights.
93 Its make-send count is zero, its sequence number is zero,
94 its queue limit is MACH_PORT_QLIMIT_DEFAULT,
95 and it has no queued messages.
96 \fBname\fR denotes the receive right for the new port.
97
98 \fBtask\fR does not hold send rights for the new port, only the receive right.
99 \fBmach_port_insert_right(2)\fR and \fBmach_port_extract_right(2)\fR can
100 be used to convert the receive right into a combined send/receive right.
101 .TP 12
102 MACH_PORT_RIGHT_PORT_SET
103 \fBmach_port_allocate_name\fR creates a port set.
104 The new port set has no members.
105 .TP 12
106 MACH_PORT_RIGHT_DEAD_NAME
107 \fBmach_port_allocate_name\fR creates a new dead name.
108 The new dead name has one user reference.
109 .PP
110 \fBname\fR must not already be in use for some right,
111 and it can't be the reserved values MACH_PORT_NULL
112 and MACH_PORT_DEAD.
113 .SH DIAGNOSTICS
114 .TP 25
115 KERN_SUCCESS
116 The call succeeded.
117 .TP 25
118 KERN_INVALID_TASK
119 \fBtask\fR was invalid.
120 .TP 25
121 KERN_INVALID_VALUE
122 \fBright\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 was already in use for a port right.
129 .TP 25
130 KERN_RESOURCE_SHORTAGE
131 The kernel ran out of memory.
132 .PP
133 The \fBmach_port_allocate_name\fR call is actually an RPC to \fBtask\fR,
134 normally a send right for a task port, but potentially any send right.
135 In addition to the normal diagnostic
136 return codes from the call's server (normally the kernel),
137 the call may return \fBmach_msg(2)\fR return codes.
138 .SH SEE ALSO
139 mach_port_allocate(2),
140 mach_port_insert_right(2),
141 mach_port_extract_right(2),
142 mach_port_get_receive_status(2).
Cache object: a5f8b2ff83741860645dc3ed078bdc00
|