* 41intnam.ads, 42intnam.ads, 4aintnam.ads, 4cintnam.ads,

	4dintnam.ads, 4gintnam.ads, 4hintnam.ads, 4lintnam.ads,
	4mintnam.ads, 4pintnam.ads, 4rintnam.ads, 4sintnam.ads,
	4uintnam.ads, 4vcalend.adb, 4zintnam.ads, 52system.ads,
	5amastop.adb, 5asystem.ads, 5ataprop.adb, 5atpopsp.adb,
	5avxwork.ads, 5bosinte.adb, 5bsystem.ads, 5esystem.ads,
	5fsystem.ads, 5ftaprop.adb, 5ginterr.adb, 5gmastop.adb,
	5gsystem.ads, 5gtaprop.adb, 5gtasinf.adb, 5gtasinf.ads,
	5hparame.ads, 5hsystem.ads, 5htaprop.adb, 5htraceb.adb,
	5itaprop.adb, 5ksystem.ads, 5kvxwork.ads, 5lintman.adb,
	5lsystem.ads, 5mvxwork.ads, 5ninmaop.adb, 5nosinte.ads,
	5ntaprop.adb, 5ointerr.adb, 5omastop.adb, 5oosinte.adb,
	5osystem.ads, 5otaprop.adb, 5otaspri.ads, 5pvxwork.ads,
	5qtaprop.adb, 5sintman.adb, 5ssystem.ads, 5staprop.adb,
	5stpopse.adb, 5svxwork.ads, 5tosinte.ads, 5uintman.adb,
	5vasthan.adb, 5vinmaop.adb, 5vinterr.adb, 5vintman.adb,
	5vmastop.adb, 5vparame.ads, 5vsystem.ads, 5vtaprop.adb,
	5vtpopde.adb, 5wmemory.adb, 5wsystem.ads, 5wtaprop.adb,
	5ysystem.ads, 5zinterr.adb, 5zintman.adb, 5zosinte.adb,
	5zosinte.ads, 5zsystem.ads, 5ztaprop.adb, 6vcpp.adb, 6vcstrea.adb,
	7sintman.adb, 7staprop.adb, 7stpopsp.adb, 9drpc.adb,
	Make-lang.in, Makefile.in, a-caldel.adb, a-comlin.ads,
	a-dynpri.adb, a-except.adb, a-except.ads, a-finali.adb,
	a-ncelfu.ads, a-reatim.adb, a-retide.adb, a-stream.ads,
	a-ststio.adb, a-ststio.ads, a-stwifi.adb, a-tags.adb, a-tasatt.adb,
	a-textio.adb, a-tideau.adb, a-tiflau.adb, a-tigeau.adb,
	a-tigeau.ads, a-tiinau.adb, a-timoau.adb, a-witeio.adb,
	a-wtdeau.adb, a-wtenau.adb, a-wtflau.adb, a-wtgeau.adb,
	a-wtgeau.ads, a-wtinau.adb, a-wtmoau.adb, ada-tree.def, ada-tree.h,
	adaint.c, adaint.h, ali-util.adb, ali.adb, ali.ads, atree.adb,
	atree.ads, atree.h, back_end.adb, bcheck.adb, bindgen.adb,
	bindusg.adb, checks.adb, comperr.adb, config-lang.in, csets.adb,
	csets.ads, cstand.adb, cstreams.c, debug.adb, debug.ads, decl.c,
	einfo.adb, einfo.ads, einfo.h, elists.h, errout.adb, errout.ads,
	eval_fat.adb, exp_aggr.adb, exp_attr.adb, exp_ch11.adb,
	exp_ch12.adb, exp_ch13.adb, exp_ch2.adb, exp_ch3.adb, exp_ch3.ads,
	exp_ch4.adb, exp_ch5.adb, exp_ch6.adb, exp_ch7.adb, exp_ch7.ads,
	exp_ch9.adb, exp_ch9.ads, exp_dbug.adb, exp_dbug.ads, exp_disp.ads,
	exp_dist.adb, exp_fixd.adb, exp_intr.adb, exp_pakd.adb,
	exp_prag.adb, exp_strm.adb, exp_util.adb, exp_util.ads,
	expander.adb, expect.c, fe.h, fmap.adb, fmap.ads, fname-uf.adb,
	freeze.adb, frontend.adb, g-awk.adb, g-cgideb.adb, g-comlin.adb,
	g-comlin.ads, g-debpoo.adb, g-dirope.adb, g-dirope.ads,
	g-dyntab.adb, g-expect.adb, g-expect.ads, g-io.ads, g-io_aux.adb,
	g-io_aux.ads, g-locfil.adb, g-locfil.ads, g-os_lib.adb,
	g-os_lib.ads, g-regexp.adb, g-regpat.adb, g-socket.adb,
	g-socket.ads, g-spipat.adb, g-table.adb, g-trasym.adb,
	g-trasym.ads, gigi.h, gmem.c, gnat1drv.adb, gnatbind.adb, gnatbl.c,
	gnatchop.adb, gnatcmd.adb, gnatdll.adb, gnatfind.adb, gnatlbr.adb,
	gnatlink.adb, gnatls.adb, gnatmem.adb, gnatprep.adb, gnatvsn.ads,
	gnatxref.adb, hlo.adb, hostparm.ads, i-cobol.adb, i-cpp.adb,
	i-cstrea.ads, i-cstrin.adb, i-pacdec.adb, i-vxwork.ads,
	impunit.adb, init.c, inline.adb, io-aux.c, layout.adb, lib-load.adb,
	lib-util.adb, lib-writ.adb, lib-writ.ads, lib-xref.adb,
	lib-xref.ads, lib.adb, lib.ads, make.adb, makeusg.adb, mdll.adb,
	memroot.adb, misc.c, mlib-tgt.adb, mlib-utl.adb, mlib-utl.ads,
	mlib.adb, namet.adb, namet.ads, namet.h, nlists.h, nmake.adb,
	nmake.ads, nmake.adt, opt.adb, opt.ads, osint.adb, osint.ads,
	output.adb, output.ads, par-ch2.adb, par-ch3.adb, par-ch5.adb,
	par-prag.adb, par-tchk.adb, par-util.adb, par.adb, prj-attr.adb,
	prj-dect.adb, prj-env.adb, prj-env.ads, prj-nmsc.adb, prj-part.adb,
	prj-proc.adb, prj-strt.adb, prj-tree.adb, prj-tree.ads, prj.adb,
	prj.ads, raise.c, raise.h, repinfo.adb, restrict.adb, restrict.ads,
	rident.ads, rtsfind.adb, rtsfind.ads, s-arit64.adb, s-asthan.adb,
	s-atacco.adb, s-atacco.ads, s-auxdec.adb, s-crc32.adb, s-crc32.ads,
	s-direio.adb, s-fatgen.adb, s-fileio.adb, s-finimp.adb,
	s-gloloc.adb, s-gloloc.ads, s-interr.adb, s-mastop.adb,
	s-mastop.ads, s-memory.adb, s-parame.ads, s-parint.adb,
	s-pooglo.adb, s-pooloc.adb, s-rpc.adb, s-secsta.adb, s-sequio.adb,
	s-shasto.adb, s-soflin.adb, s-soflin.ads, s-stache.adb,
	s-taasde.adb, s-taasde.ads, s-tadeca.adb, s-tadeca.ads,
	s-tadert.adb, s-tadert.ads, s-taenca.adb, s-taenca.ads,
	s-taprob.adb, s-taprop.ads, s-tarest.adb, s-tasdeb.adb,
	s-tasini.adb, s-tasini.ads, s-taskin.adb, s-taskin.ads,
	s-tasque.adb, s-tasque.ads, s-tasren.adb, s-tasren.ads,
	s-tassta.adb, s-tasuti.adb, s-tasuti.ads, s-tataat.adb,
	s-tataat.ads, s-tpoben.adb, s-tpoben.ads, s-tpobop.adb,
	s-tposen.adb, s-tposen.ads, s-traceb.adb, s-traceb.ads,
	s-unstyp.ads, s-widenu.adb, scn-nlit.adb, scn.adb, sem.adb,
	sem_aggr.adb, sem_attr.adb, sem_attr.ads, sem_case.adb,
	sem_ch10.adb, sem_ch11.adb, sem_ch11.ads, sem_ch12.adb,
	sem_ch13.adb, sem_ch13.ads, sem_ch2.adb, sem_ch3.adb, sem_ch3.ads,
	sem_ch4.adb, sem_ch5.adb, sem_ch6.adb, sem_ch6.ads, sem_ch7.adb,
	sem_ch8.adb, sem_ch8.ads, sem_ch9.adb, sem_disp.adb, sem_dist.adb,
	sem_elab.adb, sem_elim.adb, sem_elim.ads, sem_eval.adb,
	sem_intr.adb, sem_mech.adb, sem_prag.adb, sem_res.adb,
	sem_type.adb, sem_util.adb, sem_util.ads, sem_vfpt.adb,
	sem_warn.adb, sinfo.adb, sinfo.ads, sinfo.h, sinput-l.adb,
	sinput-l.ads, sinput.adb, sinput.ads, snames.adb, snames.ads,
	snames.h, sprint.adb, sprint.ads, stringt.adb, stringt.ads,
	stringt.h, style.adb, switch.adb, switch.ads, sysdep.c, system.ads,
	table.adb, targparm.adb, targparm.ads, targtyps.c, tbuild.adb,
	tbuild.ads, tracebak.c, trans.c, tree_gen.adb, tree_io.adb,
	treepr.adb, treepr.ads, treeprs.ads, treeprs.adt, ttypes.ads,
	types.adb, types.ads, types.h, uintp.ads, urealp.ads, usage.adb,
	utils.c, utils2.c, validsw.adb, xnmake.adb, xr_tabls.adb,
	xr_tabls.ads, xref_lib.adb, xref_lib.ads : Merge in ACT changes.

	* 1ssecsta.adb, 1ssecsta.ads, a-chlat9.ads, a-cwila9.ads,
	g-enblsp.adb, g-md5.adb, g-md5.ads, gnatname.adb, gnatname.ads,
	mkdir.c, osint-b.adb, osint-b.ads, osint-c.adb, osint-c.ads,
	osint-l.adb, osint-l.ads, osint-m.adb, osint-m.ads : New files

	* 3lsoccon.ads, 5qparame.ads, 5qvxwork.ads, 5smastop.adb,
	5zparame.ads, gnatmain.adb, gnatmain.ads, gnatpsys.adb : Removed

	* mdllfile.adb, mdllfile.ads, mdlltool.adb, mdlltool.ads : Renamed
	to mdll-fil.ad[bs] and mdll-util.ad[bs]

	* mdll-fil.adb, mdll-fil.ads, mdll-utl.adb, mdll-utl.ads : Renamed
	from mdllfile.ad[bs] and mdlltool.ad[bs]


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@50451 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 71 insertions, 26 deletions

