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