Add rights for mapping buffer. Update (shared) buffer APIs.

mojo/public/c/system/buffer.h

Index: mojo/public/c/system/buffer.h
diff --git a/mojo/public/c/system/buffer.h b/mojo/public/c/system/buffer.h
index 0c253c006afc5e540b2f8b4d590156d90ecaca53..2dd747799169adb5ca772d169ca70e2b3b1f2168 100644
--- a/mojo/public/c/system/buffer.h
+++ b/mojo/public/c/system/buffer.h
@@ -102,7 +102,11 @@ MOJO_BEGIN_EXTERN_C
 // |options| may be set to null for a shared buffer with the default options.
 //
 // On success, |*shared_buffer_handle| will be set to the handle for the shared
-// buffer. (On failure, it is not modified.)
+// buffer. (On failure, it is not modified.) The handle has (at least) the
+// following rights: |MOJO_HANDLE_RIGHT_DUPLICATE|,
+// |MOJO_HANDLE_RIGHT_TRANSFER|, |MOJO_HANDLE_RIGHT_GET_OPTIONS|,
+// |MOJO_HANDLE_RIGHT_SET_OPTIONS|, |MOJO_HANDLE_RIGHT_MAP_READABLE|,
+// |MOJO_HANDLE_RIGHT_MAP_WRITABLE|, and |MOJO_HANDLE_RIGHT_MAP_EXECUTABLE|.
 //
 // Note: While more than |num_bytes| bytes may apparently be
 // available/visible/readable/writable, trying to use those extra bytes is
@@ -122,11 +126,11 @@ MojoResult MojoCreateSharedBuffer(
     uint64_t num_bytes,                               // In.
     MojoHandle* MOJO_RESTRICT shared_buffer_handle);  // Out.
 
-// |MojoDuplicateBufferHandle()|: Duplicates the handle |buffer_handle| to a
-// buffer. This creates another handle (returned in |*new_buffer_handle| on
-// success), which can then be sent to another application over a message pipe,
-// while retaining access to the |buffer_handle| (and any mappings that it may
-// have).
+// |MojoDuplicateBufferHandle()|: Duplicates the handle |buffer_handle| (which
+// must have the |MOJO_HANDLE_RIGHT_DUPLICATE| right) to a buffer. This creates
+// another handle (returned in |*new_buffer_handle| on success), which can then
+// be sent to another application over a message pipe, while retaining access to
+// the |buffer_handle| (and any mappings that it may have).
 //
 // |options| may be set to null to duplicate the buffer handle with the default
 // options.
@@ -138,6 +142,8 @@ MojoResult MojoCreateSharedBuffer(
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
 //       |buffer_handle| is not a valid buffer handle or |*options| is invalid).
+//   |MOJO_RESULT_PERMISSION_DENIED| if |buffer_handle| does not have the
+//       |MOJO_HANDLE_RIGHT_DUPLICATE| right.
 //   |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|.
 //   |MOJO_RESULT_BUSY| if |buffer_handle| is currently in use in some
 //       transaction (that, e.g., may result in it being invalidated, such as
@@ -149,9 +155,10 @@ MojoResult MojoDuplicateBufferHandle(
     MojoHandle* MOJO_RESTRICT new_buffer_handle);  // Out.
 
 // |MojoGetBufferInformation()|: Gets information about the buffer with handle
-// |buffer_handle|. |info| should be non-null and point to a buffer of size
-// |info_num_bytes|; |info_num_bytes| should be at least 16 (the size of the
-// first, and currently only, version of |struct MojoBufferInformation|).
+// |buffer_handle| (which must have the |MOJO_HANDLE_RIGHT_GET_OPTIONS| right).
+// |info| should be non-null and point to a buffer of size |info_num_bytes|;
+// |info_num_bytes| should be at least 16 (the size of the first, and currently
+// only, version of |struct MojoBufferInformation|).
 //
 // On success, |*info| will be filled with information about the given buffer.
 // Note that if additional (larger) versions of |struct MojoBufferInformation|
@@ -164,6 +171,8 @@ MojoResult MojoDuplicateBufferHandle(
 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
 //       |buffer_handle| is not a valid buffer handle, |*info| is null, or
 //       |info_num_bytes| is too small).
+//   |MOJO_RESULT_PERMISSION_DENIED| if |buffer_handle| does not have the
+//       |MOJO_HANDLE_RIGHT_GET_OPTIONS| right.
 //   |MOJO_RESULT_BUSY| if |buffer_handle| is currently in use in some
 //       transaction (that, e.g., may result in it being invalidated, such as
 //       being sent in a message).
@@ -172,10 +181,12 @@ MojoResult MojoGetBufferInformation(MojoHandle buffer_handle,            // In.
                                     uint32_t info_num_bytes);            // In.
 
 // |MojoMapBuffer()|: Maps the part (at offset |offset| of length |num_bytes|)
-// of the buffer given by |buffer_handle| into memory, with options specified by
-// |flags|. |offset + num_bytes| must be less than or equal to the size of the
-// buffer. On success, |*buffer| points to memory with the requested part of the
-// buffer. (On failure, it is not modified.)
+// of the buffer given by |buffer_handle| (which must have both the
+// |MOJO_HANDLE_RIGHT_MAP_READABLE| and |MOJO_HANDLE_RIGHT_MAP_WRITABLE| rights)
+// into memory, with options specified by |flags|. |offset + num_bytes| must be
+// less than or equal to the size of the buffer. On success, |*buffer| points to
+// memory with the requested part of the buffer. (On failure, it is not
+// modified.)
 //
 // A single buffer handle may have multiple active mappings (possibly depending
 // on the buffer type). The permissions (e.g., writable or executable) of the
@@ -191,6 +202,9 @@ MojoResult MojoGetBufferInformation(MojoHandle buffer_handle,            // In.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
 //       |buffer_handle| is not a valid buffer handle or the range specified by
 //       |offset| and |num_bytes| is not valid).
+//   |MOJO_RESULT_PERMISSION_DENIED| if |buffer_handle| does not have both the
+//       |MOJO_HANDLE_RIGHT_MAP_READABLE| and |MOJO_HANDLE_RIGHT_MAP_WRITABLE|
+//       rights.
 //   |MOJO_RESULT_RESOURCE_EXHAUSTED| if the mapping operation itself failed
 //       (e.g., due to not having appropriate address space available).
 //   |MOJO_RESULT_BUSY| if |buffer_handle| is currently in use in some