diff --git a/gcc/ada/g-os_lib.ads b/gcc/ada/g-os_lib.ads
index 761e01904de..a878f90e74b 100644
--- a/gcc/ada/g-os_lib.ads
+++ b/gcc/ada/g-os_lib.ads
@@ -8,7 +8,7 @@
 --                                                                          --
 --                            $Revision$
 --                                                                          --
---          Copyright (C) 1995-2001 Free Software Foundation, Inc.          --
+--          Copyright (C) 1995-2002 Free Software Foundation, Inc.          --
 --                                                                          --
 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
 -- terms of the  GNU General Public License as published  by the Free Soft- --
@@ -42,9 +42,7 @@
 
 --  This package tends to use fairly low-level Ada in order to not bring
 --  in large portions of the RTL. For example, functions return access
---  to string as part of avoiding functions returning unconstrained types;
---  types related to dates are defined here instead of using the types
---  from Calendar, since use of Calendar forces linking in of tasking code.
+--  to string as part of avoiding functions returning unconstrained types.
 
 --  Except where specifically noted, these routines are portable across
 --  all GNAT implementations on all supported operating systems.
@@ -56,15 +54,25 @@ package GNAT.OS_Lib is
 pragma Elaborate_Body (OS_Lib);
 
    type String_Access is access all String;
