Re: [PATCH 04/11] doc: document mach_port_set_protected_payload
At Mon, 17 Feb 2014 23:35:12 +0100,
Richard Braun wrote:
>
> On Mon, Feb 17, 2014 at 06:20:54PM +0100, Justus Winter wrote:
> > +@deftypefun kern_return_t mach_port_set_protected_payload (@w{ipc_space_t
> > @var{task}}, @w{mach_port_t @var{name}}, @w{unsigned long @var{payload}})
> > +The function @code{mach_port_set_protected_payload} sets the protected
> > +payload to @var{payload}. If @var{payload} is non-zero, the
> > +@code{msgh_protected_payload} field will be set to @var{payload} if a
> > +message is delivered to @var{name}.
>
> If I'm right, this also means switching back from the protected payload
> is done by calling this RPC with a payload of 0. It could be worth
> emphasizing that 0 is an invalid value for a protected payload.
These semantics are unfortunate. 0 should be valid. Add another IPC
to clear the pp or add a parameter to this IPC called, say, set, which
if true sets the pp to the provided value and otherwise clears the pp.
Neal
Re: [PATCH 04/11] doc: document mach_port_set_protected_payload
On Mon, Feb 17, 2014 at 06:20:54PM +0100, Justus Winter wrote:
> +@deftypefun kern_return_t mach_port_set_protected_payload (@w{ipc_space_t
> @var{task}}, @w{mach_port_t @var{name}}, @w{unsigned long @var{payload}})
> +The function @code{mach_port_set_protected_payload} sets the protected
> +payload to @var{payload}. If @var{payload} is non-zero, the
> +@code{msgh_protected_payload} field will be set to @var{payload} if a
> +message is delivered to @var{name}.
If I'm right, this also means switching back from the protected payload
is done by calling this RPC with a payload of 0. It could be worth
emphasizing that 0 is an invalid value for a protected payload.
--
Richard Braun
[PATCH 04/11] doc: document mach_port_set_protected_payload
* doc/mach.texi (Receive Rights): Document
mach_port_set_protected_payload.
---
doc/mach.texi | 18 ++
1 file changed, 18 insertions(+)
diff --git a/doc/mach.texi b/doc/mach.texi
index d089224..67c5fe9 100644
--- a/doc/mach.texi
+++ b/doc/mach.texi
@@ -2715,6 +2715,24 @@ In addition to the normal diagnostic return codes from
the call's server
(normally the kernel), the call may return @code{mach_msg} return codes.
@end deftypefun
+@deftypefun kern_return_t mach_port_set_protected_payload (@w{ipc_space_t
@var{task}}, @w{mach_port_t @var{name}}, @w{unsigned long @var{payload}})
+The function @code{mach_port_set_protected_payload} sets the protected
+payload to @var{payload}. If @var{payload} is non-zero, the
+@code{msgh_protected_payload} field will be set to @var{payload} if a
+message is delivered to @var{name}.
+
+The function returns @code{KERN_SUCCESS} if the call succeeded,
+@code{KERN_INVALID_TASK} if @var{task} was invalid,
+@code{KERN_INVALID_NAME} if @var{name} did not denote a right and
+@code{KERN_INVALID_RIGHT} if @var{name} denoted a right, but not a
+receive right.
+
+The @code{mach_port_set_protected_payload} call is actually an RPC to
+@var{task}, normally a send right for a task port, but potentially any
+send right. In addition to the normal diagnostic return codes from
+the call's server (normally the kernel), the call may return
+@code{mach_msg} return codes.
+@end deftypefun
@node Port Sets
@subsection Port Sets
--
1.8.5.2
