| Message ID | 20221017175523.2048887-3-zokeefe@google.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | Add MADV_COLLAPSE documentation | expand |
Hi Zach, On 10/17/22 19:55, Zach OKeefe wrote: > From: Zach O'Keefe <zokeefe@google.com> > > EINVAL is an overloaded error code for madvise(2) and it's not clear > under what context it means "advice is not valid" vs another error. > > Explicitly document that madvise(0, 0, advice) can reliably be used to > probe for kernel support for "advice", returning zero iff "advice" is > supported by the kernel. > > Signed-off-by: Zach O'Keefe <zokeefe@google.com> > --- > man2/madvise.2 | 7 +++++++ > 1 file changed, 7 insertions(+) > > diff --git a/man2/madvise.2 b/man2/madvise.2 > index e14e0f7fb..adfe24c24 100644 > --- a/man2/madvise.2 > +++ b/man2/madvise.2 > @@ -789,6 +789,13 @@ that are not mapped, the Linux version of > ignores them and applies the call to the rest (but returns > .B ENOMEM > from the system call, as it should). > +.PP > +.BR madvise (0, > +0, > +.IR advice ) For expressions, we don't follow the same highlighting rules as in identifiers and man-page references. Instead we use all italics. See man-pages(7): Expressions, if not written on a separate indented line, should be specified in italics. Again, the use of non‐ breaking spaces may be appropriate if the expression is inlined with normal text. Cheers, Alex > +will return zero iff > +.I advice > +is supported by the kernel and can be relied on to probe for support. > .\" .SH HISTORY > .\" The > .\" .BR madvise ()
Hey Alex, > > diff --git a/man2/madvise.2 b/man2/madvise.2 > > index e14e0f7fb..adfe24c24 100644 > > --- a/man2/madvise.2 > > +++ b/man2/madvise.2 > > @@ -789,6 +789,13 @@ that are not mapped, the Linux version of > > ignores them and applies the call to the rest (but returns > > .B ENOMEM > > from the system call, as it should). > > +.PP > > +.BR madvise (0, > > +0, > > +.IR advice ) > > For expressions, we don't follow the same highlighting rules as in > identifiers and man-page references. Instead we use all italics. See > man-pages(7): > > Expressions, if not written on a separate indented line, > should be specified in italics. Again, the use of non‐ > breaking spaces may be appropriate if the expression is > inlined with normal text. Just to confirm, by "expression", you mean "madvise(0, 0, advice)"? If so, to be consistent with the other note, perhaps best to break this into a phrase such as: --8<--- .BR madvise () called with zero for both .IR addr and .IR length will return zero iff .I advice is supported by the kernel and can be relied on to probe for support. --8<--- Thanks, Zach
Hey Zach! On 10/18/22 19:53, Zach O'Keefe wrote: > Hey Alex, > >>> diff --git a/man2/madvise.2 b/man2/madvise.2 >>> index e14e0f7fb..adfe24c24 100644 >>> --- a/man2/madvise.2 >>> +++ b/man2/madvise.2 >>> @@ -789,6 +789,13 @@ that are not mapped, the Linux version of >>> ignores them and applies the call to the rest (but returns >>> .B ENOMEM >>> from the system call, as it should). >>> +.PP >>> +.BR madvise (0, >>> +0, >>> +.IR advice ) >> >> For expressions, we don't follow the same highlighting rules as in >> identifiers and man-page references. Instead we use all italics. See >> man-pages(7): >> >> Expressions, if not written on a separate indented line, >> should be specified in italics. Again, the use of non‐ >> breaking spaces may be appropriate if the expression is >> inlined with normal text. > > Just to confirm, by "expression", you mean "madvise(0, 0, advice)"? Yes, I meant that. > If > so, to be consistent with the other note, perhaps best to break this > into a phrase such as: > > --8<--- > .BR madvise () > called with zero for both > .IR addr > and > .IR length > will return zero iff > .I advice > is supported by the kernel and can be relied on to probe for support. > --8<--- I think the C expression was more readable. Cheers, Alex > > Thanks, > Zach
On Tue, Oct 18, 2022 at 11:04 AM Alejandro Colomar <alx.manpages@gmail.com> wrote: > > Hey Zach! > > On 10/18/22 19:53, Zach O'Keefe wrote: > > Hey Alex, > > > >>> diff --git a/man2/madvise.2 b/man2/madvise.2 > >>> index e14e0f7fb..adfe24c24 100644 > >>> --- a/man2/madvise.2 > >>> +++ b/man2/madvise.2 > >>> @@ -789,6 +789,13 @@ that are not mapped, the Linux version of > >>> ignores them and applies the call to the rest (but returns > >>> .B ENOMEM > >>> from the system call, as it should). > >>> +.PP > >>> +.BR madvise (0, > >>> +0, > >>> +.IR advice ) > >> > >> For expressions, we don't follow the same highlighting rules as in > >> identifiers and man-page references. Instead we use all italics. See > >> man-pages(7): > >> > >> Expressions, if not written on a separate indented line, > >> should be specified in italics. Again, the use of non‐ > >> breaking spaces may be appropriate if the expression is > >> inlined with normal text. > > > > Just to confirm, by "expression", you mean "madvise(0, 0, advice)"? > > Yes, I meant that. > > > If > > so, to be consistent with the other note, perhaps best to break this > > into a phrase such as: > > > > --8<--- > > .BR madvise () > > called with zero for both > > .IR addr > > and > > .IR length > > will return zero iff > > .I advice > > is supported by the kernel and can be relied on to probe for support. > > --8<--- > > I think the C expression was more readable. SGTM - will update for v2. Appreciate your help here! Best, Zach
diff --git a/man2/madvise.2 b/man2/madvise.2 index e14e0f7fb..adfe24c24 100644 --- a/man2/madvise.2 +++ b/man2/madvise.2 @@ -789,6 +789,13 @@ that are not mapped, the Linux version of ignores them and applies the call to the rest (but returns .B ENOMEM from the system call, as it should). +.PP +.BR madvise (0, +0, +.IR advice ) +will return zero iff +.I advice +is supported by the kernel and can be relied on to probe for support. .\" .SH HISTORY .\" The .\" .BR madvise ()