-   --  General purpose string access type
+   --  General purpose string access type. Some of the functions in this
+   --  package allocate string results on the heap, and return a value of
+   --  this type. Note that the caller is responsible for freeing this
+   --  String to avoid memory leaks.
 
    procedure Free is new Unchecked_Deallocation
      (Object => String, Name => String_Access);
+   --  This procedure is provided for freeing returned values of type
+   --  String_Access
 
    type String_List is array (Positive range <>) of String_Access;
    type String_List_Access is access all String_List;
    --  General purpose array and pointer for list of string accesses
 
+   procedure Free (Arg : in out String_List_Access);
+   --  Frees the given array and all strings that its elements reference,
+   --  and then sets the argument to null. Provided for freeing returned
+   --  values of this type (including Argument_List_Access).
+
    ---------------------
    -- Time/Date Stuff --
    ---------------------
@@ -200,7 +208,7 @@ pragma Elaborate_Body (OS_Lib);
      (Old_Name : String;
       New_Name : String;
       Success  : out Boolean);
-   --  Rename a file. Successis set True or False indicating if the rename is
+   --  Rename a file. Success is set True or False indicating if the rename is
    --  successful.
 
    function Read
@@ -316,22 +324,18 @@ pragma Elaborate_Body (OS_Lib);
 
    function Get_Debuggable_Suffix return String_Access;
    --  Return the debuggable suffix convention. Usually this is the same as
