summaryrefslogtreecommitdiff
path: root/doc/api/libstd/os.txt
blob: 2fad27129664dc899a1964a1d0099f11b8437f69 (plain)
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
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
{
        title:  OS Interfaces
        description:  libstd: OS Interfaces
}


OS Interfaces
-------------

    pkg std =
            type sysinfo = struct
                    system	: byte[:]
                    version	: byte[:]
                    release	: byte[:]
                    arch	: byte[:]
            ;;

            type waitstatus = union
                    `Wsuccess
                    `Wfailure
                    `Wsignalled
                    `Waiterror
            ;;

            const Enone	: errno 
            const Eperm	: errno 
            const Enoent	: errno 
            const Esrch	: errno 
            const Eintr	: errno 
            const Eio	: errno 
            const Enxio	: errno 
            const E2big	: errno 
            const Enoexec	: errno 
            const Ebadf	: errno 
            const Echild	: errno 
            const Eagain	: errno 
            const Enomem	: errno 
            const Eacces	: errno 
            const Efault	: errno 
            const Enotblk	: errno 
            const Ebusy	: errno 
            const Eexist	: errno 
            const Exdev	: errno 
            const Enodev	: errno 
            const Enotdir	: errno 
            const Eisdir	: errno 
            const Einval	: errno 
            const Enfile	: errno 
            const Emfile	: errno 
            const Enotty	: errno 
            const Etxtbsy	: errno 
            const Efbig	: errno 
            const Enospc	: errno 
            const Espipe	: errno 
            const Erofs	: errno 
            const Emlink	: errno 
            const Epipe	: errno 
            const Edom	: errno 
            const Erange	: errno 
            const Emisc	: errno 

            const Failmem	: byte#	

            const getpid	: ( -> pid)
            const getsysinfo	: (si : sysinfo# -> void)
            const execvp	: (cmd : byte[:], args : byte[:][:] -> int64)
            const execvpe	: (cmd : byte[:], args : byte[:][:], env : byte[:][:] -> int64)
            const getenv :	(name : byte[:] -> option(byte[:]))
            const getenvv :	(name : byte[:], default : byte[:] -> byte[:])
            const fork	: (-> pid)
            const execv	: (cmd : byte[:], args : byte[:][:] -> int64)
            const execve	: (cmd : byte[:], args : byte[:][:], env : byte[:][:] -> int64)
            const waitpid	: (pid:pid, loc:int32#, opt : int64	-> int64)
            const spork	: (cmd : byte[:][:]	-> result((pid, fd, fd), int))
            const sporkfd	: (cmd : byte[:][:], infd : fd, outfd : fd	-> result(pid, int))
            const exit	: (status:int -> void)
            const now	: (-> time)
            const wait	: (pid : pid -> waitstatus)

    ;;

    type sysinfo = struct
            system	: byte[:]
            version	: byte[:]
            release	: byte[:]
            arch	: byte[:]
    ;;

The `sysinfo` struct is returned from the operating system, giving
some information about the sytem that this program is running on. It
is similar to the `uname` function in the standard C library, although
it is guaranteed to be portable. All the storage for the members is
within the private parts of the struct, and no freeing is needed to
relase them.

    type waitstatus = union
            `Wsuccess
            `Wfailure
            `Wsignalled
            `Waiterror
    ;;

This type indicates the exit status of a child process that was invoked
with one of the exec family of functions. It only returns a broad category
of values, and does not return the full details provided by the os -- this
is not portable. If the exact exit status is needed, the `sys` package
should cover this need.

    const Enone	: errno 
    const Erange	: errno 
    const Ebadf	: errno 
    const Eexist	: errno 
    const Einval	: errno 
    const Efault	: errno 
    const Eio	: errno 
    const Emisc	: errno 


The errno results are used to signal OS errors. They are not going to remain
stable, and will probably be replaced with system call specific unions for
error handling in future API work. Use them, but parsimoniously. The code
that uses them will break.

Emisc is used for any non-portable error codes.

    const getpid	: ( -> pid)

Returns the process id of the current process.

    const getsysinfo	: (si : sysinfo# -> void)

Fills a `sysinfo` struct with information about the platform that the program
is running on.

    const execv	: (cmd : byte[:], args : byte[:][:] -> errno)
    const execve	: (cmd : byte[:], args : byte[:][:], env : byte[:][:] -> errno)

    const execvp	: (cmd : byte[:], args : byte[:][:] -> errno)
    const execvpe	: (cmd : byte[:], args : byte[:][:], env : byte[:][:] -> errno)

Executes a program. If the command `cmd` begins with a `/`, then it is
resolved as an absolute path. Otherwise, command is resolved relative to the
current directory.

If the path in `cmd` is not an absolute path, the `execvp` variants of this
function will search the path for this program in each directory relative to
$PATH or $path, in addition to the current directory.

The arguments in `args` are passed to the executed program as its argument
vector. By convention, the first argument in the `args` array should be the
filename of the program being executed.

For the `execvp` exec variant, the current program's environment is inherited,
and is not modified.

The `execvpe` variant of this function takes an additional argument `env`,
which is passed to the invoked binary, replacing alll the current environment
variables. It is in the form of a list of `"ENV_VAR=value"` key value pairs.

Returns: Errno on failure. On success, the function does not return.

    const getenv :	(name : byte[:] -> option(byte[:]))

The `getenv` function looks up a variable from the process environment.

Returns: `\`Some env\_val` for an environment variable that is present in the
environment, or `\`None` if it is not present.

    const getenvv :	(name : byte[:], default : byte[:] -> byte[:])

The `getenvv` is the same as `getenv, with the exception that will return the
value of the environment variable if it is present, or `default` if there is
no such environment variable.

Returns: The value of "name" if present, or "default" if not.

    const fork	: (-> pid)

This forks a new process. This function returns twice, once in the parent
and once in the child.

On a successful fork, within the parent process `fork` returns a process ID
greater than zero, which is the process id of the child process. Within the
child process, `fork` returns zero.

If the `fork` function returns a value less than zero, then creating a child
process failed.

Returns: The pid of the child.

    const wait	: (pid : pid -> waitstatus)

`wait` waits for a process with the PID `pid` to exit, returning its final
status. This function blocks until the child process has exited. If the
process has already exited before this function is called, but has not yet
been called on the process id of the child process, then this function
will return a status immediately.

If the child process has already been waited on, calling this function is
invalid, and it should return a `\`Waiterror`.

Returns: A waitstatus, telling you if the process crashed, exited with
failure, exited with success, or whether the wait call was invalid.

    const spork	: (cmd : byte[:][:]	-> result((pid, fd, fd), errno))

Spork stand for `Speak to Process Fork`. It returns a process id and an
input and output file descriptor via which you can communicate to the process
over stdin and stdout. Stderr is inherited from the current process.

Returns: Either a tuple of (pid, stdin, stdout) on success, or the error
that caused the failure.

    const sporkfd	: (cmd : byte[:][:], infd : fd, outfd : fd	-> result(pid, errno))

Sporkfd is identical to spork, however, instead of returning new file
descriptors, it uses the file descriptors passed in.

Returns: Either the pid spawned, or the error that caused the spawn failure.


    const exit	: (status:int -> void)

This exits a process with the status specified. On most Unixy systems,
this will return the value to the shell. On Plan 9, this will call
exits() with the number converted to a string.

This function terminates the process.