Re: [PATCH v3 3/7] shm: add memfd_create() syscall

[Michael Kerrisk (man-pages)]

Hi David,

On Fri, Jun 13, 2014 at 2:41 PM, David Herrmann <dh.herrmann@xxxxxxxxx> wrote:
> Hi
>
> On Fri, Jun 13, 2014 at 2:27 PM, Michael Kerrisk (man-pages)
> <mtk.manpages@xxxxxxxxx> wrote:
>> Hi David,
>>
>> On Fri, Jun 13, 2014 at 12:36 PM, David Herrmann <dh.herrmann@xxxxxxxxx> wrote:
>>> memfd_create() is similar to mmap(MAP_ANON), but returns a file-descriptor
>>> that you can pass to mmap(). It can support sealing and avoids any
>>> connection to user-visible mount-points. Thus, it's not subject to quotas
>>> on mounted file-systems, but can be used like malloc()'ed memory, but
>>> with a file-descriptor to it.
>>>
>>> memfd_create() returns the raw shmem file, so calls like ftruncate() can
>>> be used to modify the underlying inode. Also calls like fstat()
>>> will return proper information and mark the file as regular file. If you
>>> want sealing, you can specify MFD_ALLOW_SEALING. Otherwise, sealing is not
>>> supported (like on all other regular files).
>>>
>>> Compared to O_TMPFILE, it does not require a tmpfs mount-point and is not
>>> subject to quotas and alike. It is still properly accounted to memcg
>>> limits, though.
>>
>> Where do I find / is there detailed documentation (ideally, a man
>> page) for this new system call?
>
> I did write a man-page proposal for memfd_create() and a patch for
> fcntl() for v1,

Ahh -- that's why I had a recollection of such a page ;-).

> however, the API changed several times so I didn't
> keep them up to date (the man-page patches are on LKML). However, I
> wrote a short introduction to memfd+sealing v3, that I recommend
> reading first:
>   http://dvdhrm.wordpress.com/2014/06/10/memfd_create2/

Yes, I saw it already. (It's good, but I want more.)

> This explains the idea behind the new API and describes almost all
> aspects of it. It's up-to-date to v3 and I will use it to write the
> final man-pages once Hugh and Andrew ACKed the patches. Let me know if
> anything is unclear.

The general notion these days is that a (comprehensive) manual page
_should_ come *with* the system call, rather than after the fact. And
there's a lot of value in that. I've found no end of bugs and design
errors while writing (comprehensive) man pages after the fact (by
which time it's too late to fix the design errors), and also found
quite a few of those issues when I've managed to work with folk at the
same time as they write the syscall. Bottom line: you really should
write formal documentation now, as part of the process of code
submission. It improves the chance of finding implementation and
design bugs, and may well widen your circle of reviewers.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/