From f15731c43ae5e8cea424ea40f905c19afa1bd2e4 Mon Sep 17 00:00:00 2001 From: bosch Date: Fri, 8 Mar 2002 20:11:04 +0000 Subject: * 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 --- gcc/ada/g-os_lib.ads | 97 ++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 71 insertions(+), 26 deletions(-) (limited to 'gcc/ada/g-os_lib.ads') 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). -- cgit v1.2.1