chapter23 The Operating System Library

The Operating System library includes functions for file (not stream) manipulation,
for getting the current date and time, and other facilities related to the
operating system. It is defined in table os.This library pays a price for Lua
portability: because Lua is written in ANSI C, it uses only the functionality
that the ANSI standard offers. Many OS facilities, such as directory manipulation
and sockets, are not part of this standard; therefore, the system library

does not provide them.

For file manipulation, all that this OS library provides is anos.rename
function, which changes the name of a file; and os.remove, which removes
(deletes) a file.

23.1 Date and Time

Two functions, time and date, provide all date and time functionality in Lua.

The time function, when called without arguments, returns the current date
and time, coded as a number. (In most systems, this number is the number of
seconds (注意是秒数)since some epoch.) When called with a table, it returns the number
representing the date and time described by the table. Such date tables have
the following significant fields:

year       a full year
month    01–12
day        01–31
hour      00–23
min        00–59
sec       00–59
isdst a boolean, true if daylight saving is on

The first three fields are mandatory; the others default to noon (12:00:00) when
not provided. In a UNIX system (where the epoch is 00:00:00 UTC, January 1,
1970) running in Rio de Janeiro (which is three hours west of Greenwich), we
have the following examples:

--> =os.time();
1389753135
--> =os.time();
1389753137
--> =os.time();
1389753138     --这些数字真的是年月日，时分秒吗？ 什么是时间？？2014-01-15 10:33 am,这个是日期时间？ 0000-00-00 00：00 am, 这个是时间的起点？？我们有必要从这个点开始算起嘛，No,Definitely NO. so we choose

a start point, that's when os.time()=0, we represent the start date-time.这个起点应该由系统决定我们改不了了

os.time({table}), 加上table 并不时说当前时间可以让我们来选择到底从哪个点计算起，，，而是这个table 所代表的时间 距离这个start point 一共有多少秒， DateTable-startPont=os.time(DateTable)....不要理解错了， see the Reference

os.time(table)

returns the current time when called without arguments,or

a time representing the date and time specified by the given table.This table must have fieldsyear, month, andday,and may have fieldshour (default is 12),min (default is 0),sec (default is 0),and isdst (default isnil).For a description of these fields, see theos.date function.

The returned value is a number, whose meaning depends on your system.In POSIX, Windows, and some other systems,this number counts the numberof seconds since some given start time (the "epoch").In other systems, the meaning is not specified,and the number returned by time can be used only as an argument toos.date andos.difftime.

书上描述的example should be test in UNIX system.

print(os.time{year=1970, month=1, day=1, hour=0}) --> 10800
print(os.time{year=1970, month=1, day=1, hour=0, sec=1})
--> 10801
print(os.time{year=1970, month=1, day=1}) --> 54000 ，hour default 12

(Note that 10800 are 3 hours in seconds,(which is three hours west of Greenwich,也就是偏离GMT 3 个小时), and 54000 are 10800 plus 12 hours in
seconds.偏离GMT 3 hours +12 hours.)

也就是UNIX system的起点时间是1970-1-1 0：0:0 ,但这个市GMT 时间，也就是如果把Unix机器调时间到1970-1-1 0：0:0, 如果用os.time() 返回就是 10800,3 hours offset GMT.

(但总是觉得还不通，，好像还差什么似的，，，，，，)

---my test in Windows:

startTable1={year=1970, month=1, day=1, hour=0};
startTable2={year=1970, month=1, day=1,hour=12,min=0,sec=0};
startTable3={year=1970, month=1, day=1,hour=12,min=0,sec=1};

startTable4={year=1970, month=1, day=1,hour=11,min=0,sec=0};

print(os.time());
print(os.time(startTable1));
print(os.time(startTable2));
print(os.time(startTable3));

print(os.time(startTable4));

1389757004
nil   --{year=1970, month=1, day=1, hour=0 } hour=0 似乎就不validate 了，，，
14400   --23 minutes
14401

10800  -- 这个跟Unix的结果是一样的!!! ????

The date function, despite its name, is a kind of a reverse of the time function:
it converts a number representing the date and time back to some higher-level
representation. Its first parameter is a format string, describing the representation
we want. The second is the numeric date–time; it defaults to the current
date and time.

To produce a date table, we use the format string“*t”,Not Time Formate pattern. For instance, the call
os.date("*t",906000490) returns the following table:
{year = 1998, month = 9, day = 16, yday = 259, wday = 4,
hour = 23, min = 48, sec = 10, isdst = false}

Notice that, besides the fields used by os.time, the table created by os.date
also gives the day of week (wday, 1 is Sunday) and the day of year (yday, 1 is
January 1st),2 more fields.

