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 49This set of functions may be used for parsing and checking login and 50session times against a predefined list of allowed login times as 51used in 52.Xr login.conf 5 . 53.Pp 54The format of allowed and disallowed session times specified in the 55.Ar times.allow 56and 57.Ar times.deny 58capability fields in a login class are comprised of a prefix which 59specifies one or more 2- or 3-character day codes, followed by 60a start and end time in 24 hour format separated by a hyphen. 61Day codes may be concatenated together to select specific days, or 62the 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 66For example, the following time period: 67.Dl MoThFrSa1400-2200 68is interpreted as Monday, Thursday through Saturday between the hours 69of 2pm and 10pm. 70.Dl Wd0600-1800 71means Saturday and Sunday, between the hours of 6am through 6pm, and 72.Dl Any0400-1600 73means any day of the week, between 4am and 4pm. 74.Pp 75Note that all time periods reference system local time. 76.Pp 77The 78.Fn parse_lt 79function converts the ASCII representation of a time period into 80a structure of type 81.Ft login_time_t . 82This is defined as: 83.Bd -literal 84typedef 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 92The 93.Ar lt_start 94and 95.Ar lt_end 96fields contain the number of minutes past midnight at which the 97described period begins and ends. 98The 99.Ar lt_dow 100field is a bit field, containing one bit for each day of the week 101and one bit unused. 102A series 103.Em LTM_* 104macros may be used for testing bits individually and in combination. 105If 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. 108This is used as a convention to mark the termination of an array 109of login_time_t values. 110If 111.Fn parse_lt 112returns a 113.Ar login_time_t 114with 115.Ar lt_dow 116equal to 117.Em LTM_NONE 118then a parsing error was encountered. 119.Pp 120The remaining functions provide the ability to test a given time_t or 121struct tm value against a specific time period or array of time 122periods. 123The 124.Fn in_ltm 125function determines whether the given time described by the struct tm 126passed as the second parameter falls within the period described 127by the first parameter. 128A boolean value is returned, indicating whether or not the time 129specified falls within the period. 130If the time does fall within the time period, and the third 131parameter to the function is not NULL, the time at which the 132period ends relative to the time passed is returned. 133.Pp 134The 135.Fn in_ltms 136function is similar to 137.Fn in_ltm 138except that the first parameter must be a pointer to an array 139of login_time_t objects, which is up to LC_MAXTIMES (64) 140elements in length, and terminated by an element with its 141.Ar lt_dow 142field set to 143.Em LTM_NONE . 144.Pp 145The 146.Fn in_lt 147and 148.Fn in_lts 149functions are equivalent to 150.Fn in_ltm 151and 152.Fn in_ltms , 153respectively, with the second argument set to the current time as 154returned by 155.Xr localtime 3 . 156.Sh RETURN VALUES 157The 158.Fn parse_lt 159function returns a filled in structure of type login_time_t containing the 160parsed time period. 161If a parsing error occurs, the lt_dow field is set to 162.Em LTM_NONE 163(i.e., 0). 164.Pp 165The 166.Fn in_ltm 167function returns non-zero if the given time falls within the period described 168by the login_time_t passed as the first parameter. 169.Pp 170The 171.Fn in_ltms 172function returns the index of the first time period found in which the given 173time 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 180