# OsLib (Luaj API)
Date: 2015-04-29

## org.luaj.vm2.lib
Class OsLib

    java.lang.Object
      org.luaj.vm2.Varargs
          org.luaj.vm2.LuaValue
              org.luaj.vm2.LuaFunction
                  org.luaj.vm2.lib.LibFunction
                      org.luaj.vm2.lib.TwoArgFunction
                          org.luaj.vm2.lib.OsLib

Direct Known Subclasses:
  JseOsLib

    public class OsLib

extends TwoArgFunction

Subclass of `LibFunction` which implements the standard lua `os` library.

It is a usable base with simplified stub functions for library functions that cannot be implemented uniformly on Jse and Jme.

This can be installed as-is on either platform, or extended and refined to be used in a complete Jse implementation.

Because the nature of the `os` library is to encapsulate os-specific features, the behavior of these functions varies considerably from their counterparts in the C platform.

The following functions have limited implementations of features that are not supported well on Jme:

- `execute()`
- `remove()`
- `rename()`
- `tmpname()`

Typically, this library is included as part of a call to either `JsePlatform.standardGlobals()` or `JmePlatform.standardGlobals()`

     Globals globals = JsePlatform.standardGlobals();
     System.out.println( globals.get("os").get("time").call() );

In this example the platform-specific `JseOsLib` library will be loaded, which will include the base functionality provided by this class.

To instantiate and use it directly, link it into your globals table via `LuaValue.load(LuaValue)` using code such as:

     Globals globals = new Globals();
     globals.load(new JseBaseLib());
     globals.load(new PackageLib());
     globals.load(new OsLib());
     System.out.println( globals.get("os").get("time").call() );

See Also:
  `LibFunction`, `JseOsLib`, `JsePlatform`, `JmePlatform`, http://www.lua.org/manual/5.1/manual.html#5.8

Field Summary
`protected Globals` `globals`
`static java.lang.String` `TMP_PREFIX`
`static java.lang.String` `TMP_SUFFIX`

Fields inherited from class org.luaj.vm2.lib.LibFunction
`name, opcode`

Fields inherited from class org.luaj.vm2.LuaFunction
`s_metatable`

Fields inherited from class org.luaj.vm2.LuaValue
`ADD, CALL, CONCAT, DIV, EMPTYSTRING, ENV, EQ, FALSE, INDEX, LE, LEN, LT, METATABLE, MINUSONE, MOD, MODE, MUL, NEWINDEX, NIL, NILS, NONE, NOVALS, ONE, POW, SUB, TBOOLEAN, TFUNCTION, TINT, TLIGHTUSERDATA, TNIL, TNONE, TNUMBER, TOSTRING, TRUE, TSTRING, TTABLE, TTHREAD, TUSERDATA, TVALUE, TYPE_NAMES, UNM, ZERO`

Constructor Summary
`OsLib()` Create and OsLib instance.

Method Summary
`LuaValue` `call(LuaValue modname, LuaValue env)` Perform one-time initialization on the library by creating a table containing the library functions, adding that table to the supplied environment, adding the table to package.loaded, and returning table as the return value.
`protected double` `clock()`
`java.lang.String` `date(java.lang.String format, double time)` If the time argument is present, this is the time to be formatted (see the os.time function for a description of this value).
`protected double` `difftime(double t2, double t1)` Returns the number of seconds from time t1 to time t2.
`protected Varargs` `execute(java.lang.String command)` This function is equivalent to the C function system.
`protected void` `exit(int code)` Calls the C function exit, with an optional code, to terminate the host program.
`protected java.lang.String` `getenv(java.lang.String varname)` Returns the value of the process environment variable varname, or the System property value for varname, or null if the variable is not defined in either environment.
`protected void` `remove(java.lang.String filename)` Deletes the file or directory with the given name.
`protected void` `rename(java.lang.String oldname, java.lang.String newname)` Renames file or directory named oldname to newname.
`protected java.lang.String` `setlocale(java.lang.String locale, java.lang.String category)` Sets the current locale of the program.
`protected double` `time(LuaTable table)` Returns the current time when called without arguments, or a time representing the date and time specified by the given table.
`protected java.lang.String` `tmpname()` Returns a string with a file name that can be used for a temporary file.

Methods inherited from class org.luaj.vm2.lib.TwoArgFunction
`call, call, call, invoke`

