share/man/man4/clockctl.4

   1 .\"     $NetBSD: clockctl.4,v 1.6 2009/02/19 03:18:19 enami Exp $
   2 .\"
   3 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Emmanuel Dreyfus.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd February 19, 2009
  31 .Dt CLOCKCTL 4
  32 .Os
  33 .Sh NAME
  34 .Nm clockctl
  35 .Nd Clock subsystem user control
  36 .Sh SYNOPSIS
  37 .Cd pseudo-device clockctl
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 interface brings clock control to non-root users.
  42 Any user with write access to
  43 .Pa /dev/clockctl
  44 will be able to perform operations such as
  45 .Xr settimeofday 2 ,
  46 .Xr clock_settime 2 ,
  47 .Xr adjtime 2 ,
  48 or
  49 .Xr ntp_adjtime 2 ,
  50 which are normally restricted to the super-user.
  51 Using the
  52 .Nm
  53 pseudo-device, it is possible to run daemons such as
  54 .Xr ntpd 8
  55 as non-privileged users, thus reducing the security exposure if a
  56 compromise is found in such a daemon.
  57 .Pp
  58 The
  59 .Nm
  60 pseudo-device driver provides an
  61 .Xr ioctl 2
  62 call for each privileged clock-related system call.
  63 The system call stubs in C library will use the
  64 .Xr ioctl 2
  65 on
  66 .Pa /dev/clockctl
  67 if the special file is present and accessible, or will revert to the
  68 plain super-user-restricted system call if the special file is not accessible.
  69 .Pp
  70 The following
  71 .Xr ioctl 2
  72 calls are defined in
  73 .Aq Pa sys/clockctl.h :
  74 .Bl -tag -width CLOCKCTL
  75 .It Dv CLOCKCTL_SETTIMEOFDAY
  76 This will run the
  77 .Xr settimeofday 2
  78 system call.
  79 Argument should be a pointer to a
  80 .Va struct clockctl_settimeofday :
  81 .Bd -literal
  82 struct clockctl_settimeofday {
  83         const struct timeval *tv;
  84         const void *tzp;
  85 };
  86 .Ed
  87 .It Dv CLOCKCTL_CLOCK_SETTIME
  88 This will run the
  89 .Xr clock_settime 2
  90 system call.
  91 Argument should be a pointer to a
  92 .Va struct clockctl_clock_settime :
  93 .Bd -literal
  94 struct clockctl_clock_settime {
  95         clockid_t clock_id;
  96         struct timespec *tp;
  97 };
  98 .Ed
  99 .It Dv CLOCKCTL_ADJTIME
 100 This will run the
 101 .Xr adjtime 2
 102 system call.
 103 Argument should be a pointer to a
 104 .Va struct clockctl_adjtime :
 105 .Bd -literal
 106 struct clockctl_adjtime {
 107         const struct timeval *delta;
 108         struct timeval *olddelta;
 109 };
 110 .Ed
 111 .It Dv CLOCKCTL_NTP_ADJTIME
 112 This will run the
 113 .Xr ntp_adjtime 2
 114 system call.
 115 Argument should be a pointer to a
 116 .Va struct clockctl_ntp_adjtime :
 117 .Bd -literal
 118 struct clockctl_ntp_adjtime {
 119         struct timex *tp;
 120 .\" Following member is commented out intentionally.
 121 .\"     register_t retval;
 122 };
 123 .Ed
 124 .El
 125 .Sh SEE ALSO
 126 .Xr adjtime 2 ,
 127 .Xr clock_settime 2 ,
 128 .Xr ioctl 2 ,
 129 .Xr settimeofday 2
 130 .Sh HISTORY
 131 .Nm
 132 appeared in
 133 .Nx 1.6 .