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 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 .