1os(3)                      Erlang Module Definition                      os(3)
2
3
4

NAME

6       os - Operating system-specific functions.
7

DESCRIPTION

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
14   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
19

DATA TYPES

21       env_var_name() = nonempty_string()
22
23              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
29       env_var_value() = string()
30
31              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
35       env_var_name_value() = nonempty_string()
36
37              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
44       os_command() = atom() | io_lib:chars()
45
46              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
50       os_command_opts() = #{max_size => integer() >= 0 | infinity}
51
52              Options for os:cmd/2
53
54                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

EXPORTS

59       cmd(Command) -> string()
60
61       cmd(Command, Options) -> string()
62
63              Types:
64
65                 Command = os_command()
66                 Options = os_command_opts()
67
68              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
72              Examples:
73
74              LsOut = os:cmd("ls"), % on unix platform
75              DirOut = os:cmd("dir"), % on Win32 platform
76
77              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
82              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
86                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
92                > 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
95       env() -> [{env_var_name(), env_var_value()}]
96
97              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
101              If Unicode filename encoding is in effect (see  the  erl  manual
102              page), the strings can contain characters with codepoints > 255.
103
104       find_executable(Name) -> Filename | false
105
106       find_executable(Name, Path) -> Filename | false
107
108              Types:
109
110                 Name = Path = Filename = string()
111
112              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
117              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
121       getenv() -> [env_var_name_value()]
122
123              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
128              If  Unicode  filename  encoding is in effect (see the erl manual
129              page), the strings can contain characters with codepoints > 255.
130
131              Consider using env/0 for a nicer 2-tuple format.
132
133       getenv(VarName) -> Value | false
134
135              Types:
136
137                 VarName = env_var_name()
138                 Value = env_var_value()
139
140              Returns the Value of the environment variable VarName, or  false
141              if the environment variable is undefined.
142
143              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
147       getenv(VarName, DefaultValue) -> Value
148
149              Types:
150
151                 VarName = env_var_name()
152                 DefaultValue = Value = env_var_value()
153
154              Returns  the  Value  of the environment variable VarName, or De‐
155              faultValue if the environment variable is undefined.
156
157              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
161       getpid() -> Value
162
163              Types:
164
165                 Value = string()
166
167              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
174       putenv(VarName, Value) -> true
175
176              Types:
177
178                 VarName = env_var_name()
179                 Value = env_var_value()
180
181              Sets a new Value for environment variable VarName.
182
183              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
187              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
191       set_signal(Signal, Option) -> ok
192
193              Types:
194
195                 Signal =
196                     sighup  | sigquit | sigabrt | sigalrm | sigterm | sigusr1
197                 |
198                     sigusr2 | sigchld | sigstop | sigtstp
199                 Option = default | handle | ignore
200
201              Enables or disables OS signals.
202
203              Each signal my be set to one of the following options:
204
205                ignore:
206                   This signal will be ignored.
207
208                default:
209                   This signal will use the default signal handler for the op‐
210                  erating system.
211
212                handle:
213                   This  signal  will  notify erl_signal_server when it is re‐
214                  ceived by the Erlang runtime system.
215
216       system_time() -> integer()
217
218              Returns the current OS system time in native time unit.
219
220          Note:
221              This time is not a monotonically increasing time.
222
223
224       system_time(Unit) -> integer()
225
226              Types:
227
228                 Unit = erlang:time_unit()
229
230              Returns the current OS  system  time  converted  into  the  Unit
231              passed as argument.
232
233              Calling   os:system_time(Unit)   is  equivalent  to  erlang:con‐
234              vert_time_unit(os:system_time(), native, Unit).
235
236          Note:
237              This time is not a monotonically increasing time.
238
239
240       timestamp() -> Timestamp
241
242              Types:
243
244                 Timestamp = erlang:timestamp()
245                   Timestamp = {MegaSecs, Secs, MicroSecs}
246
247              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
255              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
260              -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
271              This module can be used as follows:
272
273              1> io:format("~s~n",[print_time:format_utc_timestamp()]).
274              29 Apr 2009  9:55:30.051711
275
276              OS  system  time can also be retrieved by system_time/0 and sys‐
277              tem_time/1.
278
279       perf_counter() -> Counter
280
281              Types:
282
283                 Counter = integer()
284
285              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
289       perf_counter(Unit) -> integer()
290
291              Types:
292
293                 Unit = erlang:time_unit()
294
295              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
303              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
308       type() -> {Osfamily, Osname}
309
310              Types:
311
312                 Osfamily = unix | win32
313                 Osname = atom()
314
315              Returns the Osfamily and, in some cases, the Osname of the  cur‐
316              rent OS.
317
318              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
321              On Windows, Osname is nt.
322
323          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
328
329       unsetenv(VarName) -> true
330
331              Types:
332
333                 VarName = env_var_name()
334
335              Deletes the environment variable VarName.
336
337              If Unicode filename encoding is in effect (see  the  erl  manual
338              page), the string VarName can contain characters with codepoints
339              > 255.
340
341       version() -> VersionString | {Major, Minor, Release}
342
343              Types:
344
345                 VersionString = string()
346                 Major = Minor = Release = integer() >= 0
347
348              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
352          Note:
353              Think twice before using this function. If you still need to use
354              it, always call os:type() first.
355
356
357
358
359Ericsson AB                     kernel 8.5.4.2                           os(3)
Impressum