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 |
216 sigquit |
217 sigabrt |
218 sigalrm |
219 sigterm |
220 sigusr1 |
221 sigusr2 |
222 sigchld |
223 sigstop |
224 sigtstp
225 Option = default | handle | ignore
226 Enables or disables OS signals.
228 Each signal my be set to one of the following options:
230 ignore:
232 This signal will be ignored.
233 default:
235 This signal will use the default signal handler for the
236 operating system.
237 handle:
239 This signal will notify erl_signal_server when it is
240 received by the Erlang runtime system.
241 system_time() -> integer()
243 Returns the current OS system time in native time unit.
245 Note:
247 This time is not a monotonically increasing time.
248 system_time(Unit) -> integer()
251 Types:
253 Unit = erlang:time_unit()
255 Returns the current OS system time converted into the Unit
257 passed as argument.
258 Calling os:system_time(Unit) is equivalent to erlang:con‐
260 vert_time_unit(os:system_time(), native, Unit).
261 Note:
263 This time is not a monotonically increasing time.
264 timestamp() -> Timestamp
267 Types:
269 Timestamp = erlang:timestamp()
271 Timestamp = {MegaSecs, Secs, MicroSecs}
272 Returns the current OS system time in the same format as
274 erlang:timestamp/0. The tuple can be used together with function
275 calendar:now_to_universal_time/1 or calendar:now_to_local_time/1
276 to get calendar time. Using the calendar time, together with the
277 MicroSecs part of the return tuple from this function, allows
278 you to log time stamps in high resolution and consistent with
279 the time in the rest of the OS.
280 Example of code formatting a string in format "DD Mon YYYY
282 HH:MM:SS.mmmmmm", where DD is the day of month, Mon is the tex‐
283 tual month name, YYYY is the year, HH:MM:SS is the time, and
284 mmmmmm is the microseconds in six positions:
285 -module(print_time).
287 -export([format_utc_timestamp/0]).
288 format_utc_timestamp() ->
289 TS = {_,_,Micro} = os:timestamp(),
290 {{Year,Month,Day},{Hour,Minute,Second}} =
291 calendar:now_to_universal_time(TS),
292 Mstr = element(Month,{"Jan","Feb","Mar","Apr","May","Jun","Jul",
293 "Aug","Sep","Oct","Nov","Dec"}),
294 io_lib:format("~2w ~s ~4w ~2w:~2..0w:~2..0w.~6..0w",
295 [Day,Mstr,Year,Hour,Minute,Second,Micro]).
296 This module can be used as follows:
298 1> io:format("~s~n",[print_time:format_utc_timestamp()]).
300 29 Apr 2009 9:55:30.051711
301 OS system time can also be retreived by system_time/0 and sys‐
303 tem_time/1.
304 perf_counter() -> Counter
306 Types:
308 Counter = integer()
310 Returns the current performance counter value in perf_counter
312 time unit. This is a highly optimized call that might not be
313 traceable.
314 perf_counter(Unit) -> integer()
316 Types:
318 Unit = erlang:time_unit()
320 Returns a performance counter that can be used as a very fast
322 and high resolution timestamp. This counter is read directly
323 from the hardware or operating system with the same guarantees.
324 This means that two consecutive calls to the function are not
325 guaranteed to be monotonic, though it most likely will be. The
326 performance counter will be converted to the resolution passed
327 as an argument.
328 1> T1 = os:perf_counter(1000),receive after 10000 -> ok end,T2 = os:perf_counter(1000).
330 176525861
331 2> T2 - T1.
332 10004
333 type() -> {Osfamily, Osname}
335 Types:
337 Osfamily = unix | win32
339 Osname = atom()
340 Returns the Osfamily and, in some cases, the Osname of the cur‐
342 rent OS.
343 On Unix, Osname has the same value as uname -s returns, but in
345 lower case. For example, on Solaris 1 and 2, it is sunos.
346 On Windows, Osname is nt.
348 Note:
350 Think twice before using this function. Use module filename if
351 you want to inspect or build filenames in a portable way. Avoid
352 matching on atom Osname.
353 unsetenv(VarName) -> true
356 Types:
358 VarName = env_var_name()
360 Deletes the environment variable VarName.
362 If Unicode filename encoding is in effect (see the erl manual
364 page), the string VarName can contain characters with codepoints
365 > 255.
366 version() -> VersionString | {Major, Minor, Release}
368 Types:
370 VersionString = string()
372 Major = Minor = Release = integer() >= 0
373 Returns the OS version. On most systems, this function returns a
375 tuple, but a string is returned instead if the system has ver‐
376 sions that cannot be expressed as three numbers.
377 Note:
379 Think twice before using this function. If you still need to use
380 it, always call os:type() first.
381Ericsson AB kernel 6.3.1.1 os(3)