For other format strings, os.date formats the date as a string that is a copy
of the format string where specific tags were replaced by information about time
and date. A tag consists of a ‘%’ followed by a letter, as in the next examples:
print(os.date("a %A in %B")) --> a Tuesday in May
print(os.date("%x", 906000490)) --> 09/16/1998,

All representations follow the current locale. For instance, in a locale for Brazil–
Portuguese, %B would result in “setembro” and %x in “16/09/98”.

The following table shows each tag, its meaning, and its value for September
16, 1998 (a Wednesday), at 23:48:10,也就是以这个日期为例子解析，

For numeric values, the table shows  also their range of possible values:

%a abbreviated weekday name (e.g., Wed)
%A full weekday name (e.g., Wednesday)
%b abbreviated month name (e.g., Sep)
%B full month name (e.g., September)
%c date and time (e.g., 09/16/98 23:48:10)
%d day of the month (16) [01–31]
%H hour, using a 24-hour clock (23) [00–23]
%I hour, using a 12-hour clock (11) [01–12]
%j day of the year (259) [001–366]
%M minute (48) [00–59]
%m month (09) [01–12]
%p either “am” or “pm” (pm)
%S second (10) [00–60]
%w weekday (3) [0–6 = Sunday–Saturday]
%x date (e.g., 09/16/98)
%X time (e.g., 23:48:10)
%y two-digit year (98) [00–99]
%Y full year (1998)
%% the character ‘%’

If you call date without any arguments, it uses the %c format, that is, complete
date and time information in a reasonable format. Note that the representations
for %x, %X, and %c change according to the locale and the system. If you
want a fixed representation, such as mm/dd/yyyy, use an explicit format string,
such as “%m/%d/%Y”.

The os.clock function returns the number of seconds(但会精确到millisecond) of CPU time for the
program. Its typical use is to benchmark (基准)  a piece of code:
local x = os.clock()
local s = 0
for i = 1, 100000 do s = s + i end
print(string.format("elapsed time: %.2f\n", os.clock() - x))

23.2 Other System Calls

The os.exit function terminates the execution of a program. Its optional first
argument is the return status of the program. It can be a number (zero means
a successful execution) or a boolean (true means a successful execution). An
optional second argument, if true, closes the Lua state, calling all finalizers and
releasing all memory used by that state,还有Lua state  concept,what's that??.

(Usually this finalization is not necessary, because most operating systems release all resources used by a process
when it exits.)

The os.getenv function gets the value of an environment variable. It takes
the name of the variable and returns a string with its value:
print(os.getenv("HOME")) --> /home/lua

The call returns nil for undefined variables.

Function os.execute runs a system command; it is equivalent tothe system
function in C. It takes a string with the command and returns information
regarding how the command terminated. The first return,返回多个value,not return a table

is a boolean: true   means the program exited with no errors. The second return is a string: “exit”
if the program terminated normally or “signal” if it was interrupted by a signal.
A third return is the return status (if the program terminated normally) or
the number of the signal that terminated the program. As an example of use,
both in UNIX and in Windows you can use the following function to create new
directories:
function createDir (dirname)
os.execute("mkdir " .. dirname)
end
The os.execute function is powerful, but it is also highly system dependent.

The os.setlocale function sets the current locale used by a Lua program.
Locales define behavior that is sensitive to cultural or linguistic differences. The
setlocale function has two string parameters: the locale name and a category
that specifies what features the locale will affect. There are six categories of
locales:

“collate” controls the alphabetic order of strings;
“ctype” controls the types of individual characters (e.g., what is a letter) and
the conversion between lower and upper cases;
“monetary” has no influence in Lua programs;
“numeric” controls how numbers are formatted;
“time” controls how date and time are formatted (i.e., function os.date);
“all” controls all the above functions.

The default category is “all”, so that if you call setlocale with only the locale
name it will set all categories. The setlocale function returns the locale name
or nil if it fails (usually because the system does not support the given locale).
print(os.setlocale("ISO-8859-1", "collate")) --> ISO-8859-1

The category “numeric” is a little tricky. As Portuguese and other Latin
languages use a comma instead of a point to represent decimal numbers, the
locale changes the way Lua prints and reads these numbers. But the locale does
not change the way that Lua parses numbers in programs (among other reasons
because expressions like print(3,4) already have a meaning in Lua). If you are
using Lua to create pieces of Lua code, you may have problems here:
print(os.setlocale("pt_BR")) --> pt_BR
s = "return (" .. 3.4 .. ")"
print(s) --> return (3,4)
print(loadstring(s))
--> nil [string "return (3,4)"]:1: ')' expected near ','

To avoid those problems, make sure that your program is using the standard “C”
locale when creating pieces of code.