Correct RETURN VALUES in mountctl(2)
[dragonfly.git] / lib / libc / sys / mountctl.2
CommitLineData
c27eed25
SW
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.\"
a8ac7a04 32.\" $DragonFly: src/lib/libc/sys/mountctl.2,v 1.3 2008/02/10 23:35:30 swildner Exp $
c27eed25 33.\"
0b3a1c24 34.Dd July 21, 2009
c27eed25
SW
35.Os
36.Dt MOUNTCTL 2
37.Sh NAME
38.Nm mountctl
39.Nd execute a mount control operation
40.Sh LIBRARY
41.Lb libc
42.Sh SYNOPSIS
a8ac7a04 43.In sys/mountctl.h
c27eed25
SW
44.Ft int
45.Fo mountctl
46.Fa "const char *path"
47.Fa "int op"
48.Fa "int fd"
49.Fa "void *ctl"
50.Fa "int ctllen"
51.Fa "void *buf"
52.Fa "int buflen"
53.Fc
54.Sh DESCRIPTION
55The
56.Fn mountctl
57system call executes the mount control operation
58.Fa op
59on the mount point
60.Fa path .
61An optional file descriptor
62.Fa fd
63can be passed, or set to -1 if unneeded.
64The
65.Fa ctl
66argument is for passing operation specific data and usually points to
67some struct (see
68.Sx CONTROL OPERATIONS
69for further information).
70The data's size is specified by
71.Fa ctllen .
72The
73.Fa buf
74and
75.Fa buflen
76arguments are used if the operation needs to return data to the caller
77or set to
78.Dv NULL
79and 0 if unused.
80.Sh CONTROL OPERATIONS
81The following operations are defined in
a8ac7a04 82.In sys/mountctl.h :
c27eed25
SW
83.Bl -tag -width indent
84.It Dv MOUNTCTL_SET_EXPORT
85Set export control of a filesystem.
86This operation needs a
87.Vt struct export_args
88passed in
89.Fa ctl .
90Note that export control for numerous filesystems may still only be settable
91with
92.Xr mount 2 .
93New software should attempt to use
94.Fn mountctl
95before using the old
96.Xr mount 2
97method.
98.It Dv MOUNTCTL_INSTALL_VFS_JOURNAL
99Install a journal on a mount point.
100This operation needs a
101.Vt struct mountctl_install_journal
102passed in
103.Fa ctl .
104The journal file must be specified via
105.Fa fd .
106A mount point may have multiple journals attached to it.
107.It Dv MOUNTCTL_REMOVE_VFS_JOURNAL
108Disassociate a journal from a mount point.
109This operation needs a
110.Vt struct mountctl_remove_journal
111passed in
112.Fa ctl .
113.It Dv MOUNTCTL_RESTART_VFS_JOURNAL
114Restart a journal with a new descriptor.
115This operation needs a
116.Vt struct mountctl_restart_journal
117passed in
118.Fa ctl .
119The journal file must be specified via
120.Fa fd .
121.It Dv MOUNTCTL_STATUS_VFS_JOURNAL
122Return a journal's status.
123This operation needs a
124.Vt struct mountctl_status_journal
125passed in
126.Fa ctl
127and an array of
128.Vt struct mountctl_journal_ret_status
129in
130.Fa buf .
131.\" XXX Not yet implemented:
132.\".It Dv MOUNTCTL_INSTALL_BLK_JOURNAL
133.\".It Dv MOUNTCTL_REMOVE_BLK_JOURNAL
134.\".It Dv MOUNTCTL_RESYNC_BLK_JOURNAL
135.\".It Dv MOUNTCTL_RESYNC_VFS_JOURNAL
136.\".It Dv MOUNTCTL_STATUS_BLK_JOURNAL
137.El
138.Sh RETURN VALUES
0b3a1c24
AH
139Upon successful completion, the number
140of copied bytes is returned; otherwise
141the value -1 is returned and the
142global variable
143.Va errno
144is set to indicate the error.
c27eed25
SW
145.Sh ERRORS
146The
147.Fn mountctl
148function will fail when one of the following occurs:
149.Bl -tag -width Er
150.It Bq Er EBADF
151.Fa \&Fd
152is not an active descriptor.
153.It Bq Er EINVAL
154The specified
155.Fa ctllen
156is not 0-1024,
157.Fa buflen
158is not 0-16384, or
159.Fa path
160is
161.Dv NULL .
162.It Bq Er EPERM
163The caller is not the super-user.
164.El
165.Sh SEE ALSO
166.Xr mount 2 ,
167.Xr mountctl 8
168.Sh HISTORY
169The
170.Fn mountctl
171system call first appeared in
172.Dx 1.1 .
173.Sh AUTHORS
eb73b953 174.An -nosplit
c27eed25
SW
175The
176.Fn mountctl
177system call was written by
178.An Matthew Dillon
179and this manual page was written by
180.An Sascha Wildner .