autofs: Remove BUGS section from autofs(5)
[dragonfly.git] / lib / libc / sys / mountctl.2
1 .\"
2 .\" Copyright (c) 2008
3 .\"     The DragonFly Project.  All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\"
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\"    notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\"    notice, this list of conditions and the following disclaimer in
13 .\"    the documentation and/or other materials provided with the
14 .\"    distribution.
15 .\" 3. Neither the name of The DragonFly Project nor the names of its
16 .\"    contributors may be used to endorse or promote products derived
17 .\"    from this software without specific, prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .Dd July 21, 2009
33 .Dt MOUNTCTL 2
34 .Os
35 .Sh NAME
36 .Nm mountctl
37 .Nd execute a mount control operation
38 .Sh LIBRARY
39 .Lb libc
40 .Sh SYNOPSIS
41 .In sys/mountctl.h
42 .Ft int
43 .Fo mountctl
44 .Fa "const char *path"
45 .Fa "int op"
46 .Fa "int fd"
47 .Fa "void *ctl"
48 .Fa "int ctllen"
49 .Fa "void *buf"
50 .Fa "int buflen"
51 .Fc
52 .Sh DESCRIPTION
53 The
54 .Fn mountctl
55 system call executes the mount control operation
56 .Fa op
57 on the mount point
58 .Fa path .
59 An optional file descriptor
60 .Fa fd
61 can be passed, or set to -1 if unneeded.
62 The
63 .Fa ctl
64 argument is for passing operation specific data and usually points to
65 some struct (see
66 .Sx CONTROL OPERATIONS
67 for further information).
68 The data's size is specified by
69 .Fa ctllen .
70 The
71 .Fa buf
72 and
73 .Fa buflen
74 arguments are used if the operation needs to return data to the caller
75 or set to
76 .Dv NULL
77 and 0 if unused.
78 .Sh CONTROL OPERATIONS
79 The following operations are defined in
80 .In sys/mountctl.h :
81 .Bl -tag -width indent
82 .It Dv MOUNTCTL_SET_EXPORT
83 Set export control of a filesystem.
84 This operation needs a
85 .Vt struct export_args
86 passed in
87 .Fa ctl .
88 Note that export control for numerous filesystems may still only be settable
89 with
90 .Xr mount 2 .
91 New software should attempt to use
92 .Fn mountctl
93 before using the old
94 .Xr mount 2
95 method.
96 .It Dv MOUNTCTL_INSTALL_VFS_JOURNAL
97 Install a journal on a mount point.
98 This operation needs a
99 .Vt struct mountctl_install_journal
100 passed in
101 .Fa ctl .
102 The journal file must be specified via
103 .Fa fd .
104 A mount point may have multiple journals attached to it.
105 .It Dv MOUNTCTL_REMOVE_VFS_JOURNAL
106 Disassociate a journal from a mount point.
107 This operation needs a
108 .Vt struct mountctl_remove_journal
109 passed in
110 .Fa ctl .
111 .It Dv MOUNTCTL_RESTART_VFS_JOURNAL
112 Restart a journal with a new descriptor.
113 This operation needs a
114 .Vt struct mountctl_restart_journal
115 passed in
116 .Fa ctl .
117 The journal file must be specified via
118 .Fa fd .
119 .It Dv MOUNTCTL_STATUS_VFS_JOURNAL
120 Return a journal's status.
121 This operation needs a
122 .Vt struct mountctl_status_journal
123 passed in
124 .Fa ctl
125 and an array of
126 .Vt struct mountctl_journal_ret_status
127 in
128 .Fa buf .
129 .It Dv MOUNTCTL_MOUNTFLAGS
130 It will store a comma separated string buffer in the
131 .Fa buf
132 parameter with the name list of the currently set
133 user mount flags. The
134 .Fa buf
135 will be sized at most
136 .Fa buflen
137 bytes.
138 .\" XXX Not yet implemented:
139 .\".It Dv MOUNTCTL_INSTALL_BLK_JOURNAL
140 .\".It Dv MOUNTCTL_REMOVE_BLK_JOURNAL
141 .\".It Dv MOUNTCTL_RESYNC_BLK_JOURNAL
142 .\".It Dv MOUNTCTL_RESYNC_VFS_JOURNAL
143 .\".It Dv MOUNTCTL_STATUS_BLK_JOURNAL
144 .El
145 .Sh RETURN VALUES
146 Upon successful completion, the number
147 of copied bytes is returned; otherwise
148 the value -1 is returned and the
149 global variable
150 .Va errno
151 is set to indicate the error.
152 .Sh ERRORS
153 The
154 .Fn mountctl
155 function will fail when one of the following occurs:
156 .Bl -tag -width Er
157 .It Bq Er EBADF
158 .Fa \&Fd
159 is not an active descriptor.
160 .It Bq Er EINVAL
161 The specified
162 .Fa ctllen
163 is not 0-1024,
164 .Fa buflen
165 is not 0-16384, or
166 .Fa path
167 is
168 .Dv NULL .
169 .It Bq Er EPERM
170 The caller is not the super-user.
171 .El
172 .Sh SEE ALSO
173 .Xr mount 2 ,
174 .Xr mountctl 8
175 .Sh HISTORY
176 The
177 .Fn mountctl
178 system call first appeared in
179 .Dx 1.1 .
180 .Sh AUTHORS
181 .An -nosplit
182 The
183 .Fn mountctl
184 system call was written by
185 .An Matthew Dillon
186 and this manual page was written by
187 .An Sascha Wildner .