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