Add and document the quota_convert function which converts between the

old 32-bit and the new 64-bit formats.

1 files changed, 26 insertions, 8 deletions

diff --git a/lib/libutil/quotafile.3 b/lib/libutil/quotafile.3
index d2134c505306..5702cec90762 100644
--- a/lib/libutil/quotafile.3
+++ b/lib/libutil/quotafile.3
@@ -1,6 +1,6 @@
 .\"-
-.\" Copyright (c) 2008 Dag-Erling Coïdan Smørgrav
-.\" All rights reserved.
+.\" Copyright (c) 2009 Dag-Erling Coïdan Smørgrav and
+.\" Marshall Kirk McKusick. All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd September 26, 2009
+.Dd December 28, 2009
 .Dt QUOTAFILE 3
 .Os
 .Sh NAME
@@ -40,6 +40,7 @@
 .Nm quota_qfname
 .Nm quota_maxid
 .Nm quota_check_path
+.Nm quota_convert
 .Nd "Manipulate quotas"
 .Sh LIBRARY
 .Lb libutil
@@ -72,6 +73,8 @@
 .Fn quota_maxid "const struct quotafile *qf"
 .Ft int
 .Fn quota_check_path "const struct quotafile *qf" "const char *path"
+.Ft int
+.Fn quota_convert "struct quotafile *qf" "int wordsize"
 .Sh DESCRIPTION
 These functions are designed to simplify access to filesystem quotas.
 If quotas are active on a filesystem,
@@ -219,9 +222,23 @@ If the
 argument refers to a symbolic link,
 .Fn quota_check_path
 will follow it.
+.Pp
+The
+.Fn quota_convert
+function converts the quota file associated with its
+.Va qf
+argument to the data size specified by its
+.Va wordsize
+argument.
+The supported wordsize arguments are 32 for the old 32-bit
+quota file format and 64 for the new 64-bit quota file format.
+The
+.Fn quota_convert
+function may only be called to operate on quota files that
+are not currently active.
 .Sh IMPLEMENTATION NOTES
-If the underlying quota file is in the old 32-bit format, limit and
-usage values written to the quota file will be clipped to 32 bits.
+If the underlying quota file is in or converted to the old 32-bit format,
+limit and usage values written to the quota file will be clipped to 32 bits.
 .Sh RETURN VALUES
 If the filesystem has quotas associated with it,
 .Fn quota_open
@@ -246,6 +263,7 @@ The
 .Fn quota_read ,
 .Fn quota_write_limits ,
 .Fn quota_write_usage ,
+.Fn quota_convert ,
 and
 .Fn quota_close
 functions return zero on success.
@@ -259,13 +277,13 @@ to indicate the error.
 .Xr quota.group 5
 .Sh HISTORY
 The
-.Nm
+.Nm quotafile
 functions first appeared in
-.Fx 8.0 .
+.Fx 8.1 .
 .Sh AUTHORS
 .An -nosplit
 The
-.Nm
+.Nm quotafile
 functions and this manual page were written by
 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org 
 and