1os(3) Erlang Module Definition os(3)
2
6 os - Operating system-specific functions.
7
9 The functions in this module are operating system-specific. Careless
10 use of these functions results in programs that will only run on a spe‐
11 cific platform. On the other hand, with careful use, these functions
12 can be of help in enabling a program to run on most platforms.
13 Note:
15 File operations used to accept filenames containing null characters
16 (integer value zero). This caused the name to be truncated and in some
17 cases arguments to primitive operations to be mixed up. Filenames con‐
18 taining null characters inside the filename are now rejected and will
19 cause primitive file operations to fail.
20 Also environment variable operations used to accept names and values of
22 environment variables containing null characters (integer value zero).
23 This caused operations to silently produce erroneous results. Environ‐
24 ment variable names and values containing null characters inside the
25 name or value are now rejected and will cause environment variable
26 operations to fail.
27
30 env_var_name() = nonempty_string()
31 A string containing valid characters on the specific OS for
33 environment variable names using file:native_name_encoding()
34 encoding. Note that specifically null characters (integer value
35 zero) and $= characters are not allowed. However, note that not
36 all invalid characters necessarily will cause the primitiv oper‐
37 ations to fail, but may instead produce invalid results.
38 env_var_value() = string()
40 A string containing valid characters on the specific OS for
42 environment variable values using file:native_name_encoding()
43 encoding. Note that specifically null characters (integer value
44 zero) are not allowed. However, note that not all invalid char‐
45 acters necessarily will cause the primitiv operations to fail,
46 but may instead produce invalid results.
47 env_var_name_value() = nonempty_string()
49 Assuming that environment variables has been correctly set, a
51 strings containing valid characters on the specific OS for envi‐
52 ronment variable names and values using file:native_name_encod‐
53 ing() encoding. The first $= characters appearing in the string
54 separates environment variable name (on the left) from environ‐
55 ment variable value (on the right).
56 os_command() = atom() | io_lib:chars()
58 All characters needs to be valid characters on the specific OS
60 using file:native_name_encoding() encoding. Note that specifi‐
61 cally null characters (integer value zero) are not allowed. How‐
62 ever, note that not all invalid characters not necessarily will
63 cause os:cmd/1 to fail, but may instead produce invalid results.
64 os_command_opts() = #{max_size => integer() >= 0 | infinity}
66 Options for os:cmd/2
68 max_size:
70 The maximum size of the data returned by the os:cmd call.
71 See the os:cmd/2 documentation for more details.
72
74 cmd(Command) -> string()
75 cmd(Command, Options) -> string()
77 Types:
79 Command = os_command()
81 Options = os_command_opts()
82 Executes Command in a command shell of the target OS, captures
84 the standard output of the command, and returns this result as a
85 string.
86 Warning:
88 Previous implementation used to allow all characters as long as
89 they were integer values greater than or equal to zero. This
90 sometimes lead to unwanted results since null characters (inte‐
91 ger value zero) often are interpreted as string termination. The
92 current implementation rejects these.
93 Examples:
96 LsOut = os:cmd("ls"), % on unix platform
98 DirOut = os:cmd("dir"), % on Win32 platform
99 Notice that in some cases, standard output of a command when
101 called from another program (for example, os:cmd/1) can differ,
102 compared with the standard output of the command when called
103 directly from an OS command shell.
104 os:cmd/2 was added in kernel-5.5 (OTP-20.2.1). It makes it pos‐
106 sible to pass an options map as the second argument in order to
107 control the behaviour of os:cmd. The possible options are:
108 max_size:
110 The maximum size of the data returned by the os:cmd call.
111 This option is a safety feature that should be used when the
112 command executed can return a very large, possibly infinite,
113 result.
114 > os:cmd("cat /dev/zero", #{ max_size => 20 }).
116 [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
117 find_executable(Name) -> Filename | false
119 find_executable(Name, Path) -> Filename | false
121 Types:
123 Name = Path = Filename = string()
125 These two functions look up an executable program, with the
127 specified name and a search path, in the same way as the under‐
128 lying OS. find_executable/1 uses the current execution path
129 (that is, the environment variable PATH on Unix and Windows).
130 Path, if specified, is to conform to the syntax of execution
132 paths on the OS. Returns the absolute filename of the executable
133 program Name, or false if the program is not found.
134 getenv() -> [env_var_name_value()]
136 Returns a list of all environment variables. Each environment
138 variable is expressed as a single string on the format "Var‐
139 Name=Value", where VarName is the name of the variable and Value
140 its value.
141 If Unicode filename encoding is in effect (see the erl manual
143 page), the strings can contain characters with codepoints > 255.
144 getenv(VarName) -> Value | false
146 Types:
148 VarName = env_var_name()
150 Value = env_var_value()
151 Returns the Value of the environment variable VarName, or false
153 if the environment variable is undefined.
154 If Unicode filename encoding is in effect (see the erl manual
156 page), the strings VarName and Value can contain characters with
157 codepoints > 255.
158 getenv(VarName, DefaultValue) -> Value
160 Types:
162 VarName = env_var_name()
164 DefaultValue = Value = env_var_value()
165 Returns the Value of the environment variable VarName, or
167 DefaultValue if the environment variable is undefined.
168 If Unicode filename encoding is in effect (see the erl manual
170 page), the strings VarName and Value can contain characters with
171 codepoints > 255.
172 getpid() -> Value
174 Types:
176 Value = string()
178 Returns the process identifier of the current Erlang emulator in
180 the format most commonly used by the OS environment. Returns
181 Value as a string containing the (usually) numerical identifier
182 for a process. On Unix, this is typically the return value of
183 the getpid() system call. On Windows, the process id as returned
184 by the GetCurrentProcessId() system call is used.
185 putenv(VarName, Value) -> true
187 Types:
189 VarName = env_var_name()
191 Value = env_var_value()
192 Sets a new Value for environment variable VarName.
194 If Unicode filename encoding is in effect (see the erl manual
196 page), the strings VarName and Value can contain characters with
197 codepoints > 255.
198 On Unix platforms, the environment is set using UTF-8 encoding
200 if Unicode filename translation is in effect. On Windows, the
201 environment is set using wide character interfaces.
202 Note:
204 VarName is not allowed to contain an $= character. Previous
205 implementations used to just let the $= character through which
206 silently caused erroneous results. Current implementation will
207 instead throw a badarg exception.
208 set_signal(Signal, Option) -> ok
211 Types:
213 Signal =
215 sighup | sigquit | sigabrt | sigalrm | sigterm | sigusr1
216 |
217 sigusr2 | sigchld | sigstop | sigtstp
218 Option = default | handle | ignore
219 Enables or disables OS signals.
221 Each signal my be set to one of the following options:
223 ignore:
225 This signal will be ignored.
226 default:
228 This signal will use the default signal handler for the
229 operating system.
230 handle:
232 This signal will notify erl_signal_server when it is
233 received by the Erlang runtime system.
234 system_time() -> integer()
236 Returns the current OS system time in native time unit.
238 Note:
240 This time is not a monotonically increasing time.
241 system_time(Unit) -> integer()
244 Types:
246 Unit = erlang:time_unit()
248 Returns the current OS system time converted into the Unit
250 passed as argument.
251 Calling os:system_time(Unit) is equivalent to erlang:con‐
253 vert_time_unit(os:system_time(), native, Unit).
254 Note:
256 This time is not a monotonically increasing time.
257 timestamp() -> Timestamp
260 Types:
262 Timestamp = erlang:timestamp()
264 Timestamp = {MegaSecs, Secs, MicroSecs}
265 Returns the current OS system time in the same format as
267 erlang:timestamp/0. The tuple can be used together with function
268 calendar:now_to_universal_time/1 or calendar:now_to_local_time/1
269 to get calendar time. Using the calendar time, together with the
270 MicroSecs part of the return tuple from this function, allows
271 you to log time stamps in high resolution and consistent with
272 the time in the rest of the OS.
273 Example of code formatting a string in format "DD Mon YYYY
275 HH:MM:SS.mmmmmm", where DD is the day of month, Mon is the tex‐
276 tual month name, YYYY is the year, HH:MM:SS is the time, and
277 mmmmmm is the microseconds in six positions:
278 -module(print_time).
280 -export([format_utc_timestamp/0]).
281 format_utc_timestamp() ->
282 TS = {_,_,Micro} = os:timestamp(),
283 {{Year,Month,Day},{Hour,Minute,Second}} =
284 calendar:now_to_universal_time(TS),
285 Mstr = element(Month,{"Jan","Feb","Mar","Apr","May","Jun","Jul",
286 "Aug","Sep","Oct","Nov","Dec"}),
287 io_lib:format("~2w ~s ~4w ~2w:~2..0w:~2..0w.~6..0w",
288 [Day,Mstr,Year,Hour,Minute,Second,Micro]).
289 This module can be used as follows:
291 1> io:format("~s~n",[print_time:format_utc_timestamp()]).
293 29 Apr 2009 9:55:30.051711
294 OS system time can also be retreived by system_time/0 and sys‐
296 tem_time/1.
297 perf_counter() -> Counter
299 Types:
301 Counter = integer()
303 Returns the current performance counter value in perf_counter
305 time unit. This is a highly optimized call that might not be
306 traceable.
307 perf_counter(Unit) -> integer()
309 Types:
311 Unit = erlang:time_unit()
313 Returns a performance counter that can be used as a very fast
315 and high resolution timestamp. This counter is read directly
316 from the hardware or operating system with the same guarantees.
317 This means that two consecutive calls to the function are not
318 guaranteed to be monotonic, though it most likely will be. The
319 performance counter will be converted to the resolution passed
320 as an argument.
321 1> T1 = os:perf_counter(1000),receive after 10000 -> ok end,T2 = os:perf_counter(1000).
323 176525861
324 2> T2 - T1.
325 10004
326 type() -> {Osfamily, Osname}
328 Types:
330 Osfamily = unix | win32
332 Osname = atom()
333 Returns the Osfamily and, in some cases, the Osname of the cur‐
335 rent OS.
336 On Unix, Osname has the same value as uname -s returns, but in
338 lower case. For example, on Solaris 1 and 2, it is sunos.
339 On Windows, Osname is nt.
341 Note:
343 Think twice before using this function. Use module filename if
344 you want to inspect or build filenames in a portable way. Avoid
345 matching on atom Osname.
346 unsetenv(VarName) -> true
349 Types:
351 VarName = env_var_name()
353 Deletes the environment variable VarName.
355 If Unicode filename encoding is in effect (see the erl manual
357 page), the string VarName can contain characters with codepoints
358 > 255.
359 version() -> VersionString | {Major, Minor, Release}
361 Types:
363 VersionString = string()
365 Major = Minor = Release = integer() >= 0
366 Returns the OS version. On most systems, this function returns a
368 tuple, but a string is returned instead if the system has ver‐
369 sions that cannot be expressed as three numbers.
370 Note:
372 Think twice before using this function. If you still need to use
373 it, always call os:type() first.
374Ericsson AB kernel 6.5.2 os(3)