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