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