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

[Jeff King <peff@peff.net>]

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

> 惠轶群 <huiyiqun@gmail.com> writes:
> 
> >> 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