_I_n_p_u_t_ _f_r_o_m_ _U_N_I_X_ _f_i_l_e_s_ _e_t_c_.

The following Miranda functions provide an interface to  the  UNIX  file
system from within Miranda expressions:

	read :: [char]->[char]
This takes a string valued argument, which it treats as a UNIX pathname,
and returns the contents of the file or device of that name, also  as  a
string  (i.e.   as  a  list  of  characters).   There  is no end-of-file
character, the termination of the file is indicated simply by the end of
the list of characters.  The Miranda evaluation terminates with an error
message if the file does not exist  or  the  user  does  not  have  read
permission for it.

A special case - the notation `$-' denotes the contents of the  standard
input,  as a list of characters.  Note that multiple occurrences of `$-'
always denote a single shared input stream.  So for example ($-  ++  $-)
reads one lot of data from the terminal and duplicates it.

(See separate subsection on Input/Output of binary data for  the  binary
versions readb and $:-)

	filemode :: [char]->[char]
Takes   a   pathname  and  returns  a  string  representing  the  access
permissions of the current process to the file of that name.  The string
is  empty  if  the  file  does not exist, otherwise it is of length four
containing, in order, the following characters - 'd' if the  file  is  a
directory,  'r'  if it is readable, 'w' if it is writeable, 'x' if it is
executable.  Each character not applicable is replaced by '-'.   So  for
example   "drwx"  is  the  filemode  of  a  directory  with  all  access
permissions, while "-rw-" is the filemode of a normal file with read and
write but no execute permission.

	getenv :: [char]->[char]
Looks  up  the  string  associated with a given name in the current UNIX
environment (see man (2) getenv in the UNIX manual system).  For example
	getenv "HOME"
returns the name of the  current  home  directory.   Returns  the  empty
string if the given name not present in the environment.

	system :: [char]->([char],[char],num)
The effect of `system string' is that a UNIX process is  forked  off  to
execute  `string'  as a shell command (by `/bin/sh').  The result of the
call to `system' is a  triple  containing  the  standard  output,  error
output,  and  exit_status, respectively, resulting from the execution of
the UNIX command.  (The exit_status of a UNIX command is a number in the
range  0..127,  with a non-zero exit status usually indicating some kind
of abnormal event.) Note that inspecting the exit_status will force  the
Miranda  process  to  wait  until the execution of the shell command has
completed - otherwise the two processes proceed concurrently.

If  the  attempt  to  set up a shell process fails, `system' returns the
result ([],errmess,-1), where errmess is an error message.

WARNING - the function `system' provides a  very  general  interface  to
UNIX.   Obviously,  this  can  be  abused  to  cause the evaluation of a
Miranda expression to have side effects  on  the  state  of  the  filing
system.   It is not intended to be used in this way - `system' should be
used only to _o_b_t_a_i_n _i_n_f_o_r_m_a_t_i_o_n about the state of the  world.   If  you
wish  to change the state of the world, this should be done by placing a
`System' message in your output list (see next manual section).

Since reading data from the terminal would constitute a side effect, the
background  process  created  by  `system'  comes  into  being  with its
standard input closed.

_I_m_p_l_e_m_e_n_t_a_t_i_o_n_ _R_e_s_t_r_i_c_t_i_o_n
 `read', `filemode', `getenv', and `system' all require  their  argument
to be at most 1024 characters long.

_N_o_t_e_ _o_n_ _s_y_s_t_e_m_ _r_e_a_d_i_n_g_ _f_u_n_c_t_i_o_n_s_ _a_n_d_ _r_e_f_e_r_e_n_t_i_a_l_ _t_r_a_n_s_p_a_r_e_n_c_y

Although `read', `filemode', `getenv' do not have side effects, they are
not  referentially  transparent  because it cannot be guaranteed that an
expression like
	read "file"
will return the same result if evaluated twice.  Some external event may
have  changed  the  state of the filing system in the meantime.  Clearly
the same  problem  applies  to  `system'  -  consider  for  example  the
expression
	system "date"
which  gets  date-and-time  as  a  string.   Evaluating  this  twice  in
succession is unlikely to produce the same result.

Strictly speaking all calls to `read' and the other  functions  in  this
section  ought to be evaluated with respect to the state-of-the-world as
it existed  before  the  evaluation  of  the  given  Miranda  expression
commenced.   Otherwise  referentially  transparent  behaviour  cannot be
guaranteed.  Enforcing this would appear to require, among other things,
taking   a   copy  of  the  whole  filing  system  before  each  Miranda
command-level evaluation.  For obvious reasons this is not implemented.