-   --  the convention for Get_Executable_Suffix.
-   --
-   --  Note that this function allocates some memory for the returned value.
-   --  This memory needs to be deallocated after use.
+   --  the convention for Get_Executable_Suffix. The result is allocated on
+   --  the heap and should be freed when no longer needed to avoid storage
+   --  leaks.
 
    function Get_Executable_Suffix return String_Access;
-   --  Return the executable suffix convention.
-   --
-   --  Note that this function allocates some memory for the returned value.
-   --  This memory needs to be deallocated after use.
+   --  Return the executable suffix convention. The result is allocated on
+   --  the heap and should be freed when no longer needed to avoid storage
+   --  leaks.
 
    function Get_Object_Suffix return String_Access;
-   --  Return the object suffix convention.
-   --
-   --  Note that this function allocates some memory for the returned value.
-   --  This memory needs to be deallocated after use.
+   --  Return the object suffix convention. The result is allocated on the
+   --  heap and should be freed when no longer needed to avoid storage leaks.
 
    --  The following section contains low-level routines using addresses to
    --  pass file name and executable name. In each routine the name must be
@@ -392,8 +396,21 @@ pragma Elaborate_Body (OS_Lib);
    --  the number of arguments.
 
    subtype Argument_List_Access is String_List_Access;
