xgo/docs/stdlib-os.md

# Module - "os"

```golang
os := import("os")
```

## Constants

- `o_rdonly`
- `o_wronly`
- `o_rdwr`
- `o_append`
- `o_create`
- `o_excl`
- `o_sync`
- `o_trunc`
- `mode_dir`
- `mode_append`
- `mode_exclusive`
- `mode_temporary`
- `mode_symlink`
- `mode_device`
- `mode_named_pipe`
- `mode_socket`
- `mode_setuid`
- `mode_setgui`
- `mode_char_device`
- `mode_sticky`
- `mode_irregular`
- `mode_type`
- `mode_perm`
- `seek_set`
- `seek_cur`
- `seek_end`
- `path_separator`
- `path_list_separator`
- `dev_null`


## Functions

- `args() => [string]`: returns command-line arguments, starting with the program name.
- `chdir(dir string) => error`: changes the current working directory to the named directory.
- `chmod(name string, mode int) => error `: changes the mode of the named file to mode.
- `chown(name string, uid int, gid int) => error `: changes the numeric uid and gid of the named file.
- `clearenv()`: deletes all environment variables.
- `environ() => [string] `: returns a copy of strings representing the environment.
- `exit(code int) `: causes the current program to exit with the given status code.
- `expand_env(s string) => string `: replaces ${var} or $var in the string according to the values of the current environment variables.
- `getegid() => int `: returns the numeric effective group id of the caller.
- `getenv(key string) => string `: retrieves the value of the environment variable named by the key.
- `geteuid() => int `: returns the numeric effective user id of the caller.
- `getgid() => int `: returns the numeric group id of the caller.
- `getgroups() => [int]/error `: returns a list of the numeric ids of groups that the caller belongs to.
- `getpagesize() => int `: returns the underlying system's memory page size.
- `getpid() => int `: returns the process id of the caller.
- `getppid() => int `: returns the process id of the caller's parent.
- `getuid() => int `: returns the numeric user id of the caller.
- `getwd() => string/error `: returns a rooted path name corresponding to the current directory.
- `hostname() => string/error `: returns the host name reported by the kernel.
- `lchown(name string, uid int, gid int) => error `: changes the numeric uid and gid of the named file.
- `link(oldname string, newname string) => error `: creates newname as a hard link to the oldname file.
- `lookup_env(key string) => string/false`: retrieves the value of the environment variable named by the key.
- `mkdir(name string, perm int) => error `: creates a new directory with the specified name and permission bits (before umask).
- `mkdir_all(name string, perm int) => error `: creates a directory named path, along with any necessary parents, and returns nil, or else returns an error.
- `read_file(name string) => bytes/error `: reads the contents of a file into a byte array
- `readlink(name string) => string/error `: returns the destination of the named symbolic link.
- `remove(name string) => error `: removes the named file or (empty) directory.
- `remove_all(name string) => error `: removes path and any children it contains.
- `rename(oldpath string, newpath string) => error `: renames (moves) oldpath to newpath.
- `setenv(key string, value string) => error `: sets the value of the environment variable named by the key.
- `stat(filename string) => FileInfo/error`: returns a file info structure describing the file
- `symlink(oldname string newname string) => error `: creates newname as a symbolic link to oldname.
- `temp_dir() => string `: returns the default directory to use for temporary files.
- `truncate(name string, size int) => error `: changes the size of the named file.
- `unsetenv(key string) => error `: unsets a single environment variable.
- `create(name string) => File/error`: creates the named file with mode 0666 (before umask), truncating it if it already exists. 
- `open(name string) => File/error`: opens the named file for reading. If successful, methods on the returned file can be used for reading; the associated file descriptor has mode O_RDONLY.
- `open_file(name string, flag int, perm int) => File/error`: is the generalized open call; most users will use Open or Create instead. It opens the named file with specified flag (O_RDONLY etc.) and perm (before umask), if applicable.
- `find_process(pid int) => Process/error`: looks for a running process by its pid.
- `start_process(name string, argv [string], dir string, env [string]) => Process/error`: starts a new process with the program, arguments and attributes specified by name, argv and attr. The argv slice will become os.Args in the new process, so it normally starts with the program name.
- `exec_look_path(file string) => string/error`: searches for an executable named file in the directories named by the PATH environment variable.
- `exec(name string, args...) => Command/error`: returns the Command to execute the named program with the given arguments.


## File

```golang
file := os.create("myfile")
file.write_string("some data")
file.close()
```

- `chdir() => true/error`: changes the current working directory to the file,
- `chown(uid int, gid int) => true/error`: changes the numeric uid and gid of the named file.
- `close() => error`: closes the File, rendering it unusable for I/O.
- `name() => string`: returns the name of the file as presented to Open.
- `readdirnames(n int) => [string]/error`: reads and returns a slice of names from the directory.
- `sync() => error`: commits the current contents of the file to stable storage.
- `write(bytes) => int/error`: writes len(b) bytes to the File.
- `write_string(string) => int/error`: is like 'write', but writes the contents of string s rather than a slice of bytes.
- `read(bytes) => int/error`: reads up to len(b) bytes from the File.
- `stat() => FileInfo/error`: returns a file info structure describing the file
- `chmod(mode int) => error`: changes the mode of the file to mode.
- `seek(offset int, whence int) => int/error`: sets the offset for the next Read or Write on file to offset, interpreted according to whence: 0 means relative to the origin of the file, 1 means relative to the current offset, and 2 means relative to the end.

## Process

```golang
proc := start_process("app", ["arg1", "arg2"], "dir", [])
proc.wait()
```

- `kill() => error`: causes the Process to exit immediately. 
- `release() => error`: releases any resources associated with the process, rendering it unusable in the future.
- `signal(signal int) => error`: sends a signal to the Process.
- `wait() => ProcessState/error`: waits for the Process to exit, and then returns a ProcessState describing its status and an error, if any.

## ProcessState

```golang
proc := start_process("app", ["arg1", "arg2"], "dir", [])
stat := proc.wait()
pid := stat.pid()
```

- `exited() => bool`: reports whether the program has exited.
- `pid() => int`: returns the process id of the exited process.
- `string() => string`: returns a string representation of the process.
- `success() => bool`: reports whether the program exited successfully, such as with exit status 0 on Unix.

```golang
cmd := exec.command("echo", ["foo", "bar"])
output := cmd.output()
```

## FileInfo

- `name`: name of the file the info describes
- `mtime`: time the file was last modified
- `size`: file size in bytes
- `mode`: file permissions as in int, comparable to octal permissions
- `directory`: boolean indicating if the file is a directory

## Command

- `combined_output() => bytes/error`: runs the command and returns its combined standard output and standard error.
- `output() => bytes/error`: runs the command and returns its standard output.
- `run() => error`: starts the specified command and waits for it to complete.
- `start() => error`: starts the specified command but does not wait for it to complete.
- `wait() => error`: waits for the command to exit and waits for any copying to stdin or copying from stdout or stderr to complete.
- `set_path(path string)`: sets the path of the command to run.
- `set_dir(dir string)`: sets the working directory of the process.
- `set_env(env [string])`: sets the environment of the process.
- `process() => Process`: returns the underlying process, once started.