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.man,v $
29 .\" Revision 2.6 93/05/10 19:30:59 rvb
30 .\" updated
31 .\" [93/04/21 16:03:10 lli]
32 .\"
33 .\" Revision 2.1.1.1 93/04/21 16:01:27 lli
34 .\" updated
35 .\"
36 .\" Revision 2.5 91/12/11 08:42:40 jsb
37 .\" Updated for MK62 (sequence numbers).
38 .\" [91/11/26 11:01:28 rpd]
39 .\"
40 .\" Changed <mach/mach.h> to <mach.h>.
41 .\" [91/11/25 10:55:09 rpd]
42 .\"
43 .\" Revision 2.4 91/05/14 17:05:46 mrt
44 .\" Correcting copyright
45 .\"
46 .\" Revision 2.3 91/02/14 14:10:55 mrt
47 .\" Changed to new Mach copyright
48 .\" [91/02/12 18:11:08 mrt]
49 .\"
50 .\" Revision 2.2 90/08/07 18:35:54 rpd
51 .\" Created.
52 .\"
53 .TH mach_port_allocate 2 4/13/87
54 .CM 4
55 .SH NAME
56 .nf
57 mach_port_allocate \- 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(task, right, name)
65 mach_port_t task;
66 mach_port_right_t right;
67 mach_port_t *name; /* out */
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\fR creates a new right in the specified task.
85 The new right's name is returned in \fBname\fR.
86
87 The \fBright\fR argument takes the following values:
88 .TP 12
89 MACH_PORT_RIGHT_RECEIVE
90 \fBmach_port_allocate\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\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\fR creates a dead name.
108 The new dead name has one user reference.
109 .PP
110 The returned \fBname\fR may be any name that wasn't in use.
111 .SH DIAGNOSTICS
112 .TP 25
113 KERN_SUCCESS
114 The call succeeded.
115 .TP 25
116 KERN_INVALID_TASK
117 \fBtask\fR was invalid.
118 .TP 25
119 KERN_INVALID_VALUE
120 \fBright\fR was invalid.
121 .TP 25
122 KERN_NO_SPACE
123 There was no room in \fBtask\fR's IPC name space for another right.
124 .TP 25
125 KERN_RESOURCE_SHORTAGE
126 The kernel ran out of memory.
127 .PP
128 The \fBmach_port_allocate\fR call is actually an RPC to \fBtask\fR,
129 normally a send right for a task port, but potentially any send right.
130 In addition to the normal diagnostic
131 return codes from the call's server (normally the kernel),
132 the call may return \fBmach_msg(2)\fR return codes.
133 .SH SEE ALSO
134 mach_port_allocate_name(2),
135 mach_port_insert_right(2),
136 mach_port_extract_right(2),
137 mach_port_get_receive_status(2).
Cache object: 9fe57afedd91573940f24cf08a454e33
|