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       find_executable(Name) -> Filename | false
96
97       find_executable(Name, Path) -> Filename | false
98
99              Types:
100
101                 Name = Path = Filename = string()
102
103              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
108              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
112       getenv() -> [env_var_name_value()]
113
114              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
119              If Unicode filename encoding is in effect (see  the  erl  manual
120              page), the strings can contain characters with codepoints > 255.
121
122       getenv(VarName) -> Value | false
123
124              Types:
125
126                 VarName = env_var_name()
127                 Value = env_var_value()
128
129              Returns  the Value of the environment variable VarName, or false
130              if the environment variable is undefined.
131
132              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
136       getenv(VarName, DefaultValue) -> Value
137
138              Types:
139
140                 VarName = env_var_name()
141                 DefaultValue = Value = env_var_value()
142
143              Returns the Value of the environment variable  VarName,  or  De‐
144              faultValue if the environment variable is undefined.
145
146              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
150       getpid() -> Value
151
152              Types:
153
154                 Value = string()
155
156              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
163       putenv(VarName, Value) -> true
164
165              Types:
166
167                 VarName = env_var_name()
168                 Value = env_var_value()
169
170              Sets a new Value for environment variable VarName.
171
172              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
176              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
180       set_signal(Signal, Option) -> ok
181
182              Types:
183
184                 Signal =
185                     sighup | sigquit | sigabrt | sigalrm | sigterm |  sigusr1
186                 |
187                     sigusr2 | sigchld | sigstop | sigtstp
188                 Option = default | handle | ignore
189
190              Enables or disables OS signals.
191
192              Each signal my be set to one of the following options:
193
194                ignore:
195                   This signal will be ignored.
196
197                default:
198                   This signal will use the default signal handler for the op‐
199                  erating system.
200
201                handle:
202                   This signal will notify erl_signal_server when  it  is  re‐
203                  ceived by the Erlang runtime system.
204
205       system_time() -> integer()
206
207              Returns the current OS system time in native time unit.
208
209          Note:
210              This time is not a monotonically increasing time.
211
212
213       system_time(Unit) -> integer()
214
215              Types:
216
217                 Unit = erlang:time_unit()
218
219              Returns  the  current  OS  system  time  converted into the Unit
220              passed as argument.
221
222              Calling  os:system_time(Unit)  is  equivalent   to   erlang:con‐
223              vert_time_unit(os:system_time(), native, Unit).
224
225          Note:
226              This time is not a monotonically increasing time.
227
228
229       timestamp() -> Timestamp
230
231              Types:
232
233                 Timestamp = erlang:timestamp()
234                   Timestamp = {MegaSecs, Secs, MicroSecs}
235
236              Returns  the  current  OS  system time in the same format as er‐
237              lang: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
244              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 mm‐
247              mmmm is the microseconds in six positions:
248
249              -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
260              This module can be used as follows:
261
262              1> io:format("~s~n",[print_time:format_utc_timestamp()]).
263              29 Apr 2009  9:55:30.051711
264
265              OS system time can also be retreived by system_time/0  and  sys‐
266              tem_time/1.
267
268       perf_counter() -> Counter
269
270              Types:
271
272                 Counter = integer()
273
274              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
278       perf_counter(Unit) -> integer()
279
280              Types:
281
282                 Unit = erlang:time_unit()
283
284              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
292              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
297       type() -> {Osfamily, Osname}
298
299              Types:
300
301                 Osfamily = unix | win32
302                 Osname = atom()
303
304              Returns  the Osfamily and, in some cases, the Osname of the cur‐
305              rent OS.
306
307              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
310              On Windows, Osname is nt.
311
312          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
317
318       unsetenv(VarName) -> true
319
320              Types:
321
322                 VarName = env_var_name()
323
324              Deletes the environment variable VarName.
325
326              If  Unicode  filename  encoding is in effect (see the erl manual
327              page), the string VarName can contain characters with codepoints
328              > 255.
329
330       version() -> VersionString | {Major, Minor, Release}
331
332              Types:
333
334                 VersionString = string()
335                 Major = Minor = Release = integer() >= 0
336
337              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
341          Note:
342              Think twice before using this function. If you still need to use
343              it, always call os:type() first.
344
345
346
347
348Ericsson AB                     kernel 7.3.1.1                           os(3)
Impressum