diff options
Diffstat (limited to 'static/freebsd/man3/login_times.3')
| -rw-r--r-- | static/freebsd/man3/login_times.3 | 187 |
1 files changed, 187 insertions, 0 deletions
diff --git a/static/freebsd/man3/login_times.3 b/static/freebsd/man3/login_times.3 new file mode 100644 index 00000000..18c2cda6 --- /dev/null +++ b/static/freebsd/man3/login_times.3 @@ -0,0 +1,187 @@ +.\" Copyright (c) 1995 David Nugent <davidn@blaze.net.au> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, is permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice immediately at the beginning of the file, without modification, +.\" this list of conditions, and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. This work was done expressly for inclusion into FreeBSD. Other use +.\" is permitted provided this notation is included. +.\" 4. Absolutely no warranty of function or purpose is made by the author +.\" David Nugent. +.\" 5. Modifications may be freely made to this file providing the above +.\" conditions are met. +.\" +.Dd May 10, 2020 +.Dt LOGIN_TIMES 3 +.Os +.Sh NAME +.Nm parse_lt , +.Nm in_lt , +.Nm in_ltm , +.Nm in_ltms , +.Nm in_lts +.Nd functions for parsing and checking login time periods +.Sh LIBRARY +.Lb libutil +.Sh SYNOPSIS +.In sys/types.h +.In time.h +.In login_cap.h +.Ft login_time_t +.Fn parse_lt "const char *str" +.Ft int +.Fn in_lt "const login_time_t *lt" "time_t *ends" +.Ft int +.Fn in_ltm "const login_time_t *lt" "struct tm *t" "time_t *ends" +.Ft int +.Fn in_ltms "const login_time_t *lt" "struct tm *t" "time_t *ends" +.Ft int +.Fn in_lts "const login_time_t *lt" "time_t *ends" +.Sh DESCRIPTION +This set of functions may be used for parsing and checking login and +session times against a predefined list of allowed login times as +used in +.Xr login.conf 5 . +.Pp +The format of allowed and disallowed session times specified in the +.Ar times.allow +and +.Ar times.deny +capability fields in a login class are comprised of a prefix which +specifies one or more 2- or 3-character day codes, followed by +a start and end time in 24 hour format separated by a hyphen. +Day codes may be concatenated together to select specific days, or +the special mnemonics "Any" and "All" (for any/all days of the week), +"Wk" for any day of the week (excluding Saturdays and Sundays) and +"Wd" for any weekend day may be used. +.Pp +For example, the following time period: +.Dl MoThFrSa1400-2200 +is interpreted as Monday, Thursday through Saturday between the hours +of 2pm and 10pm. +.Dl Wd0600-1800 +means Saturday and Sunday, between the hours of 6am through 6pm, and +.Dl Any0400-1600 +means any day of the week, between 4am and 4pm. +.Pp +Note that all time periods reference system local time. +.Pp +The +.Fn parse_lt +function converts the ASCII representation of a time period into +a structure of type +.Ft login_time_t . +This is defined as: +.Bd -literal +typedef struct login_time +{ + u_short lt_start; /* Start time */ + u_short lt_end; /* End time */ + u_char lt_dow; /* Days of week */ +} login_time_t; +.Ed +.Pp +The +.Ar lt_start +and +.Ar lt_end +fields contain the number of minutes past midnight at which the +described period begins and ends. +The +.Ar lt_dow +field is a bit field, containing one bit for each day of the week +and one bit unused. +A series +.Em LTM_* +macros may be used for testing bits individually and in combination. +If no bits are set in this field - i.e., it contains the value +.Em LTM_NONE +- then the entire period is assumed invalid. +This is used as a convention to mark the termination of an array +of login_time_t values. +If +.Fn parse_lt +returns a +.Ar login_time_t +with +.Ar lt_dow +equal to +.Em LTM_NONE +then a parsing error was encountered. +.Pp +The remaining functions provide the ability to test a given time_t or +struct tm value against a specific time period or array of time +periods. +The +.Fn in_ltm +function determines whether the given time described by the struct tm +passed as the second parameter falls within the period described +by the first parameter. +A boolean value is returned, indicating whether or not the time +specified falls within the period. +If the time does fall within the time period, and the third +parameter to the function is not NULL, the time at which the +period ends relative to the time passed is returned. +.Pp +The +.Fn in_ltms +function is similar to +.Fn in_ltm +except that the first parameter must be a pointer to an array +of login_time_t objects, which is up to LC_MAXTIMES (64) +elements in length, and terminated by an element with its +.Ar lt_dow +field set to +.Em LTM_NONE . +.Pp +The +.Fn in_lt +and +.Fn in_lts +functions are equivalent to +.Fn in_ltm +and +.Fn in_ltms , +respectively, with the second argument set to the current time as +returned by +.Xr localtime 3 . +.Sh RETURN VALUES +The +.Fn parse_lt +function returns a filled in structure of type login_time_t containing the +parsed time period. +If a parsing error occurs, the lt_dow field is set to +.Em LTM_NONE +(i.e., 0). +.Pp +The +.Fn in_ltm +function returns non-zero if the given time falls within the period described +by the login_time_t passed as the first parameter. +.Pp +The +.Fn in_ltms +function returns the index of the first time period found in which the given +time falls, or -1 if none of them apply. +.Sh SEE ALSO +.Xr getcap 3 , +.Xr login_cap 3 , +.Xr login_class 3 , +.Xr login.conf 5 , +.Xr termcap 5 +.Sh HISTORY +The functions +.Fn parse_lt , +.Fn in_lt , +.Fn in_ltm , +.Fn in_ltms +and +.Fn in_lts +first appeared in +.Fx 2.1.5 . |