Libc-1272.200.26.tar.gz

[apple/libc.git] / gen / FreeBSD / getmntinfo.3

diff --git a/gen/FreeBSD/getmntinfo.3 b/gen/FreeBSD/getmntinfo.3
index e5b6f179935d7fc01625826ac81e75dbb531b181..9bf03b4a086e0e491d01731d73959628216ce71c 100644 (file)
--- a/gen/FreeBSD/getmntinfo.3
+++ b/gen/FreeBSD/getmntinfo.3
@@ -28,63 +28,125 @@
 .\"     @(#)getmntinfo.3       8.1 (Berkeley) 6/9/93
 .\" $FreeBSD: src/lib/libc/gen/getmntinfo.3,v 1.13 2007/01/09 00:27:54 imp Exp $
 .\"
-.Dd June 9, 1993
+.Dd April 12, 2017
 .Dt GETMNTINFO 3
 .Os
 .Sh NAME
 .Nm getmntinfo
+.Nm getmntinfo_r_np
+.Nm getmntinfo64
 .Nd get information about mounted file systems
-.Sh LIBRARY
-.Lb libc
 .Sh SYNOPSIS
 .In sys/param.h
 .In sys/ucred.h
 .In sys/mount.h
 .Ft int
 .Fn getmntinfo "struct statfs **mntbufp" "int flags"
+.Ft int
+.Fn getmntinfo_r_np "struct statfs **mntbufp" "int flags"
+.Sh TRANSITIIONAL SYNOPSIS (NOW DEPRECATED)
+.Ft int
+.br
+.Fn getmntinfo64 "struct statfs64 **mntbufp" "int flags" ;
 .Sh DESCRIPTION
 The
 .Fn getmntinfo
 function
 returns an array of
-.Fn statfs
+.Ft statfs
 structures describing each currently mounted file system (see
 .Xr statfs 2 ) .
+As
+.Xr statfs 2
+indicates, the structure is defined differently depending on
+whether the macro _DARWIN_FEATURE_64_BIT_INODE is defined (see
+.Xr stat 2
+for more information on this macro).
 .Pp
 The
 .Fn getmntinfo
-function
-passes its
+and
+.Fn getmntinfo_r_np
+functions
+pass their
 .Fa flags
 argument transparently to
 .Xr getfsstat 2 .
+.Pp
+The
+.Fn getmntinfo
+function maintains ownership of the results buffer it allocates,
+and may overwrite or free this buffer in subsequent calls to
+.Fn getmntinfo .
+For this reason,
+.Fn getmntinfo
+is not thread-safe.
+.Pp
+The
+.Fn getmntinfo_r_np
+function is a thread-safe equivalent of
+.Fn getmntinfo
+that allocates a new results buffer on every call and transfers ownership
+of this buffer to the caller.
+The caller is responsible for freeing this memory with
+.Xr free 3 .
 .Sh RETURN VALUES
 On successful completion,
 .Fn getmntinfo
-returns a count of the number of elements in the array.
+and
+.Fn getmntinfo_r_np
+return a count of the number of elements in the array.
 The pointer to the array is stored into
 .Fa mntbufp .
 .Pp
 If an error occurs, zero is returned and the external variable
 .Va errno
 is set to indicate the error.
-Although the pointer
-.Fa mntbufp
-will be unmodified, any information previously returned by
+The
+.Fn getmntinfo
+function may modify the
+.Fa mbtbufp
+pointer even in the case of an error.
+In this situation, callers should consider any previous information
+returned by
 .Fn getmntinfo
-will be lost.
+to be lost.
+The
+.Fn getmntinfo_r_np
+function will not modify the
+.Fa mntbufp
+pointer in the case of an error.
 .Sh ERRORS
 The
 .Fn getmntinfo
-function
+and
+.Fn getmntinfo_r_np
+functions
 may fail and set errno for any of the errors specified for the library
 routines
 .Xr getfsstat 2
 or
 .Xr malloc 3 .
+.Sh TRANSITIONAL DESCRIPTION (NOW DEPRECATED)
+The
+.Fn getmntinfo64
+routine is equivalent to its corresponding non-64-suffixed routine,
+when 64-bit inodes are in effect.
+It was added before there was support for the symbol variants, and so is
+now deprecated.
+Instead of using it, set the
+.Dv _DARWIN_USE_64_BIT_INODE
+macro before including header files to force 64-bit inode support.
+.Pp
+The
+.Ft statfs64
+structure used by this deprecated routine is the same as the
+.Ft statfs
+structure when 64-bit inodes are in effect.
 .Sh SEE ALSO
 .Xr getfsstat 2 ,
 .Xr mount 2 ,
+.Xr stat 2 ,
 .Xr statfs 2 ,
 .Xr mount 8
 .Sh HISTORY
@@ -92,6 +154,9 @@ The
 .Fn getmntinfo
 function first appeared in
 .Bx 4.4 .
+The
+.Fn getmntinfo_r_np
+function first appeared in macOS 10.13.
 .Sh BUGS
 The
 .Fn getmntinfo