Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

NAME

       os - Operating System Specific Functions

DESCRIPTION

       The  functions  in  this  module  are  operating  system  specific.  Careless use of these
       functions will result in programs that will only run on a specific platform. On the  other
       hand, with careful use these functions can be of help in enabling a program to run on most
       platforms.

EXPORTS

       cmd(Command) -> string()

              Types:

                 Command = atom() | io_lib:chars()

              Executes Command in a command shell of the target OS, captures the standard  output
              of  the command and returns this result as a string. This function is a replacement
              of the previous unix:cmd/1; on a Unix platform they are equivalent.

              Examples:

              LsOut = os:cmd("ls"), % on unix platform
              DirOut = os:cmd("dir"), % on Win32 platform

              Note that in some cases, standard output of a  command  when  called  from  another
              program  (for example, os:cmd/1) may differ, compared to the standard output of the
              command when called directly from an OS command shell.

       find_executable(Name) -> Filename | false

       find_executable(Name, Path) -> Filename | false

              Types:

                 Name = Path = Filename = string()

              These two functions look up an executable program given its name and a search path,
              in  the  same  way  as  the underlying operating system. find_executable/1 uses the
              current execution path  (that  is,  the  environment  variable  PATH  on  Unix  and
              Windows).

              Path,  if  given,  should conform to the syntax of execution paths on the operating
              system. The absolute filename of the executable program Name is returned, or  false
              if the program was not found.

       getenv() -> [string()]

              Returns  a list of all environment variables. Each environment variable is given as
              a single string on the format "VarName=Value", where VarName is  the  name  of  the
              variable and Value its value.

              If  Unicode  file name encoding is in effect (see the erl manual page), the strings
              may contain characters with codepoints > 255.

       getenv(VarName) -> Value | false

              Types:

                 VarName = Value = string()

              Returns the Value of the environment variable VarName, or false if the  environment
              variable is undefined.

              If  Unicode  file name encoding is in effect (see the erl manual page), the strings
              (both VarName and Value) may contain characters with codepoints > 255.

       getpid() -> Value

              Types:

                 Value = string()

              Returns the process identifier of the current Erlang emulator in  the  format  most
              commonly  used  by  the operating system environment. Value is returned as a string
              containing the (usually) numerical identifier for  a  process.  On  Unix,  this  is
              typically  the return value of the getpid() system call. On Windows, the process id
              as returned by the GetCurrentProcessId() system call is used.

       putenv(VarName, Value) -> true

              Types:

                 VarName = Value = string()

              Sets a new Value for the environment variable VarName.

              If Unicode filename encoding is in effect (see the erl manual  page),  the  strings
              (both VarName and Value) may contain characters with codepoints > 255.

              On Unix platforms, the environment will be set using UTF-8 encoding if Unicode file
              name translation is in effect.  On  Windows  the  environment  is  set  using  wide
              character interfaces.

       timestamp() -> Timestamp

              Types:

                 Timestamp = erlang:timestamp()
                   Timestamp = {MegaSecs, Secs, MicroSecs}

              Returns  a  tuple  in  the same format as erlang:now/0. The difference is that this
              function returns what the operating system thinks  (a.k.a.  the  wall  clock  time)
              without  any attempts at time correction. The result of two different calls to this
              function is not guaranteed to be different.

              The most obvious use for this function is logging. The tuple can be  used  together
              with  the function calendar:now_to_universal_time/1 or calendar:now_to_local_time/1
              to get calendar time. Using the calendar time together with the MicroSecs  part  of
              the return tuple from this function allows you to log timestamps in high resolution
              and consistent with the time in the rest of the operating system.

              Example of code formatting a string in the format "DD  Mon  YYYY  HH:MM:SS.mmmmmm",
              where  DD  is  the  day  of month, Mon is the textual month name, YYYY is the year,
              HH:MM:SS is the time and mmmmmm is the microseconds in six positions:

              -module(print_time).
              -export([format_utc_timestamp/0]).
              format_utc_timestamp() ->
                  TS = {_,_,Micro} = os:timestamp(),
                  {{Year,Month,Day},{Hour,Minute,Second}} =
                   calendar:now_to_universal_time(TS),
                  Mstr = element(Month,{"Jan","Feb","Mar","Apr","May","Jun","Jul",
                               "Aug","Sep","Oct","Nov","Dec"}),
                  io_lib:format("~2w ~s ~4w ~2w:~2..0w:~2..0w.~6..0w",
                          [Day,Mstr,Year,Hour,Minute,Second,Micro]).

              The module above could be used in the following way:

              1> io:format("~s~n",[print_time:format_utc_timestamp()]).
              29 Apr 2009  9:55:30.051711

       type() -> {Osfamily, Osname}

              Types:

                 Osfamily = unix | win32
                 Osname = atom()

              Returns the Osfamily and, in some cases, Osname of the current operating system.

              On Unix, Osname will have same value as uname -s returns, but in  lower  case.  For
              example, on Solaris 1 and 2, it will be sunos.

              In Windows, Osname will be either nt (on Windows NT), or windows (on Windows 95).

          Note:
              Think  twice  before  using  this  function. Use the filename module if you want to
              inspect or build file names in a portable way. Avoid matching on the Osname atom.

       unsetenv(VarName) -> true

              Types:

                 VarName = string()

              Deletes the environment variable VarName.

              If Unicode filename encoding is in effect (see the erl  manual  page),  the  string
              (VarName) may contain characters with codepoints > 255.

       version() -> VersionString | {Major, Minor, Release}

              Types:

                 VersionString = string()
                 Major = Minor = Release = integer() >= 0

              Returns  the  operating  system  version.  On most systems, this function returns a
              tuple, but a string will be returned instead  if  the  system  has  versions  which
              cannot be expressed as three numbers.

          Note:
              Think  twice  before  using this function. If you still need to use it, always call
              os:type() first.