Methods inherited from class org.luaj.vm2.lib.LibFunction
`bind, bind, call, newupe, newupl, newupn, tojstring`

Methods inherited from class org.luaj.vm2.LuaFunction
`checkfunction, classnamestub, getmetatable, isfunction, name, optfunction, strvalue, type, typename`

Methods inherited from class org.luaj.vm2.LuaValue

`add, add, add, and, arg, arg1, argerror, argerror, aritherror, aritherror, arithmt, arithmtwith, assert_, buffer, call, callmt, checkboolean, checkclosure, checkdouble, checkglobals, checkint, checkinteger, checkjstring, checklong, checkmetatag, checknotnil, checknumber, checknumber, checkstring, checktable, checkthread, checkuserdata, checkuserdata, compareerror, compareerror, comparemt, concat, concat, concatmt, concatTo, concatTo, concatTo, div, div, div, divInto, eq_b, eq, eqmtcall, equals, error, get, get, get, gettable, gt_b, gt_b, gt_b, gt, gt, gt, gteq_b, gteq_b, gteq_b, gteq, gteq, gteq, illegal, inext, initupvalue1, invoke, invoke, invoke, invoke, invoke, invokemethod, invokemethod, invokemethod, invokemethod, invokemethod, invokemethod, isboolean, isclosure, isint, isinttype, islong, isnil, isnumber, isstring, istable, isthread, isuserdata, isuserdata, isvalidkey, len, lenerror, length, listOf, listOf, load, lt_b, lt_b, lt_b, lt, lt, lt, lteq_b, lteq_b, lteq_b, lteq, lteq, lteq, metatableOf, metatag, method, method, method, method, method, method, mod, mod, mod, modFrom, mul, mul, mul, narg, neg, neq_b, neq, next, not, onInvoke, optboolean, optclosure, optdouble, optint, optinteger, optjstring, optlong, optnumber, optstring, opttable, optthread, optuserdata, optuserdata, optvalue, or, pow, pow, pow, powWith, powWith, presize, raweq, raweq, raweq, raweq, raweq, rawget, rawget, rawget, rawlen, rawset, rawset, rawset, rawset, rawset, rawset, rawset, rawsetlist, set, set, set, set, set, set, set, setmetatable, settable, strcmp, strcmp, strongvalue, sub, sub, sub, subargs, subFrom, subFrom, tableOf, tableOf, tableOf, tableOf, tableOf, tableOf, tailcallOf, testfor_b, toboolean, tobyte, tochar, todouble, tofloat, toint, tolong, tonumber, toshort, tostring, toString, touserdata, touserdata, typerror, unimplemented, userdataOf, userdataOf, valueOf, valueOf, valueOf, valueOf, valueOf, valueOf, varargsOf, varargsOf, varargsOf, varargsOf, varargsOf, varargsOf`

Methods inherited from class org.luaj.vm2.Varargs

`argcheck, checkboolean, checkclosure, checkdouble, checkfunction, checkint, checkinteger, checkjstring, checklong, checknotnil, checknumber, checkstring, checktable, checkthread, checkuserdata, checkuserdata, checkvalue, eval, isfunction, isnil, isnoneornil, isnumber, isstring, istable, isTailcall, isthread, isuserdata, isvalue, optboolean, optclosure, optdouble, optfunction, optint, optinteger, optjstring, optlong, optnumber, optstring, opttable, optthread, optuserdata, optuserdata, optvalue, toboolean, tobyte, tochar, todouble, tofloat, toint, tojstring, tolong, toshort, touserdata, touserdata, type`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### TMP_PREFIX

    public static java.lang.String TMP_PREFIX

### TMP_SUFFIX

    public static java.lang.String TMP_SUFFIX

### globals

    protected Globals globals

Constructor Detail

### OsLib

    public OsLib()

  Create and OsLib instance.

Method Detail

### call

    public LuaValue call(LuaValue modname,
                         LuaValue env)

  Perform one-time initialization on the library by creating a table containing the library functions, adding that table to the supplied environment, adding the table to package.loaded, and returning table as the return value.

  Specified by:
    `call` in class `TwoArgFunction`
  Parameters:
    `modname` - the module name supplied if this is loaded via 'require'.
    `env` - the environment to load into, typically a Globals instance.
  Returns:
    First return value `(this(arg1,arg2))`, or `LuaValue.NIL` if there were none.
  See Also:
    `LuaValue.call()`, `LuaValue.call(LuaValue)`, `LuaValue.call(LuaValue, LuaValue, LuaValue)`, `LuaValue.invoke(LuaValue, Varargs)`, `LuaValue.method(String,LuaValue,LuaValue)`, `LuaValue.method(LuaValue,LuaValue,LuaValue)`

