sync man page in coreutils and man-pages

sync man page in coreutils and man-pages

[Michael Kerrisk (man-pages)]

Hi,

Sometime in the 20th century (before my watch), a sync(8)
page made its way into the Linux man-pages set that I maintain
(http://man7.org/linux/man-pages/man8/sync.8.html). It purportedly
documents the sync command from fileutils, which gives an idea
of its age, and the piece under notes notes some behavior of sync(2)
that ceased to be true many years ago.

The man-pages project generally focuses on only Linux kernel and
(g)libc interfaces, so this sync(8) page doesn't really belong,
and I would like to remove it. Also, I see that coreutils has a 
sync(1) page which covers the same command. However, I see that
that page lacks some details that are in the sync(8) page. Before
I retire the sync(8) page, would you be interested to integrate 
any of the following detail into the coreutils sync(1) page?

       The  kernel  keeps  data  in  memory to avoid doing (relatively
       slow) disk reads and writes.  This improves performance, but if
       the  computer crashes, data may be lost or the file system cor‐
       rupted as a result.  sync ensures that everything in memory  is
       written to disk.

       sync  should  be  called  before  the processor is halted in an
       unusual manner (e.g., before causing a kernel panic when debug‐
       ging  new  kernel  code).   In general, the processor should be
       halted using the shutdown(8) or reboot(8) or halt(8)  commands,
       which  will  attempt  to  put  the  system in a quiescent state
       before calling sync(2).  (Various implementations of these com‐
       mands  exist;  consult  your documentation; on some systems one
       should not call reboot(8) and halt(8) directly.)

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-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: sync man page in coreutils and man-pages

[Christoph Hellwig]

On Mon, Mar 10, 2014 at 01:03:41PM +0100, Michael Kerrisk (man-pages) wrote:
>        The  kernel  keeps  data  in  memory to avoid doing (relatively
>        slow) disk reads and writes.  This improves performance, but if
>        the  computer crashes, data may be lost or the file system cor???
>        rupted as a result.  sync ensures that everything in memory  is
>        written to disk.

This part looks correct.

>        sync  should  be  called  before  the processor is halted in an
>        unusual manner (e.g., before causing a kernel panic when debug???
>        ging  new  kernel  code).   In general, the processor should be
>        halted using the shutdown(8) or reboot(8) or halt(8)  commands,
>        which  will  attempt  to  put  the  system in a quiescent state
>        before calling sync(2).  (Various implementations of these com???
>        mands  exist;  consult  your documentation; on some systems one
>        should not call reboot(8) and halt(8) directly.)

This kind of information does not seem useful for a user of a command
line utility, and the last bit seems incorrect at least for Linux.

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: sync man page in coreutils and man-pages

[Michael Kerrisk (man-pages)]

Hi Christoph,

Thanks for that quick response.

On Mon, Mar 10, 2014 at 1:10 PM, Christoph Hellwig <hch-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:
> On Mon, Mar 10, 2014 at 01:03:41PM +0100, Michael Kerrisk (man-pages) wrote:
>>        The  kernel  keeps  data  in  memory to avoid doing (relatively
>>        slow) disk reads and writes.  This improves performance, but if
>>        the  computer crashes, data may be lost or the file system cor???
>>        rupted as a result.  sync ensures that everything in memory  is
>>        written to disk.
>
> This part looks correct.
>
>>        sync  should  be  called  before  the processor is halted in an
>>        unusual manner (e.g., before causing a kernel panic when debug???
>>        ging  new  kernel  code).   In general, the processor should be
>>        halted using the shutdown(8) or reboot(8) or halt(8)  commands,
>>        which  will  attempt  to  put  the  system in a quiescent state
>>        before calling sync(2).  (Various implementations of these com???
>>        mands  exist;  consult  your documentation; on some systems one
>>        should not call reboot(8) and halt(8) directly.)
>
> This kind of information does not seem useful for a user of a command
> line utility, and the last bit seems incorrect at least for Linux.

Yes, I agree that that paragraph is borderline. I included it in case
there was anything there to inspire an addition to sync(1). Anyway,
your comment just makes me more sure that this page should be booted
from man-pages.

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-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: sync man page in coreutils and man-pages

[Pádraig Brady]

On 03/10/2014 12:10 PM, Christoph Hellwig wrote:
> On Mon, Mar 10, 2014 at 01:03:41PM +0100, Michael Kerrisk (man-pages) wrote:
>>        The  kernel  keeps  data  in  memory to avoid doing (relatively
>>        slow) disk reads and writes.  This improves performance, but if
>>        the  computer crashes, data may be lost or the file system cor???
>>        rupted as a result.  sync ensures that everything in memory  is
>>        written to disk.
> 
> This part looks correct.

Yes, and it's already in the info pages:
http://www.gnu.org/software/coreutils/manual/coreutils.html#sync-invocation

Generally we keep the man pages to a minimum,
stating the interface and brief description.
Users are prompted to run info coreutils 'sync invocation'
for further discussion, where they'll see the above text.

> 
>>        sync  should  be  called  before  the processor is halted in an
>>        unusual manner (e.g., before causing a kernel panic when debug???
>>        ging  new  kernel  code).   In general, the processor should be
>>        halted using the shutdown(8) or reboot(8) or halt(8)  commands,
>>        which  will  attempt  to  put  the  system in a quiescent state
>>        before calling sync(2).  (Various implementations of these com???
>>        mands  exist;  consult  your documentation; on some systems one
>>        should not call reboot(8) and halt(8) directly.)
> 
> This kind of information does not seem useful for a user of a command
> line utility, and the last bit seems incorrect at least for Linux.

I agree.

thanks,
Pádraig.

Re: sync man page in coreutils and man-pages

[Michael Kerrisk (man-pages)]

On Mon, Mar 10, 2014 at 1:34 PM, Pádraig Brady <P@draigbrady.com> wrote:
> On 03/10/2014 12:10 PM, Christoph Hellwig wrote:
>> On Mon, Mar 10, 2014 at 01:03:41PM +0100, Michael Kerrisk (man-pages) wrote:
>>>        The  kernel  keeps  data  in  memory to avoid doing (relatively
>>>        slow) disk reads and writes.  This improves performance, but if
>>>        the  computer crashes, data may be lost or the file system cor???
>>>        rupted as a result.  sync ensures that everything in memory  is
>>>        written to disk.
>>
>> This part looks correct.
>
> Yes, and it's already in the info pages:
> http://www.gnu.org/software/coreutils/manual/coreutils.html#sync-invocation
>
> Generally we keep the man pages to a minimum,
> stating the interface and brief description.
> Users are prompted to run info coreutils 'sync invocation'
> for further discussion, where they'll see the above text.
>
>>
>>>        sync  should  be  called  before  the processor is halted in an
>>>        unusual manner (e.g., before causing a kernel panic when debug???
>>>        ging  new  kernel  code).   In general, the processor should be
>>>        halted using the shutdown(8) or reboot(8) or halt(8)  commands,
>>>        which  will  attempt  to  put  the  system in a quiescent state
>>>        before calling sync(2).  (Various implementations of these com???
>>>        mands  exist;  consult  your documentation; on some systems one
>>>        should not call reboot(8) and halt(8) directly.)
>>
>> This kind of information does not seem useful for a user of a command
>> line utility, and the last bit seems incorrect at least for Linux.
>
> I agree.

Right then. The man-pages project just shrank by one page.

Thanks for your input, Pádraig.

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/