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
15 os_command() = atom() | io_lib:chars()
16 os_command_opts() = #{max_size => integer() >= 0 | infinity}
18 Options for os:cmd/2
20 max_size:
22 The maximum size of the data returned by the os:cmd call.
23 See the os:cmd/2 documentation for more details.
24
26 cmd(Command) -> string()
27 cmd(Command, Options) -> string()
29 Types:
31 Command = os_command()
33 Options = os_command_opts()
34 Executes Command in a command shell of the target OS, captures
36 the standard output of the command, and returns this result as a
37 string.
38 Examples:
40 LsOut = os:cmd("ls"), % on unix platform
42 DirOut = os:cmd("dir"), % on Win32 platform
43 Notice that in some cases, standard output of a command when
45 called from another program (for example, os:cmd/1) can differ,
46 compared with the standard output of the command when called
47 directly from an OS command shell.
48 os:cmd/2 was added in kernel-5.5 (OTP-20.2.1). It makes it pos‐
50 sible to pass an options map as the second argument in order to
51 control the behaviour of os:cmd. The possible options are:
52 max_size:
54 The maximum size of the data returned by the os:cmd call.
55 This option is a safety feature that should be used when the
56 command executed can return a very large, possibly infinite,
57 result.
58 > os:cmd("cat /dev/zero", #{ max_size => 20 }).
60 [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
61 find_executable(Name) -> Filename | false
63 find_executable(Name, Path) -> Filename | false
65 Types:
67 Name = Path = Filename = string()
69 These two functions look up an executable program, with the
71 specified name and a search path, in the same way as the under‐
72 lying OS. find_executable/1 uses the current execution path
73 (that is, the environment variable PATH on Unix and Windows).
74 Path, if specified, is to conform to the syntax of execution
76 paths on the OS. Returns the absolute filename of the executable
77 program Name, or false if the program is not found.
78 getenv() -> [string()]
80 Returns a list of all environment variables. Each environment
82 variable is expressed as a single string on the format "Var‐
83 Name=Value", where VarName is the name of the variable and Value
84 its value.
85 If Unicode filename encoding is in effect (see the erl manual
87 page), the strings can contain characters with codepoints > 255.
88 getenv(VarName) -> Value | false
90 Types:
92 VarName = Value = string()
94 Returns the Value of the environment variable VarName, or false
96 if the environment variable is undefined.
97 If Unicode filename encoding is in effect (see the erl manual
99 page), the strings VarName and Value can contain characters with
100 codepoints > 255.
101 getenv(VarName, DefaultValue) -> Value
103 Types:
105 VarName = DefaultValue = Value = string()
107 Returns the Value of the environment variable VarName, or
109 DefaultValue if the environment variable is undefined.
110 If Unicode filename encoding is in effect (see the erl manual
112 page), the strings VarName and Value can contain characters with
113 codepoints > 255.
114 getpid() -> Value
116 Types:
118 Value = string()
120 Returns the process identifier of the current Erlang emulator in
122 the format most commonly used by the OS environment. Returns
123 Value as a string containing the (usually) numerical identifier
124 for a process. On Unix, this is typically the return value of
125 the getpid() system call. On Windows, the process id as returned
126 by the GetCurrentProcessId() system call is used.
127 putenv(VarName, Value) -> true
129 Types:
131 VarName = Value = string()
133 Sets a new Value for environment variable VarName.
135 If Unicode filename encoding is in effect (see the erl manual
137 page), the strings VarName and Value can contain characters with
138 codepoints > 255.
139 On Unix platforms, the environment is set using UTF-8 encoding
141 if Unicode filename translation is in effect. On Windows, the
142 environment is set using wide character interfaces.
143 set_signal(Signal, Option) -> ok
145 Types:
147 Signal =
149 sighup |
150 sigquit |
151 sigabrt |
152 sigalrm |
153 sigterm |
154 sigusr1 |
155 sigusr2 |
156 sigchld |
157 sigstop |
158 sigtstp
159 Option = default | handle | ignore
160 Enables or disables OS signals.
162 Each signal my be set to one of the following options:
164 ignore:
166 This signal will be ignored.
167 default:
169 This signal will use the default signal handler for the
170 operating system.
171 handle:
173 This signal will notify erl_signal_server when it is
174 received by the Erlang runtime system.
175 system_time() -> integer()
177 Returns the current OS system time in native time unit.
179 Note:
181 This time is not a monotonically increasing time.
182 system_time(Unit) -> integer()
185 Types:
187 Unit = erlang:time_unit()
189 Returns the current OS system time converted into the Unit
191 passed as argument.
192 Calling os:system_time(Unit) is equivalent to erlang:con‐
194 vert_time_unit(os:system_time(), native, Unit).
195 Note:
197 This time is not a monotonically increasing time.
198 timestamp() -> Timestamp
201 Types:
203 Timestamp = erlang:timestamp()
205 Timestamp = {MegaSecs, Secs, MicroSecs}
206 Returns the current OS system time in the same format as
208 erlang:timestamp/0. The tuple can be used together with function
209 calendar:now_to_universal_time/1 or calendar:now_to_local_time/1
210 to get calendar time. Using the calendar time, together with the
211 MicroSecs part of the return tuple from this function, allows
212 you to log time stamps in high resolution and consistent with
213 the time in the rest of the OS.
214 Example of code formatting a string in format "DD Mon YYYY
216 HH:MM:SS.mmmmmm", where DD is the day of month, Mon is the tex‐
217 tual month name, YYYY is the year, HH:MM:SS is the time, and
218 mmmmmm is the microseconds in six positions:
219 -module(print_time).
221 -export([format_utc_timestamp/0]).
222 format_utc_timestamp() ->
223 TS = {_,_,Micro} = os:timestamp(),
224 {{Year,Month,Day},{Hour,Minute,Second}} =
225 calendar:now_to_universal_time(TS),
226 Mstr = element(Month,{"Jan","Feb","Mar","Apr","May","Jun","Jul",
227 "Aug","Sep","Oct","Nov","Dec"}),
228 io_lib:format("~2w ~s ~4w ~2w:~2..0w:~2..0w.~6..0w",
229 [Day,Mstr,Year,Hour,Minute,Second,Micro]).
230 This module can be used as follows:
232 1> io:format("~s~n",[print_time:format_utc_timestamp()]).
234 29 Apr 2009 9:55:30.051711
235 OS system time can also be retreived by system_time/0 and sys‐
237 tem_time/1.
238 perf_counter() -> Counter
240 Types:
242 Counter = integer()
244 Returns the current performance counter value in perf_counter
246 time unit. This is a highly optimized call that might not be
247 traceable.
248 perf_counter(Unit) -> integer()
250 Types:
252 Unit = erlang:time_unit()
254 Returns a performance counter that can be used as a very fast
256 and high resolution timestamp. This counter is read directly
257 from the hardware or operating system with the same guarantees.
258 This means that two consecutive calls to the function are not
259 guaranteed to be monotonic, though it most likely will be. The
260 performance counter will be converted to the resolution passed
261 as an argument.
262 1> T1 = os:perf_counter(1000),receive after 10000 -> ok end,T2 = os:perf_counter(1000).
264 176525861
265 2> T2 - T1.
266 10004
267 type() -> {Osfamily, Osname}
269 Types:
271 Osfamily = unix | win32
273 Osname = atom()
274 Returns the Osfamily and, in some cases, the Osname of the cur‐
276 rent OS.
277 On Unix, Osname has the same value as uname -s returns, but in
279 lower case. For example, on Solaris 1 and 2, it is sunos.
280 On Windows, Osname is nt.
282 Note:
284 Think twice before using this function. Use module filename if
285 you want to inspect or build filenames in a portable way. Avoid
286 matching on atom Osname.
287 unsetenv(VarName) -> true
290 Types:
292 VarName = string()
294 Deletes the environment variable VarName.
296 If Unicode filename encoding is in effect (see the erl manual
298 page), the string VarName can contain characters with codepoints
299 > 255.
300 version() -> VersionString | {Major, Minor, Release}
302 Types:
304 VersionString = string()
306 Major = Minor = Release = integer() >= 0
307 Returns the OS version. On most systems, this function returns a
309 tuple, but a string is returned instead if the system has ver‐
310 sions that cannot be expressed as three numbers.
311 Note:
313 Think twice before using this function. If you still need to use
314 it, always call os:type() first.
315Ericsson AB kernel 5.4.3.2 os(3)