From 8a7805ad452028118c0dea6d754a522003ea0d63 Mon Sep 17 00:00:00 2001
From: ocelot-inc <pgulutzan@ocelot.ca>
Date: Sun, 24 Apr 2016 12:35:25 -0600
Subject: [PATCH] os.rst
---
doc/sphinx/book/app/c-lua_tutorial.rst | 2 +-
doc/sphinx/book/app/d-plugins.rst | 4 +-
.../book/user_guide_getting_started.rst | 2 +-
doc/sphinx/reference/clock.rst | 3 +-
doc/sphinx/reference/index.rst | 1 +
doc/sphinx/reference/os.rst | 143 ++++++++++++++++++
6 files changed, 149 insertions(+), 6 deletions(-)
create mode 100644 doc/sphinx/reference/os.rst
diff --git a/doc/sphinx/book/app/c-lua_tutorial.rst b/doc/sphinx/book/app/c-lua_tutorial.rst
index 6e95ecc788..d37c605938 100644
--- a/doc/sphinx/book/app/c-lua_tutorial.rst
+++ b/doc/sphinx/book/app/c-lua_tutorial.rst
@@ -374,7 +374,7 @@ wrinkle that we add here is a timing function.
end_time = os.clock()
'insert done in ' .. end_time - start_time .. ' seconds'
-The Lua ``os.clock()`` function will return the number of seconds since the
+The :ref:`os.clock() <os-clock>` function will return the number of CPU seconds since the
start. Therefore, by getting start_time = number of seconds just before the
inserting, and then getting end_time = number of seconds just after the
inserting, we can calculate (end_time - start_time) = elapsed time in seconds.
diff --git a/doc/sphinx/book/app/d-plugins.rst b/doc/sphinx/book/app/d-plugins.rst
index bb3f4e94d5..b696a45fb6 100644
--- a/doc/sphinx/book/app/d-plugins.rst
+++ b/doc/sphinx/book/app/d-plugins.rst
@@ -581,8 +581,8 @@ To end a session that began with :code:`pg.connect`, the request is:
**Example:**
- tarantool> conn:close()
- ---
+ tarantool> conn:close() |br|
+ --- |br|
...
For further information, including examples of rarely-used requests, see the
diff --git a/doc/sphinx/book/user_guide_getting_started.rst b/doc/sphinx/book/user_guide_getting_started.rst
index 32195bf2aa..1caa29ada3 100644
--- a/doc/sphinx/book/user_guide_getting_started.rst
+++ b/doc/sphinx/book/user_guide_getting_started.rst
@@ -227,7 +227,7 @@ You can repeat :code:`box.space...:insert{}` and :code:`box.space...:select{}`
indefinitely, on either Tarantool instance.
When the testing is over: To drop the space: :code:`s:drop()`.
To stop tarantool: Ctrl+C. To stop tarantool (an alternative):
-:code:`os.exit()`. To stop tarantool (from another terminal):
+:ref:`os.exit() <os-exit>`. To stop tarantool (from another terminal):
:code:`sudo pkill -f tarantool`.
To destroy the test: :code:`rm -r ~/tarantool_sandbox`.
diff --git a/doc/sphinx/reference/clock.rst b/doc/sphinx/reference/clock.rst
index eca8e96f8f..eeeaebf456 100644
--- a/doc/sphinx/reference/clock.rst
+++ b/doc/sphinx/reference/clock.rst
@@ -15,10 +15,9 @@ functions whose names end in "64" return a 64-bit number of nanoseconds.
realtime64()
The wall clock time. Derived from C function clock_gettime(CLOCK_REALTIME).
- Approximately the same as os.clock().
This is the best function for knowing what the official time is,
as determined by the system administrator. |br|
- See also :func:`fiber.time64 <fiber.time64>`.
+ See also :func:`fiber.time64 <fiber.time64>` and :ref:`os.clock() <os-clock>`.
:return: seconds or nanoseconds since epoch (1970-01-01 00:00:00), adjusted.
:rtype: number or number64
diff --git a/doc/sphinx/reference/index.rst b/doc/sphinx/reference/index.rst
index 2662ee37aa..995740e706 100644
--- a/doc/sphinx/reference/index.rst
+++ b/doc/sphinx/reference/index.rst
@@ -25,6 +25,7 @@
msgpack
net_box
box_once
+ os
pickle
shard
socket
diff --git a/doc/sphinx/reference/os.rst b/doc/sphinx/reference/os.rst
new file mode 100644
index 0000000000..aacbd9e1e0
--- /dev/null
+++ b/doc/sphinx/reference/os.rst
@@ -0,0 +1,143 @@
+-------------------------------------------------------------------------------
+ Package `os`
+-------------------------------------------------------------------------------
+
+.. module:: os
+
+The os package contains the functions
+:ref:`execute() <os-execute>`,
+:ref:`rename() <os-rename>`,
+:ref:`getenv() <os-getenv>`,
+:ref:`remove() <os-remove>`,
+:ref:`date() <os-date>`,
+:ref:`exit() <os-exit>`,
+:ref:`time() <os-time>`,
+:ref:`clock() <os-clock>`,
+:ref:`tmpname() <os-tmpname>`.
+Most of these functions are described in the Lua manual
+Chapter 22 `The Operating System Library <https://www.lua.org/pil/contents.html#22>`_.
+
+.. _os-execute:
+
+:codenormal:`os.`:codebold:`execute`:codenormal:`(`:codeitalic:`shell-command`:codenormal:`)`
+
+Execute by passing to the shell.
+
+Parameters: (string) shell-command = what to execute.
+
+**Example:** |br|
+:codenormal:`tarantool>` :codebold:`os.execute('ls -l /usr')` |br|
+:codenormal:`total 200` |br|
+:codenormal:`drwxr-xr-x 2 root root 65536 Apr 22 15:49 bin` |br|
+:codenormal:`drwxr-xr-x 59 root root 20480 Apr 18 07:58 include` |br|
+:codenormal:`drwxr-xr-x 210 root root 65536 Apr 18 07:59 lib` |br|
+:codenormal:`drwxr-xr-x 12 root root 4096 Apr 22 15:49 local` |br|
+:codenormal:`drwxr-xr-x 2 root root 12288 Jan 31 09:50 sbin` |br|
+
+.. _os-rename:
+
+:codenormal:`os.`:codebold:`rename`:codenormal:`(`:codeitalic:`old-name,new-name`:codenormal:`)`
+
+Rename a file or directory.
+
+Parameters: (string) old-name = name of existing file or directory,
+(string) new-name = changed name of file or directory.
+
+**Example:** |br|
+:codenormal:`tarantool>` :codebold:`os.rename('local','foreign')` |br|
+:codenormal:`---` |br|
+:codenormal:`- null` |br|
+:codenormal:`- 'local: No such file or directory'` |br|
+:codenormal:`- 2` |br|
+:codenormal:`...` |br|
+
+.. _os-getenv:
+
+:codenormal:`os.`:codebold:`getenv`:codenormal:`(`:codeitalic:`variable-name`:codenormal:`)`
+
+Get environment variable.
+
+Parameters: (string) variable-name = environment variable name.
+
+**Example:** |br|
+:codenormal:`tarantool>` :codebold:`os.getenv('PATH')` |br|
+:codenormal:`---` |br|
+:codenormal:`- /usr/local/sbin:/usr/local/bin:/usr/sbin` |br|
+:codenormal:`...` |br|
+
+.. _os-remove:
+
+:codenormal:`os.`:codebold:`remove`:codenormal:`(`:codeitalic:`name`:codenormal:`)`
+
+Remove file or directory.
+
+Parameters: (string) name = name of file or directory which will be removed.
+
+**Example:** |br|
+:codenormal:`tarantool>` :codebold:`os.remove('file')` |br|
+:codenormal:`---` |br|
+:codenormal:`- true` |br|
+:codenormal:`...` |br|
+
+.. _os-date:
+
+:codenormal:`os.`:codebold:`date`:codenormal:`(`:codeitalic:`format-string` :codenormal:`[,`:codeitalic:`time-since-epoch`:codenormal:`])`
+
+Return a formatted date.
+
+Parameters: (string) format-string = instructions; (string) time-since-epoch =
+number of seconds since 1970-01-01. If time-since-epoch is omitted, it is assumed to be the current time.
+
+**Example:** |br|
+:codenormal:`tarantool>` :codebold:`os.date("%A %B %d")` |br|
+:codenormal:`---` |br|
+:codenormal:`- Sunday April 24` |br|
+:codenormal:`...`
+
+.. _os-exit:
+
+:codenormal:`os.`:codebold:`exit`:codenormal:`()`
+
+Exit the program. If this is done on the server, then the server stops.
+
+**Example:** |br|
+:codenormal:`tarantool>` :codebold:`os.exit()` |br|
+:codenormal:`user@user-shell:~/tarantool_sandbox$``
+
+.. _os-time:
+
+:codenormal:`os.`:codebold:`time`:codenormal:`()`
+
+Return the number of seconds since the epoch.
+
+**Example:** |br|
+:codenormal:`tarantool>` :codebold:`os.time()` |br|
+:codenormal:`---` |br|
+:codenormal:`- 1461516945` |br|
+:codenormal:`...` |br|
+
+.. _os-clock:
+
+:codenormal:`os.`:codebold:`clock`:codenormal:`()`
+
+Return the number of CPU seconds since the program start.
+
+**Example:** |br|
+:codenormal:`tarantool>` :codebold:`os.clock()` |br|
+:codenormal:`---` |br|
+:codenormal:`- 0.05` |br|
+:codenormal:`...` |br|
+
+.. _os-tmpname:
+
+:codenormal:`os.`:codebold:`tmpname`:codenormal:`()`
+
+Return a name for a temporary file.
+
+**Example:** |br|
+:codenormal:`tarantool>` :codebold:`os.tmpname()` |br|
+:codenormal:`---` |br|
+:codenormal:`- /tmp/lua_7SW1m2` |br|
+:codenormal:`...` |br|
+
+
--
GitLab