lib/libutil/login_times.3

   1 .\" Copyright (c) 1995 David Nugent <davidn@blaze.net.au>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, is permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice immediately at the beginning of the file, without modification,
   9 .\"    this list of conditions, and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. This work was done expressly for inclusion into FreeBSD.  Other use
  14 .\"    is permitted provided this notation is included.
  15 .\" 4. Absolutely no warranty of function or purpose is made by the author
  16 .\"    David Nugent.
  17 .\" 5. Modifications may be freely made to this file providing the above
  18 .\"    conditions are met.
  19 .\"
  20 .\" $FreeBSD: src/lib/libutil/login_times.3,v 1.16 2008/10/20 17:17:58 des Exp $
  21 .\"
  22 .Dd October 29, 2008
  23 .Dt LOGIN_TIMES 3
  24 .Os
  25 .Sh NAME
  26 .Nm parse_lt ,
  27 .Nm in_lt ,
  28 .Nm in_ltm ,
  29 .Nm in_ltms ,
  30 .Nm in_lts
  31 .Nd functions for parsing and checking login time periods
  32 .Sh LIBRARY
  33 .Lb libutil
  34 .Sh SYNOPSIS
  35 .In sys/types.h
  36 .In time.h
  37 .In login_cap.h
  38 .Ft login_time_t
  39 .Fn parse_lt "const char *str"
  40 .Ft int
  41 .Fn in_lt "const login_time_t *lt" "time_t *ends"
  42 .Ft int
  43 .Fn in_ltm "const login_time_t *lt" "struct tm *t" "time_t *ends"
  44 .Ft int
  45 .Fn in_ltms "const login_time_t *lt" "struct tm *t" "time_t *ends"
  46 .Ft int
  47 .Fn in_lts "const login_time_t *lt" "time_t *ends"
  48 .Sh DESCRIPTION
  49 This set of functions may be used for parsing and checking login and
  50 session times against a predefined list of allowed login times as
  51 used in
  52 .Xr login.conf 5 .
  53 .Pp
  54 The format of allowed and disallowed session times specified in the
  55 .Ar times.allow
  56 and
  57 .Ar times.deny
  58 capability fields in a login class are comprised of a prefix which
  59 specifies one or more 2- or 3-character day codes, followed by
  60 a start and end time in 24 hour format separated by a hyphen.
  61 Day codes may be concatenated together to select specific days, or
  62 the special mnemonics "Any" and "All" (for any/all days of the week),
  63 "Wk" for any day of the week (excluding Saturdays and Sundays) and
  64 "Wd" for any weekend day may be used.
  65 .Pp
  66 For example, the following time period:
  67 .Dl MoThFrSa1400-2200
  68 is interpreted as Monday, Thursday through Saturday between the hours
  69 of 2pm and 10pm.
  70 .Dl Wd0600-1800
  71 means Saturday and Sunday, between the hours of 6am through 6pm, and
  72 .Dl Any0400-1600
  73 means any day of the week, between 4am and 4pm.
  74 .Pp
  75 Note that all time periods reference system local time.
  76 .Pp
  77 The
  78 .Fn parse_lt
  79 function converts the ASCII representation of a time period into
  80 a structure of type
  81 .Ft login_time_t .
  82 This is defined as:
  83 .Bd -literal
  84 typedef struct login_time
  85 {
  86   u_short       lt_start;   /* Start time */
  87   u_short       lt_end;     /* End time */
  88   u_char        lt_dow;     /* Days of week */
  89 } login_time_t;
  90 .Ed
  91 .Pp
  92 The
  93 .Ar lt_start
  94 and
  95 .Ar lt_end
  96 fields contain the number of minutes past midnight at which the
  97 described period begins and ends.
  98 The
  99 .Ar lt_dow
 100 field is a bit field, containing one bit for each day of the week
 101 and one bit unused.
 102 A series
 103 .Em LTM_*
 104 macros may be used for testing bits individually and in combination.
 105 If no bits are set in this field - i.e., it contains the value
 106 .Em LTM_NONE
 107 - then the entire period is assumed invalid.
 108 This is used as a convention to mark the termination of an array
 109 of login_time_t values.
 110 If
 111 .Fn parse_lt
 112 returns a
 113 .Ar login_time_t
 114 with
 115 .Ar lt_dow
 116 equal to
 117 .Em LTM_NONE
 118 then a parsing error was encountered.
 119 .Pp
 120 The remaining functions provide the ability to test a given time_t or
 121 struct tm value against a specific time period or array of time
 122 periods.
 123 The
 124 .Fn in_ltm
 125 function determines whether the given time described by the struct tm
 126 passed as the second parameter falls within the period described
 127 by the first parameter.
 128 A boolean value is returned, indicating whether or not the time
 129 specified falls within the period.
 130 If the time does fall within the time period, and the third
 131 parameter to the function is not NULL, the time at which the
 132 period ends relative to the time passed is returned.
 133 .Pp
 134 The
 135 .Fn in_ltms
 136 function is similar to
 137 .Fn in_ltm
 138 except that the first parameter must be a pointer to an array
 139 of login_time_t objects, which is up to LC_MAXTIMES (64)
 140 elements in length, and terminated by an element with its
 141 .Ar lt_dow
 142 field set to
 143 .Em LTM_NONE .
 144 .Pp
 145 The
 146 .Fn in_lt
 147 and
 148 .Fn in_lts
 149 functions are equivalent to
 150 .Fn in_ltm
 151 and
 152 .Fn in_ltms ,
 153 respectively, with the second argument set to the current time as
 154 returned by
 155 .Xr localtime 3 .
 156 .Sh RETURN VALUES
 157 The
 158 .Fn parse_lt
 159 function returns a filled in structure of type login_time_t containing the
 160 parsed time period.
 161 If a parsing error occurs, the lt_dow field is set to
 162 .Em LTM_NONE
 163 (i.e., 0).
 164 .Pp
 165 The
 166 .Fn in_ltm
 167 function returns non-zero if the given time falls within the period described
 168 by the login_time_t passed as the first parameter.
 169 .Pp
 170 The
 171 .Fn in_ltms
 172 function returns the index of the first time period found in which the given
 173 time falls, or -1 if none of them apply.
 174 .Sh SEE ALSO
 175 .Xr getcap 3 ,
 176 .Xr login_cap 3 ,
 177 .Xr login_class 3 ,
 178 .Xr login.conf 5 ,
 179 .Xr termcap 5