sync man page in coreutils and 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
Signature · 7 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): [email protected]
Quoted 5 lines · Michael Kerrisk (man-pages)
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.
Quoted 8 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): [email protected]
Hi Christoph,
Thanks for that quick response.
Quoted 18 lines · Christoph Hellwig
Quoted 5 lines · Michael Kerrisk (man-pages)
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.
Quoted 8 lines
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.)
Quoted 2 lines
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
Signature · 7 lines
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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 8 lines · Christoph Hellwig
Quoted 5 lines · Michael Kerrisk (man-pages)
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.
Quoted 10 lines
Quoted 9 lines
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.)
Quoted 2 lines
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.
A message that is not in the archive (sent off-list or not yet received): [email protected]
Quoted 28 lines · Pádraig Brady
Quoted 8 lines · Christoph Hellwig
Quoted 5 lines · Michael Kerrisk (man-pages)
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-invocationGenerally 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.
Quoted 10 lines
Quoted 9 lines
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.)
Quoted 4 lines
Quoted 2 lines
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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/