Re: [PATCH v3/GSoC 2/5] path.c: implement xdg_runtime_dir()

On Fri, Mar 25, 2016 at 09:55:59AM -0700, Junio C Hamano wrote:

惠轶群 [off-list ref] writes:

quoted

quoted

There's a lot of "what" here that the caller doesn't really care about,
and which may go stale with respect to the implementation over time. Can
we make something more succinct like:

  /*
   * Return a path suitable for writing run-time files related to git,
   * or NULL if no such path can be established. The resulting string
   * should be freed by the caller.
   */

?

That's clearer, but if I were the caller, I would worry about the
security of the path.
How about adding:

The security of the path is ensured by file permission.

Is "by file permission" descriptive enough?

To protect /a/b/c/socket, what filesystem entities have the right
permission bits set?  If the parent directory is writable by an
attacker, the permission bits on 'socket' itself may not matter as
the attacker can rename it away and create new one herself, for
example.

I think that is discussed elsewhere, and referring to the xdg document
is enough. My main point is that the docstring about a function should
tell a potential caller what they need to know to use it, but if it gets
overly long, that information is lost in the noise.

-Peff