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