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