### clock

    protected double clock()

  Returns:
    an approximation of the amount in seconds of CPU time used by the program. For luaj this simple returns the elapsed time since the OsLib class was loaded.

### difftime

    protected double difftime(double t2,
                              double t1)

  Returns the number of seconds from time t1 to time t2. In POSIX, Windows, and some other systems, this value is exactly t2-t1.

  Parameters:
    `t2` -
    `t1` -
  Returns:
    diffeence in time values, in seconds

### date

    public java.lang.String date(java.lang.String format,
                                 double time)

  If the time argument is present, this is the time to be formatted (see the os.time function for a description of this value). Otherwise, date formats the current time. Date returns the date as a string, formatted according to the same rules as ANSII strftime, but without support for %g, %G, or %V. When called without arguments, date returns a reasonable date and time representation that depends on the host system and on the current locale (that is, os.date() is equivalent to os.date("%c")).

  Parameters:
    `format` -
    `time` - time since epoch, or -1 if not supplied
  Returns:
    a LString or a LTable containing date and time, formatted according to the given string format.

### execute

    protected Varargs execute(java.lang.String command)

  This function is equivalent to the C function system. It passes command to be executed by an operating system shell. It returns a status code, which is system-dependent. If command is absent, then it returns nonzero if a shell is available and zero otherwise.

  Parameters:
    `command` - command to pass to the system

### exit

    protected void exit(int code)

  Calls the C function exit, with an optional code, to terminate the host program.

  Parameters:
    `code` -

### getenv

    protected java.lang.String getenv(java.lang.String varname)

  Returns the value of the process environment variable varname, or the System property value for varname, or null if the variable is not defined in either environment. The default implementation, which is used by the JmePlatform, only queryies System.getProperty(). The JsePlatform overrides this behavior and returns the environment variable value using System.getenv() if it exists, or the System property value if it does not. A SecurityException may be thrown if access is not allowed for 'varname'.

  Parameters:
    `varname` -
  Returns:
    String value, or null if not defined

### remove

    protected void remove(java.lang.String filename)
                   throws java.io.IOException

  Deletes the file or directory with the given name. Directories must be empty to be removed. If this function fails, it throws and IOException

  Parameters:
    `filename` -
  Throws:
    `java.io.IOException` - if it fails

### rename

    protected void rename(java.lang.String oldname,
                          java.lang.String newname)
                   throws java.io.IOException

  Renames file or directory named oldname to newname. If this function fails,it throws and IOException

  Parameters:
    `oldname` - old file name
    `newname` - new file name
  Throws:
    `java.io.IOException` - if it fails

### setlocale

    protected java.lang.String setlocale(java.lang.String locale,
                                         java.lang.String category)

  Sets the current locale of the program. locale is a string specifying a locale; category is an optional string describing which category to change: "all", "collate", "ctype", "monetary", "numeric", or "time"; the default category is "all". If locale is the empty string, the current locale is set to an implementation- defined native locale. If locale is the string "C", the current locale is set to the standard C locale. When called with null as the first argument, this function only returns the name of the current locale for the given category.

  Parameters:
    `locale` -
    `category` -
  Returns:
    the name of the new locale, or null if the request cannot be honored.

### time

    protected double time(LuaTable 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 fields year, month, and day, and may have fields hour, min, sec, and isdst (for a description of these fields, see the os.date function).

  Parameters:
    `table` -
  Returns:
    long value for the time

### tmpname

    protected java.lang.String tmpname()

  Returns a string with a file name that can be used for a temporary file. The file must be explicitly opened before its use and explicitly removed when no longer needed. On some systems (POSIX), this function also creates a file with that name, to avoid security risks. (Someone else might create the file with wrong permissions in the time between getting the name and creating the file.) You still have to open the file to use it and to remove it (even if you do not use it).

  Returns:
    String filename to use

Copyright © 2007-2015 Luaj.org. All Rights Reserved.