1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
|
/** -*-C-*-ish
Kaya standard library
Copyright (C) 2004, 2005 Edwin Brady
This file is distributed under the terms of the GNU Lesser General
Public Licence. See COPYING for licence.
*/
"<summary>System interaction functions</summary>
<prose>This module contains functions for interaction with the system, such as environment and argument retrieval, sleeping, and temporary file creation.</prose>
<prose>On Posix systems, the <moduleref>Posix</moduleref> module provides additional system interaction functions.</prose>"
module System;
import Array;
%include "stdlib.h";
%include "unistd.h";
foreign "stdfuns.o" {
"<argument name='code'>The exit code</argument>
<summary>Exit immediately, without calling signal handlers.</summary>
<prose>Exits immediately, without calling signal handlers, with the given exit code. An exit code of zero is traditionally used for successful completion.</prose>
<prose>As with <code>exit</code>, this should not be called in web applications.</prose>
<related><functionref>Builtins::exit</functionref></related>"
public Void _exit(Int code) = _exit;
"<summary>Get command-line arguments.</summary>
<prose>Return the arguments passed to the program on the command line. The zeroth argument is the name the program was called with. A command line of <input>printargs -a 100 --long-argument</input> will give a resulting array <code>[\"printargs\",\"-a\",\"100\",\"--long-argument\"]</code></prose>
<related><functionref>getEnv</functionref></related>
<related><functionref>getPID</functionref></related>
<related><functionref>progName</functionref> can be used instead if you only need the program name</related>"
public [String] getArgs() = getArgs;
"<argument name='env'>The name of the environment variable</argument>
<summary>Get the value of an environment variable.</summary>
<prose>Retrieves the value of an environment variable.</prose>
<prose>This is often necessary in a web application as the web server will set environment variables in the program. Some of these headers are set by the server environment, others are set based on the current request (and so may be trivially forged by the user's browser).</prose>
<example>ua = getEnv(\"HTTP_USER_AGENT\"); // Contents of User-Agent header
host = getEnv(\"HTTP_HOST\"); // the IP address of the web server
user = getEnv(\"REMOTE_USER\"); // the username under HTTP authentication
ip = getEnv(\"REMOTE_ADDR\"); // the client's IP address</example>
<prose>Environment variables are also useful for command-line programs</prose>
<example>home = getEnv(\"HOME\"); // The user's home directory on Posix systems
proxy = getEnv(\"HTTP_PROXY\"); // The HTTP proxy to use for outgoing connections</example>
<prose>If the environment variable is not set, the empty String will be returned.</prose>
<related><functionref>getArgs</functionref></related>
<related><functionref>getPID</functionref></related>"
public String getEnv(String env) = do_getenv;
"<summary>Change directory</summary>
<prose>Change the current working directory to another directory. The directory path given can be relative or absolute.</prose>
<example>// currently in /home/me/working
chdir(\"sub\"); // now in /home/me/working/sub
chdir(\"../../..\"); // now in /home
chdir(\"/tmp\"); // now in /tmp</example>
<prose>The function behaves in a similar fashion on Windows</prose>
<example>// currently in C:\\kaya\\programs
chdir(\"sub\"); // now in C:\\kaya\\programs\\sub
chdir(\"..\\\\..\"); // now in C:\\kaya
chdir(\"\\\\Program Files\"); // now in C:\\Program Files
chdir(\"F:\\\\data\"); // now in F:\\data</example>
<prose>Note the need to escape the backslashes used as a path separator.</prose>"
// check if forward slashes work on windows
// naturally have to double escape backslashes in docstring
public Void chdir(String path) = do_chdir;
"<summary>Get process ID</summary>
<prose>Get the process ID for the Kaya program.</prose>
<related><functionref>getArgs</functionref></related>
<related><functionref>getEnv</functionref></related>"
public Int getPID() = dogetpid;
"<summary>Get current working directory</summary>
<prose>Get the current working directory.</prose>
<related><functionref>chdir</functionref></related>"
public String getCwd() = dogetcwd;
"<argument name='secs'>The number of seconds to sleep for</argument>
<summary>Sleep for the specified number of seconds.</summary>
<prose>Sleep (i.e. pause program execution) for the specified number of seconds.</prose>
<related><functionref>microSleep</functionref></related>"
public Void sleep(Int secs) = do_sleep;
"<argument name='microsecs'>The number of microseconds to sleep for</argument>
<summary>Sleep for the specified number of microseconds.</summary>
<prose>Sleep (i.e. pause program execution) for at least the specified number of microseconds. Depending on your operating system, it may not actually possible to sleep for a single microsecond - on Windows, the smallest amount of time it is possible to sleep for is 1 millisecond.</prose>
<related><functionref>sleep</functionref></related>"
public Void microSleep(Int microsecs) = do_usleep;
}
"<summary>Get program name.</summary>
<prose>Returns the name of the currently running executable. This should not be used in web applications for constructing self-referential links as the name may include filesystem path information. Use <functionref>WebCommon::webappName</functionref> instead.</prose>
<example>p = progName(); // p = \"/usr/local/bin/kayadoc2man\"</example>
<related><functionref>getArgs</functionref></related>
<related><functionref>getEnv</functionref></related>
<related><functionref>getPID</functionref></related>
<related><functionref>WebCommon::webappName</functionref></related>"
public String progName() = getArgs()[0];
|
