Hey Pat,
On Thu, Dec 06, 2012 at 03:56:47PM +1100, Pat Emblen wrote:
> A patch for the man page is (hopefully) attached.
Thanks for the patch!
> I'll warn you that
> this is the first time I've edited a man page or generated a patch,
> so it could be wrong / incomplete.
Ok, I'll go easy on you then. ;)
There are some guidelines for submitting patches in the kernel sources
under Documentation/SubmittingPatches. Please give that a quick read:
I think it will help you. (read: it will help us get your patch in
faster)
> Having said that I still personally consider a 'safety catch' on the
> root filesystem would be a good idea.
I tend to agree. It really sucks that someone had to drive out to the
site to get things working again. Not a great situation.
> Description: Updates to the man page to more accurately describe the
> behaviour of the program.
> Forwarded: not-needed
> Bug-Debian: http://bugs.debian.org/694624
> Author: Patrick Emblen <support@xxxxxxxxxxxxxxxx>
> --- a/man/man8/xfs_freeze.8
> +++ b/man/man8/xfs_freeze.8
> @@ -1,16 +1,17 @@
> .TH xfs_freeze 8
> .SH NAME
> -xfs_freeze \- suspend access to an XFS filesystem
> +xfs_freeze \- suspend access to a freezable filesystem
> .SH SYNOPSIS
> .B xfs_freeze \-f
> |
> .B \-u
> -.I mount-point
> -.fi
> -.SH DESCRIPTION
> -.B xfs_freeze
> -suspends and resumes access to an XFS filesystem (see
> -.BR xfs (5)).
> +.I path.fi
> +.SH DESCRIPTION.B xfs_freezesuspends and resumes access to compatible
> filesystems.
^^ Do you need a newline there?
xfs_freeze suspends
> +The command was originaly specific to the XFS filesystem (see
> +.BR xfs (5))but since Linux kernel version 2.6.29, the interface which
^^^^^^^ This displays without spaces between. e.g
butsinceLinuxKernelVersion2.
> +XFS uses to freeze and unfreeze has been elevated to the VFS, so that
> +this tool can now be used on many other Linux filesystems.
> +The root filesystem is not treated in any special way and may also be frozen.
I think this history lesson was more appropriate in the notes section of the
manpage.
> .PP
> .B xfs_freeze
> halts new access to the filesystem and creates a stable image on disk.
> @@ -19,15 +20,14 @@
> that support the creation of snapshots.
> .PP
> The
> -.I mount-point
> -argument is the pathname of the directory where the filesystem
> -is mounted.
> -The filesystem must be mounted to be frozen (see
> -.BR mount (8)).
> +.I path
> +argument is the path to any directory within the mounted filesystem up to
> and including
> +the
> +.I mount-point.
Not sure you need 'up to and including the mount-point'?
> .PP
> The
> .B \-f
> -flag requests the specified XFS filesystem to be
> +flag requests the specified filesystem to be
Ok.
> frozen from new modifications.
> When this is selected, all ongoing transactions in the filesystem
> are allowed to complete, new write system calls are halted, other
> @@ -55,16 +55,23 @@
> must be supplied to
> .BR xfs_freeze .
> .SH NOTES
> -A copy of a frozen XFS filesystem will usually have the same universally
> +.BR xfs_freeze
> +treats the root filesystem the same as any other filesystem.
> +Take great care to verify that the path you specify contains the filesystem
> +you intend to freeze and is not for example, an empty mount-point.
I think this is all you need, just make it bold?
> +If you inadvertently freeze the root filesystem you should immediately
> +unfreeze it with the
> +.B \-u
> +option. If you attempt any action that tries to write to the frozen
> filesystem
> +your shell can be blocked waiting for the write and in most cases you will
> +not be able to open another shell to run the unfreeze command.
> +.PP
> +A copy of a frozen filesystem will usually have the same universally
That's pretty wordy... do we really need all that?
> unique identifier (UUID) as the original, and thus may be prevented from
> being mounted.
> -The XFS
> +For XFS filesystems, the
> .B nouuid
> mount option can be used to circumvent this issue.
> -.PP
> -In Linux kernel version 2.6.29, the interface which XFS uses to freeze
> -and unfreeze was elevated to the VFS, so that this tool can now be
> -used on many other Linux filesystems.
> .SH SEE ALSO
> .BR xfs (5),
> .BR lvm (8),
Could you clean those up and repost? If not we'll figure something out
eventually. ;)
Thanks again,
Ben
|