# %putenv() function

The %putenv() function makes the value
of the environment variable name equal to the value designated by *str*, by altering an existing variable or by creating a
new one.

## Syntax

```
result = %putenv(str)
```

## Parameter(s)

| result | Returns nonzero if the variable is added successfully to the environment, or 0 if an error occurred. |
| --- | --- |
| str | String of the form name=value. |

## Description

The environment contains a pointer
to *str*, making it a mistake to use a FlashBASIC
variable as *str* (FlashBASIC variables are essentially
volatile). Proper use requires using %malloc() to
obtain non-FlashBASIC space, using %strcpy() to
copy the FlashBASIC variable into it, and passing the space allocated
by %malloc() to %putenv, as
in the example below.

## Example(s)

Add the string `port=current port.number` to the host environment of the process. After
this program has been executed, the TCL env command
displays the port number of the process. The TCL environ command performs this kind of environment setting.

```
* Build the string
string=’PORT_NUMBER=’:system(22)
* get workspace (+1 for terminating NULL)
ptr=(char*)%malloc(1+len(string))
* Put the string into the allocated buff
%strcpy((char*)ptr, string)
* Add it to the environment
%putenv((char*)ptr)
```

## See also

- [%getenv() function](https://d3codex.com/pickbasic-flashbasic/percent-getenv-function/)
- [%malloc() function](https://d3codex.com/pickbasic-flashbasic/percent-malloc-function/)
- [cfunction statement](https://d3codex.com/pickbasic-flashbasic/cfunction-statement/)
- [env command](https://d3codex.com/unix/env-command/)
- [environ command](https://d3codex.com/tcl/environ-command/)
- [system() function](https://d3codex.com/pickbasic-flashbasic/system-function/)

---
Source: https://d3codex.com/pickbasic-flashbasic/percent-putenv-function/ - part of the D3Codex reference.