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