-   --  Type used to return an Argument_List without dragging in secondary
-   --  stack.
+   --  Type used to return Argument_List without dragging in secondary stack.
+   --  Note that there is a Free procedure declared for this subtype which
+   --  frees the array and all referenced strings.
+
+   procedure Normalize_Arguments (Args : in out Argument_List);
+   --  Normalize all arguments in the list. This ensure that the argument list
+   --  is compatible with the running OS and will works fine with Spawn and
+   --  Non_Blocking_Spawn for example. If Normalize_Arguments is called twice
+   --  on the same list it will do nothing the second time. Note that Spawn
+   --  and Non_Blocking_Spawn call Normalize_Arguments automatically, but
+   --  since there is a guarantee that a second call does nothing, this
+   --  internal call with have no effect if Normalize_Arguments is called
+   --  before calling Spawn. The call to Normalize_Arguments assumes that
+   --  the individual referenced arguments in Argument_List are on the heap,
+   --  and may free them and reallocate if they are modified.
 
    procedure Spawn
      (Program_Name : String;
@@ -408,15 +425,31 @@ pragma Elaborate_Body (OS_Lib);
    --  argument. On some systems (notably Unix systems) a simple file
    --  name may also work (if the executable can be located in the path).
    --
-   --  Note: Arguments that contain spaces and/or quotes such as
-   --        "--GCC=gcc -v" or "--GCC=""gcc-v""" are not portable
-   --        across OSes. They may or may not have the desired effect.
+   --  Note: Arguments in Args that contain spaces and/or quotes such as
+   --  "--GCC=gcc -v" or "--GCC=""gcc -v""" are not portable across all
+   --  operating systems, and would not have the desired effect if they
+   --  were passed directly to the operating system. To avoid this problem,
+   --  Spawn makes an internal call to Normalize_Arguments, which ensures
+   --  that such arguments are modified in a manner that ensures that the
+   --  desired effect is obtained on all operating systems. The caller may
+   --  call Normalize_Arguments explicitly before the call (e.g. to print
+   --  out the exact form of arguments passed to the operating system). In
+   --  this case the guarantee a second call to Normalize_Arguments has no
+   --  effect ensures that the internal call will not affect the result.
+   --  Note that the implicit call to Normalize_Arguments may free and
+   --  reallocate some of the individual arguments.
+   --
+   --  This function will always set Success to False under VxWorks and
+   --  other similar operating systems which have no notion of the concept
+   --  of a dynamically executable file.
 
    function Spawn
      (Program_Name : String;
       Args         : Argument_List)
       return         Integer;
-   --  Like above, but as function returning the exact exit status
+   --  Similar to the above procedure, but returns the actual status returned
+   --  by the operating system, or -1 under VxWorks and any other similar
+   --  operating systems which have no notion of separately spawnable programs.
 
    type Process_Id is private;
    --  A private type used to identify a process activated by the following
@@ -433,6 +466,9 @@ pragma Elaborate_Body (OS_Lib);
    --  This is a non blocking call. The Process_Id of the spawned process
    --  is returned. Parameters are to be used as in Spawn. If Invalid_Id
    --  is returned the program could not be spawned.
+   --
+   --  This function will always return Invalid_Id under VxWorks, since
+   --  there is no notion of executables under this OS.
 
    procedure Wait_Process (Pid : out Process_Id; Success : out Boolean);
    --  Wait for the completion of any of the processes created by previous
@@ -444,12 +480,17 @@ pragma Elaborate_Body (OS_Lib);
    --  has terminated (matching the value returned from Non_Blocking_Spawn).
    --  Success is set to True if this sub-process terminated successfully.
    --  If Pid = Invalid_Id, there were no subprocesses left to wait on.
+   --
+   --  This function will always set success to False under VxWorks, since
+   --  there is no notion of executables under this OS.
 
    function Argument_String_To_List
      (Arg_String : String)
       return       Argument_List_Access;
    --  Take a string that is a program and it's arguments and parse it into
-   --  an Argument_List.
+   --  an Argument_List. Note that the result is allocated on the heap, and
+   --  must be freed by the programmer (when it is no longer needed) to avoid
+   --  memory leaks.
 
    -------------------
    -- Miscellaneous --
@@ -460,7 +501,9 @@ pragma Elaborate_Body (OS_Lib);
    --  to the empty string if the environment variable does not exist
    --  or has an explicit null value (in some operating systems these
    --  are distinct cases, in others they are not; this interface
-   --  abstracts away that difference.
+   --  abstracts away that difference. The argument is allocated on
+   --  the heap (even in the null case), and needs to be freed explicitly
+   --  when no longer needed to avoid memory leaks.
 
    procedure Setenv (Name : String; Value : String);
    --  Set the value of the environment variable Name to Value. This call
@@ -476,10 +519,12 @@ pragma Elaborate_Body (OS_Lib);
 
    procedure OS_Exit (Status : Integer);
    pragma Import (C, OS_Exit, "__gnat_os_exit");
+   pragma No_Return (OS_Exit);
    --  Exit to OS with given status code (program is terminated)
 
    procedure OS_Abort;
    pragma Import (C, OS_Abort, "abort");
+   pragma No_Return (OS_Abort);
    --  Exit to OS signalling an abort (traceback or other appropriate
    --  diagnostic information should be given if possible, or entry made
    --  to the debugger if that is possible).