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 The functions in this module will raise a badarg exception if their ar‐
16 guments contain invalid characters according to the description in the
17 "Data Types" section.
18
21 env_var_name() = nonempty_string()
22 A string containing valid characters on the specific OS for en‐
24 vironment variable names using file:native_name_encoding() en‐
25 coding. Null characters (integer value zero) are not allowed. On
26 Unix, = characters are not allowed. On Windows, a = character is
27 only allowed as the very first character in the string.
28 env_var_value() = string()
30 A string containing valid characters on the specific OS for en‐
32 vironment variable values using file:native_name_encoding() en‐
33 coding. Null characters (integer value zero) are not allowed.
34 env_var_name_value() = nonempty_string()
36 Assuming that environment variables has been correctly set, a
38 strings containing valid characters on the specific OS for envi‐
39 ronment variable names and values using file:native_name_encod‐
40 ing() encoding. The first = characters appearing in the string
41 separates environment variable name (on the left) from environ‐
42 ment variable value (on the right).
43 os_command() = atom() | io_lib:chars()
45 All characters needs to be valid characters on the specific OS
47 using file:native_name_encoding() encoding. Null characters (in‐
48 teger value zero) are not allowed.
49 os_command_opts() = #{max_size => integer() >= 0 | infinity}
51 Options for os:cmd/2
53 max_size:
55 The maximum size of the data returned by the os:cmd/2 call.
56 See the os:cmd/2 documentation for more details.
57
59 cmd(Command) -> string()
60 cmd(Command, Options) -> string()
62 Types:
64 Command = os_command()
66 Options = os_command_opts()
67 Executes Command in a command shell of the target OS, captures
69 the standard output of the command, and returns this result as a
70 string.
71 Examples:
73 LsOut = os:cmd("ls"), % on unix platform
75 DirOut = os:cmd("dir"), % on Win32 platform
76 Notice that in some cases, standard output of a command when
78 called from another program (for example, os:cmd/1) can differ,
79 compared with the standard output of the command when called di‐
80 rectly from an OS command shell.
81 os:cmd/2 was added in kernel-5.5 (OTP-20.2.1). It makes it pos‐
83 sible to pass an options map as the second argument in order to
84 control the behaviour of os:cmd. The possible options are:
85 max_size:
87 The maximum size of the data returned by the os:cmd call.
88 This option is a safety feature that should be used when the
89 command executed can return a very large, possibly infinite,
90 result.
91 > os:cmd("cat /dev/zero", #{ max_size => 20 }).
93 [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
94 env() -> [{env_var_name(), env_var_value()}]
96 Returns a list of all environment variables. Each environment
98 variable is expressed as a tuple {VarName,Value}, where VarName
99 is the name of the variable and Value its value.
100 If Unicode filename encoding is in effect (see the erl manual
102 page), the strings can contain characters with codepoints > 255.
103 find_executable(Name) -> Filename | false
105 find_executable(Name, Path) -> Filename | false
107 Types:
109 Name = Path = Filename = string()
111 These two functions look up an executable program, with the
113 specified name and a search path, in the same way as the under‐
114 lying OS. find_executable/1 uses the current execution path
115 (that is, the environment variable PATH on Unix and Windows).
116 Path, if specified, is to conform to the syntax of execution
118 paths on the OS. Returns the absolute filename of the executable
119 program Name, or false if the program is not found.
120 getenv() -> [env_var_name_value()]
122 Returns a list of all environment variables. Each environment
124 variable is expressed as a single string on the format "Var‐
125 Name=Value", where VarName is the name of the variable and Value
126 its value.
127 If Unicode filename encoding is in effect (see the erl manual
129 page), the strings can contain characters with codepoints > 255.
130 Consider using env/0 for a nicer 2-tuple format.
132 getenv(VarName) -> Value | false
134 Types:
136 VarName = env_var_name()
138 Value = env_var_value()
139 Returns the Value of the environment variable VarName, or false
141 if the environment variable is undefined.
142 If Unicode filename encoding is in effect (see the erl manual
144 page), the strings VarName and Value can contain characters with
145 codepoints > 255.
146 getenv(VarName, DefaultValue) -> Value
148 Types:
150 VarName = env_var_name()
152 DefaultValue = Value = env_var_value()
153 Returns the Value of the environment variable VarName, or De‐
155 faultValue if the environment variable is undefined.
156 If Unicode filename encoding is in effect (see the erl manual
158 page), the strings VarName and Value can contain characters with
159 codepoints > 255.
160 getpid() -> Value
162 Types:
164 Value = string()
166 Returns the process identifier of the current Erlang emulator in
168 the format most commonly used by the OS environment. Returns
169 Value as a string containing the (usually) numerical identifier
170 for a process. On Unix, this is typically the return value of
171 the getpid() system call. On Windows, the process id as returned
172 by the GetCurrentProcessId() system call is used.
173 putenv(VarName, Value) -> true
175 Types:
177 VarName = env_var_name()
179 Value = env_var_value()
180 Sets a new Value for environment variable VarName.
182 If Unicode filename encoding is in effect (see the erl manual
184 page), the strings VarName and Value can contain characters with
185 codepoints > 255.
186 On Unix platforms, the environment is set using UTF-8 encoding
188 if Unicode filename translation is in effect. On Windows, the
189 environment is set using wide character interfaces.
190 set_signal(Signal, Option) -> ok
192 Types:
194 Signal =
196 sighup | sigquit | sigabrt | sigalrm | sigterm | sigusr1
197 |
198 sigusr2 | sigchld | sigstop | sigtstp
199 Option = default | handle | ignore
200 Enables or disables OS signals.
202 Each signal my be set to one of the following options:
204 ignore:
206 This signal will be ignored.
207 default:
209 This signal will use the default signal handler for the op‐
210 erating system.
211 handle:
213 This signal will notify erl_signal_server when it is re‐
214 ceived by the Erlang runtime system.
215 system_time() -> integer()
217 Returns the current OS system time in native time unit.
219 Note:
221 This time is not a monotonically increasing time.
222 system_time(Unit) -> integer()
225 Types:
227 Unit = erlang:time_unit()
229 Returns the current OS system time converted into the Unit
231 passed as argument.
232 Calling os:system_time(Unit) is equivalent to erlang:con‐
234 vert_time_unit(os:system_time(), native, Unit).
235 Note:
237 This time is not a monotonically increasing time.
238 timestamp() -> Timestamp
241 Types:
243 Timestamp = erlang:timestamp()
245 Timestamp = {MegaSecs, Secs, MicroSecs}
246 Returns the current OS system time in the same format as er‐
248 lang:timestamp/0. The tuple can be used together with function
249 calendar:now_to_universal_time/1 or calendar:now_to_local_time/1
250 to get calendar time. Using the calendar time, together with the
251 MicroSecs part of the return tuple from this function, allows
252 you to log time stamps in high resolution and consistent with
253 the time in the rest of the OS.
254 Example of code formatting a string in format "DD Mon YYYY
256 HH:MM:SS.mmmmmm", where DD is the day of month, Mon is the tex‐
257 tual month name, YYYY is the year, HH:MM:SS is the time, and mm‐
258 mmmm is the microseconds in six positions:
259 -module(print_time).
261 -export([format_utc_timestamp/0]).
262 format_utc_timestamp() ->
263 TS = {_,_,Micro} = os:timestamp(),
264 {{Year,Month,Day},{Hour,Minute,Second}} =
265 calendar:now_to_universal_time(TS),
266 Mstr = element(Month,{"Jan","Feb","Mar","Apr","May","Jun","Jul",
267 "Aug","Sep","Oct","Nov","Dec"}),
268 io_lib:format("~2w ~s ~4w ~2w:~2..0w:~2..0w.~6..0w",
269 [Day,Mstr,Year,Hour,Minute,Second,Micro]).
270 This module can be used as follows:
272 1> io:format("~s~n",[print_time:format_utc_timestamp()]).
274 29 Apr 2009 9:55:30.051711
275 OS system time can also be retrieved by system_time/0 and sys‐
277 tem_time/1.
278 perf_counter() -> Counter
280 Types:
282 Counter = integer()
284 Returns the current performance counter value in perf_counter
286 time unit. This is a highly optimized call that might not be
287 traceable.
288 perf_counter(Unit) -> integer()
290 Types:
292 Unit = erlang:time_unit()
294 Returns a performance counter that can be used as a very fast
296 and high resolution timestamp. This counter is read directly
297 from the hardware or operating system with the same guarantees.
298 This means that two consecutive calls to the function are not
299 guaranteed to be monotonic, though it most likely will be. The
300 performance counter will be converted to the resolution passed
301 as an argument.
302 1> T1 = os:perf_counter(1000),receive after 10000 -> ok end,T2 = os:perf_counter(1000).
304 176525861
305 2> T2 - T1.
306 10004
307 type() -> {Osfamily, Osname}
309 Types:
311 Osfamily = unix | win32
313 Osname = atom()
314 Returns the Osfamily and, in some cases, the Osname of the cur‐
316 rent OS.
317 On Unix, Osname has the same value as uname -s returns, but in
319 lower case. For example, on Solaris 1 and 2, it is sunos.
320 On Windows, Osname is nt.
322 Note:
324 Think twice before using this function. Use module filename if
325 you want to inspect or build filenames in a portable way. Avoid
326 matching on atom Osname.
327 unsetenv(VarName) -> true
330 Types:
332 VarName = env_var_name()
334 Deletes the environment variable VarName.
336 If Unicode filename encoding is in effect (see the erl manual
338 page), the string VarName can contain characters with codepoints
339 > 255.
340 version() -> VersionString | {Major, Minor, Release}
342 Types:
344 VersionString = string()
346 Major = Minor = Release = integer() >= 0
347 Returns the OS version. On most systems, this function returns a
349 tuple, but a string is returned instead if the system has ver‐
350 sions that cannot be expressed as three numbers.
351 Note:
353 Think twice before using this function. If you still need to use
354 it, always call os:type() first.
355Ericsson AB kernel 8.5.4.2 os(3)