Home / Autodocs / dos.library
NAME
- SetVar
-
Sets a local or environment variable (V36)
SYNOPSIS
success = SetVar( name, buffer, size, flags )
D0 D1 D2 D3 D4
BOOL SetVar(STRPTR, STRPTR, LONG, ULONG )
D0 D1 D2 D3 D4
BOOL SetVar(STRPTR, STRPTR, LONG, ULONG )
FUNCTION
Sets a local or environment variable. It is advised to only use ASCII strings inside variables, but not required.
INPUTS
- name
-
pointer to a variable name. Note variable names follow file system syntax and semantics.
- buffer
-
a user-allocated area which contains a string that is the value to be associated with this variable.
- size
-
length of the buffer region in bytes. -1 means buffer contains a null-terminated string.
- flags
-
combination of type of var to set (low 8 bits), and flags to control the behavior of this function. Currently defined flags include:
- GVF_LOCAL_ONLY
-
set a local (to your Process) variable.
- GVF_GLOBAL_ONLY
-
set a global environment variable.
RESULT
- success
-
If non-zero, the variable was sucessfully set. FALSE indicates failure.
WARNING
Changing a global environment variable may fail without notice. In spite of returning success, SetVar() may leave the contents of the file containing the variable value in an undefined state.
For SetVar() to succeed, the file system which the ENV: assignment is bound to must support Open(..., MODE_READWRITE) as well as SetFileSize() truncation. Both the Amiga ROM default file system and RAM: support both, but 3rd party file systems may not.
SetVar() lacks the means to insure that only one Process at a time is allowed to modify or read the value of a global environment variable. Overlapping changes can happen and may leave the variable value in an undefined state. Two Processes which compete for reading and writing a global environment variable may cause the writer's SetFileSize() call to fail to truncate the size of the file which the reader has not closed yet.
For SetVar() to succeed, the file system which the ENV: assignment is bound to must support Open(..., MODE_READWRITE) as well as SetFileSize() truncation. Both the Amiga ROM default file system and RAM: support both, but 3rd party file systems may not.
SetVar() lacks the means to insure that only one Process at a time is allowed to modify or read the value of a global environment variable. Overlapping changes can happen and may leave the variable value in an undefined state. Two Processes which compete for reading and writing a global environment variable may cause the writer's SetFileSize() call to fail to truncate the size of the file which the reader has not closed yet.
BUGS
LV_VAR is the only type that can be global. Releases prior V47 did not clear the e protection bit of the file(s) created in ENV: and ENVARC: SetEnv did that manually. If a variable name contained two slashes such as //, releases prior to V47 would have crashed. This has been fixed.