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
16 arguments contain invalid characters according to the description in
17 the "Data Types" section.
18
21 env_var_name() = nonempty_string()
22 A string containing valid characters on the specific OS for
24 environment variable names using file:native_name_encoding()
25 encoding. Null characters (integer value zero) are not allowed.
26 On Unix, = characters are not allowed. On Windows, a = character
27 is 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
32 environment variable values using file:native_name_encoding()
33 encoding. 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
48 (integer 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
80 directly 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 find_executable(Name) -> Filename | false
96 find_executable(Name, Path) -> Filename | false
98 Types:
100 Name = Path = Filename = string()
102 These two functions look up an executable program, with the
104 specified name and a search path, in the same way as the under‐
105 lying OS. find_executable/1 uses the current execution path
106 (that is, the environment variable PATH on Unix and Windows).
107 Path, if specified, is to conform to the syntax of execution
109 paths on the OS. Returns the absolute filename of the executable
110 program Name, or false if the program is not found.
111 getenv() -> [env_var_name_value()]
113 Returns a list of all environment variables. Each environment
115 variable is expressed as a single string on the format "Var‐
116 Name=Value", where VarName is the name of the variable and Value
117 its value.
118 If Unicode filename encoding is in effect (see the erl manual
120 page), the strings can contain characters with codepoints > 255.
121 getenv(VarName) -> Value | false
123 Types:
125 VarName = env_var_name()
127 Value = env_var_value()
128 Returns the Value of the environment variable VarName, or false
130 if the environment variable is undefined.
131 If Unicode filename encoding is in effect (see the erl manual
133 page), the strings VarName and Value can contain characters with
134 codepoints > 255.
135 getenv(VarName, DefaultValue) -> Value
137 Types:
139 VarName = env_var_name()
141 DefaultValue = Value = env_var_value()
142 Returns the Value of the environment variable VarName, or
144 DefaultValue if the environment variable is undefined.
145 If Unicode filename encoding is in effect (see the erl manual
147 page), the strings VarName and Value can contain characters with
148 codepoints > 255.
149 getpid() -> Value
151 Types:
153 Value = string()
155 Returns the process identifier of the current Erlang emulator in
157 the format most commonly used by the OS environment. Returns
158 Value as a string containing the (usually) numerical identifier
159 for a process. On Unix, this is typically the return value of
160 the getpid() system call. On Windows, the process id as returned
161 by the GetCurrentProcessId() system call is used.
162 putenv(VarName, Value) -> true
164 Types:
166 VarName = env_var_name()
168 Value = env_var_value()
169 Sets a new Value for environment variable VarName.
171 If Unicode filename encoding is in effect (see the erl manual
173 page), the strings VarName and Value can contain characters with
174 codepoints > 255.
175 On Unix platforms, the environment is set using UTF-8 encoding
177 if Unicode filename translation is in effect. On Windows, the
178 environment is set using wide character interfaces.
179 set_signal(Signal, Option) -> ok
181 Types:
183 Signal =
185 sighup | sigquit | sigabrt | sigalrm | sigterm | sigusr1
186 |
187 sigusr2 | sigchld | sigstop | sigtstp
188 Option = default | handle | ignore
189 Enables or disables OS signals.
191 Each signal my be set to one of the following options:
193 ignore:
195 This signal will be ignored.
196 default:
198 This signal will use the default signal handler for the
199 operating system.
200 handle:
202 This signal will notify erl_signal_server when it is
203 received by the Erlang runtime system.
204 system_time() -> integer()
206 Returns the current OS system time in native time unit.
208 Note:
210 This time is not a monotonically increasing time.
211 system_time(Unit) -> integer()
214 Types:
216 Unit = erlang:time_unit()
218 Returns the current OS system time converted into the Unit
220 passed as argument.
221 Calling os:system_time(Unit) is equivalent to erlang:con‐
223 vert_time_unit(os:system_time(), native, Unit).
224 Note:
226 This time is not a monotonically increasing time.
227 timestamp() -> Timestamp
230 Types:
232 Timestamp = erlang:timestamp()
234 Timestamp = {MegaSecs, Secs, MicroSecs}
235 Returns the current OS system time in the same format as
237 erlang:timestamp/0. The tuple can be used together with function
238 calendar:now_to_universal_time/1 or calendar:now_to_local_time/1
239 to get calendar time. Using the calendar time, together with the
240 MicroSecs part of the return tuple from this function, allows
241 you to log time stamps in high resolution and consistent with
242 the time in the rest of the OS.
243 Example of code formatting a string in format "DD Mon YYYY
245 HH:MM:SS.mmmmmm", where DD is the day of month, Mon is the tex‐
246 tual month name, YYYY is the year, HH:MM:SS is the time, and
247 mmmmmm is the microseconds in six positions:
248 -module(print_time).
250 -export([format_utc_timestamp/0]).
251 format_utc_timestamp() ->
252 TS = {_,_,Micro} = os:timestamp(),
253 {{Year,Month,Day},{Hour,Minute,Second}} =
254 calendar:now_to_universal_time(TS),
255 Mstr = element(Month,{"Jan","Feb","Mar","Apr","May","Jun","Jul",
256 "Aug","Sep","Oct","Nov","Dec"}),
257 io_lib:format("~2w ~s ~4w ~2w:~2..0w:~2..0w.~6..0w",
258 [Day,Mstr,Year,Hour,Minute,Second,Micro]).
259 This module can be used as follows:
261 1> io:format("~s~n",[print_time:format_utc_timestamp()]).
263 29 Apr 2009 9:55:30.051711
264 OS system time can also be retreived by system_time/0 and sys‐
266 tem_time/1.
267 perf_counter() -> Counter
269 Types:
271 Counter = integer()
273 Returns the current performance counter value in perf_counter
275 time unit. This is a highly optimized call that might not be
276 traceable.
277 perf_counter(Unit) -> integer()
279 Types:
281 Unit = erlang:time_unit()
283 Returns a performance counter that can be used as a very fast
285 and high resolution timestamp. This counter is read directly
286 from the hardware or operating system with the same guarantees.
287 This means that two consecutive calls to the function are not
288 guaranteed to be monotonic, though it most likely will be. The
289 performance counter will be converted to the resolution passed
290 as an argument.
291 1> T1 = os:perf_counter(1000),receive after 10000 -> ok end,T2 = os:perf_counter(1000).
293 176525861
294 2> T2 - T1.
295 10004
296 type() -> {Osfamily, Osname}
298 Types:
300 Osfamily = unix | win32
302 Osname = atom()
303 Returns the Osfamily and, in some cases, the Osname of the cur‐
305 rent OS.
306 On Unix, Osname has the same value as uname -s returns, but in
308 lower case. For example, on Solaris 1 and 2, it is sunos.
309 On Windows, Osname is nt.
311 Note:
313 Think twice before using this function. Use module filename if
314 you want to inspect or build filenames in a portable way. Avoid
315 matching on atom Osname.
316 unsetenv(VarName) -> true
319 Types:
321 VarName = env_var_name()
323 Deletes the environment variable VarName.
325 If Unicode filename encoding is in effect (see the erl manual
327 page), the string VarName can contain characters with codepoints
328 > 255.
329 version() -> VersionString | {Major, Minor, Release}
331 Types:
333 VersionString = string()
335 Major = Minor = Release = integer() >= 0
336 Returns the OS version. On most systems, this function returns a
338 tuple, but a string is returned instead if the system has ver‐
339 sions that cannot be expressed as three numbers.
340 Note:
342 Think twice before using this function. If you still need to use
343 it, always call os:type() first.
344Ericsson AB kernel 7.3 os(3)