Specification: Ballerina OS Library

Owners: @daneshk @MadhukaHarith92
Reviewers: @daneshk
Created: 2021/11/10
Updated: 2022/02/08
Edition: Swan Lake


This is the specification for the OS standard library of Ballerina language, which provides APIs to retrieve information about the operating system and its current users.

The OS library specification has evolved and may continue to evolve in the future. The released versions of the specification can be found under the relevant Github tag.

If you have any feedback or suggestions about the library, start a discussion via a GitHub issue or in the Slack channel. Based on the outcome of the discussion, the specification and implementation can be updated. Community feedback is always welcome. Any accepted proposal, which affects the specification is stored under /docs/proposals. Proposals under discussion can be found with the label type/proposal in Github.

The conforming implementation of the specification is released and included in the distribution. Any deviation from the specification is considered a bug.


  1. Overview
  2. Environment Variable Values
  3. Operating System Users Information
  4. Operating System Command execution

1. Overview

This specification elaborates on the operating-system-related functions available in the OS library.

2. Environment Variable Values

The environment variable value associated with a provided name can be retrieved using the os:getEnv() function.

An environment variable can be set using the setEnv function.

An environment variable can be removed from the system using the unsetEnv function.

The existing environment variables of the system can be listed using the listEnv function.

3. Operating System Users Information

The current user's name can be retrieved using the os:getUsername() function.

The current user's home directory path can be retrieved using the os:getUserHome() function.

4. Operating System Command execution

The users can execute OS commands using the os:exec() function by passing an os:Command record.

The following is the record type definitions of os:Command.

Additionally, users can pass any number of environment properties as key-value pairs.

This will return an os:Process object. To wait for the process to finish its work and exit, process.waitForExit() function can be used.

To retrieve the output of the process, process.output() function can be used. This will return the standard output as default. There is an option provided to return standard error by providing file descriptor.

To terminate a process, process.exit() function can be used.

The following is the definition of the os:Process object.