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_get_refs.man,v $
29 .\" Revision 2.6 93/05/10 19:31:19 rvb
30 .\" updated
31 .\" [93/04/21 16:03:29 lli]
32 .\"
33 .\" Revision 2.5 91/12/11 08:42:57 jsb
34 .\" Changed <mach/mach.h> to <mach.h>.
35 .\" [91/11/25 10:55:27 rpd]
36 .\"
37 .\" Revision 2.4 91/05/14 17:06:30 mrt
38 .\" Correcting copyright
39 .\"
40 .\" Revision 2.3 91/02/14 14:11:20 mrt
41 .\" Changed to new Mach copyright
42 .\" [91/02/12 18:11:35 mrt]
43 .\"
44 .\" Revision 2.2 90/08/07 18:36:58 rpd
45 .\" Created.
46 .\"
47 .TH mach_port_get_refs 2 9/19/86
48 .CM 4
49 .SH NAME
50 .nf
51 mach_port_get_refs \- retrieves the number of user refs for a right
52 .SH SYNOPSIS
53 .nf
54 .ft B
55 #include <mach.h>
56
57 kern_return_t
58 mach_port_get_refs(task, name, right, refs)
59 mach_port_t task;
60 mach_port_t name;
61 mach_port_right_t right;
62 mach_port_urefs_t *refs; /* out */
63 .fi
64 .ft P
65 .SH ARGUMENTS
66 .TP 12
67 .B
68 task
69 The task holding the right.
70 .TP 12
71 .B
72 name
73 The task's name for the right.
74 .TP 12
75 .B
76 right
77 The type of right being examined.
78 .TP 12
79 .B
80 refs
81 Number of user references.
82 .SH DESCRIPTION
83 \fBmach_port_get_refs\fR returns the number of user references
84 a task has for a right.
85
86 The \fBright\fR argument takes the following values:
87 .nf
88 .in +5n
89 MACH_PORT_RIGHT_SEND
90 MACH_PORT_RIGHT_RECEIVE
91 MACH_PORT_RIGHT_SEND_ONCE
92 MACH_PORT_RIGHT_PORT_SET
93 MACH_PORT_RIGHT_DEAD_NAME
94 .fi
95 .in -5n
96
97 If \fBname\fR denotes a right, but not the type
98 of right specified, then zero is returned. Otherwise a positive number
99 of user references is returned. Note a name may simultaneously
100 denote send and receive rights.
101 .SH DIAGNOSTICS
102 .TP 25
103 KERN_SUCCESS
104 The call succeeded.
105 .TP 25
106 KERN_INVALID_TASK
107 \fBtask\fR was invalid.
108 .TP 25
109 KERN_INVALID_VALUE
110 \fBright\fR was invalid.
111 .TP 25
112 KERN_INVALID_NAME
113 \fBname\fR did not denote a right.
114 .PP
115 The \fBmach_port_get_refs\fR call is actually an RPC to \fBtask\fR,
116 normally a send right for a task port, but potentially any send right.
117 In addition to the normal diagnostic
118 return codes from the call's server (normally the kernel),
119 the call may return \fBmach_msg(2)\fR return codes.
120 .SH SEE ALSO
121 mach_port_mod_refs(2).
Cache object: 126e4dfd785512c40d965f64629dad48
|