Further modernise the stk(3) stack routines (re: f619b48)

*** Void pointers ***

The stk(3) interface used char pointers throughout for K&R C and
C++ compatibility. I gave up all pretense of that long ago (see
a34e831) and we now use C89/C90 as our lowest common denominator,
so we're allowed to use void pointers.

The stkalloc(), stkset(), stkseek() and stkfreeze() functions now
return void* instead of char*. This should compatible with old code
as implicit typecasts are done. I scanned all the uses of these in
current code as well as the complete ast-open-history repo and
didn't find problems, nor does 'clang -Wall' throw any warnings.

So, no changes should be required. However, this change does allow
eliminating a lot of verbose/annoying typecasts from the code, as
void pointers can be assigned/passed to all sorts of types. This
commit removes those explicit typecasts, improving code legibility.

The stkcopy() and stkptr() functions continue to return char*, as
the first is purely for copying strings and the second's result is
often dereferenced directly to read individual bytes on the stack.

*** Deprecate/disuse stkinstall() ***

The old stak(3) interface did not pass stack pointers to every
function, so to use multiple stacks, one had to be "installed"
(activated) and there was only one "active" stack at the time. The
new interface has stkinstall() for backward compatibility with this
practice; it updates the stack that stkstd refers to. But this is
completely redundant as it's much more efficient to simply change
the pointer passed to the stack functions. So stkinstall() is
deprecated and its use replaced accordingly in the following files:
- src/lib/libast/misc/glob.c
- src/cmd/ksh93/sh/parse.c
- src/cmd/ksh93/sh/trestore.c

*** Add stkoverflow() ***

In typical AT&T fashion, stkinstall() had another, unrelated
function: set a pointer to a char* function called when the system
runs out of memory to allocate new stack frames. It can either find
memory somewhere and return a pointer, or error out. stkinstall()
did not allow unsetting this function pointer to restore the
default. This commit adds a replacement stkoverflow() function that
sets this function (now of type void*) or restores the default.
(The unset functionality is currently unused but may come in handy
someday and in any case it's trivial.)
This is currently used in:
- src/cmd/ksh93/sh/init.c

*** Bump libast API version ***

In src/lib/libast/features/api, the libast API version is bumped to
20240227 due to the changes above.

*** Rework stk(3) manual page ***

Rewrote parts to match current practice, e.g., removed references
to "the active stack" which never really applied to stk(3).

*** Restore stak.h ***

Perhaps it was overzealous to remove that in the referenced commit.
It's a small header file that simply maps the old stak(3) interface
onto stk(3) using some #defines. It remains unused, but the cost of
having it is negligible and restoring it restores compatbility with
old code we might want to test or backport at some point.

Author: McDutchie

src/cmd/ksh93/bltins/cd_pwd.c

@@ -2,7 +2,7 @@
 *                                                                      *
 *               This software is part of the ast package               *
 *          Copyright (c) 1982-2012 AT&T Intellectual Property          *
-*          Copyright (c) 2020-2023 Contributors to ksh 93u+m           *
+*          Copyright (c) 2020-2024 Contributors to ksh 93u+m           *
 *                      and is licensed under the                       *
 *                 Eclipse Public License, Version 2.0                  *
 *                                                                      *
@@ -171,7 +171,7 @@ int	b_cd(int argc, char *argv[],Shbltin_t *context)
 #endif /* _WINIX */
 		if(*stkptr(sh.stk,PATH_OFFSET)!='/')
 		{
-			char *last=(char*)stkfreeze(sh.stk,1);
+			char *last = stkfreeze(sh.stk,1);
 			stkseek(sh.stk,PATH_OFFSET);
 			sfputr(sh.stk,oldpwd,-1);
 			/* don't add '/' if oldpwd is / itself */

src/cmd/ksh93/bltins/getopts.c

@@ -2,7 +2,7 @@
 *                                                                      *
 *               This software is part of the ast package               *
 *          Copyright (c) 1982-2012 AT&T Intellectual Property          *
-*          Copyright (c) 2020-2023 Contributors to ksh 93u+m           *
+*          Copyright (c) 2020-2024 Contributors to ksh 93u+m           *
 *                      and is licensed under the                       *
 *                 Eclipse Public License, Version 2.0                  *
 *                                                                      *
@@ -41,7 +41,7 @@ static int infof(Opt_t* op, Sfio_t* sp, const char* s, Optdisc_t* dp)
 #endif /* SHOPT_NAMESPACE */
 	{
 		int savtop = stktell(stkp);
-		char *savptr = stkfreeze(stkp,0);
+		void *savptr = stkfreeze(stkp,0);
 		sfputc(stkp,'$');
 		sfputc(stkp,'(');
 		sfputr(stkp,s,')');

src/cmd/ksh93/bltins/test.c

@@ -2,7 +2,7 @@
 *                                                                      *
 *               This software is part of the ast package               *
 *          Copyright (c) 1982-2012 AT&T Intellectual Property          *
-*          Copyright (c) 2020-2023 Contributors to ksh 93u+m           *
+*          Copyright (c) 2020-2024 Contributors to ksh 93u+m           *
 *                      and is licensed under the                       *
 *                 Eclipse Public License, Version 2.0                  *
 *                                                                      *
@@ -665,7 +665,7 @@ int sh_access(const char *name, int mode)
 					maxgroups = (int)astconf_long(CONF_NGROUPS_MAX);
 				}
 			}
-			groups = (gid_t*)stkalloc(sh.stk,(maxgroups+1)*sizeof(gid_t));
+			groups = stkalloc(sh.stk,(maxgroups+1)*sizeof(gid_t));
 			n = getgroups(maxgroups,groups);
 			while(--n >= 0)
 			{

src/cmd/ksh93/bltins/typeset.c

@@ -233,7 +233,7 @@ int    b_typeset(int argc,char *argv[],Shbltin_t *context)
 	}
 	else if(argv[0][0] != 't')		/* not <t>ypeset */
 	{
-		char **new_argv = (char **)stkalloc(sh.stk, (argc + 2) * sizeof(char*));
+		char **new_argv = stkalloc(sh.stk, (argc + 2) * sizeof(char*));
 		error_info.id = new_argv[0] = SYSTYPESET->nvname;
 		if(argv[0][0] == 'a')		/* <a>utoload == typeset -fu */
 			new_argv[1] = "-fu";
@@ -1607,7 +1607,7 @@ static void print_scan(Sfio_t *file, int flag, Dt_t *root, int option,struct tda
 	if(flag==NV_LTOU || flag==NV_UTOL)
 		tp->scanmask |= NV_UTOL|NV_LTOU;
 	namec = nv_scan(root, nullscan, tp, tp->scanmask, flag&~NV_IARRAY);
-	argv = tp->argnam  = (char**)stkalloc(sh.stk,(namec+1)*sizeof(char*));
+	argv = tp->argnam  = stkalloc(sh.stk,(namec+1)*sizeof(char*));
 	namec = nv_scan(root, pushname, tp, tp->scanmask, flag&~NV_IARRAY);
 	if(mbcoll())
 		strsort(argv,namec,strcoll);

src/cmd/ksh93/edit/completion.c

@@ -277,8 +277,8 @@ int ed_expand(Edit_t *ep, char outbuff[],int *cur,int *eol,int mode, int count)
 			ep->e_nlist = 0;
 		}
 	}
-	comptr = (struct comnod*)stkalloc(sh.stk,sizeof(struct comnod));
-	ap = (struct argnod*)stkseek(sh.stk,ARGVAL);
+	comptr = stkalloc(sh.stk,sizeof(struct comnod));
+	ap = stkseek(sh.stk,ARGVAL);
 #if SHOPT_MULTIBYTE
 	{
 		int c = *cur;
@@ -368,7 +368,7 @@ int ed_expand(Edit_t *ep, char outbuff[],int *cur,int *eol,int mode, int count)
 		}
 		if(addstar)
 			sfputc(sh.stk,addstar);
-		ap = (struct argnod*)stkfreeze(sh.stk,1);
+		ap = stkfreeze(sh.stk,1);
 	}
 	if(mode!='*')
 		sh_onoption(SH_MARKDIRS);

src/cmd/ksh93/features/externs

@@ -83,7 +83,7 @@ tst	note{ determining default number of extra bytes per argument for arguments l
 				int bytec;
 
 				error_info.id="_arg_extrabytes test (child)";
-				argv = (char **)stkalloc(stkstd, (argmax / 2 + 1) * sizeof(char*));
+				argv = stkalloc(stkstd, (argmax / 2 + 1) * sizeof(char*));
 				argc = bytec = 0;
 				while(bytec < argmax)
 				{

src/cmd/ksh93/include/defs.h

@@ -2,7 +2,7 @@
 *                                                                      *
 *               This software is part of the ast package               *
 *          Copyright (c) 1982-2012 AT&T Intellectual Property          *
-*          Copyright (c) 2020-2023 Contributors to ksh 93u+m           *
+*          Copyright (c) 2020-2024 Contributors to ksh 93u+m           *
 *                      and is licensed under the                       *
 *                 Eclipse Public License, Version 2.0                  *
 *                                                                      *

src/cmd/ksh93/sh/args.c

@@ -681,7 +681,7 @@ char **sh_argbuild(int *nargs, const struct comnod *comptr,int flag)
 		 * TODO: find/fix root cause, eliminate argi
 		 */
 		argn = *nargs + 1;	/* allow room to prepend args */
-		comargn=(char**)stkalloc(sh.stk,(unsigned)(argn+1)*sizeof(char*));
+		comargn = stkalloc(sh.stk,(unsigned)(argn+1)*sizeof(char*));
 		comargm = comargn += argn;
 		*comargn = NULL;
 		if(!argp)
@@ -724,7 +724,7 @@ struct argnod *sh_argprocsub(struct argnod *argp)
 	int savestates = sh_getstate();
 	char savejobcontrol = job.jobcontrol;
 	unsigned int savesubshell = sh.subshell;
-	ap = (struct argnod*)stkseek(sh.stk,ARGVAL);
+	ap = stkseek(sh.stk,ARGVAL);
 	ap->argflag |= ARG_MAKE;
 	ap->argflag &= ~ARG_RAW;
 	fd = argp->argflag&ARG_RAW;
@@ -752,7 +752,7 @@ struct argnod *sh_argprocsub(struct argnod *argp)
 	sfputr(sh.stk,sh.fifo,0);
 #endif /* SHOPT_DEVFD */
 	sfputr(sh.stk,fmtint(pv[fd],1),0);
-	ap = (struct argnod*)stkfreeze(sh.stk,0);
+	ap = stkfreeze(sh.stk,0);
 	sh.inpipe = sh.outpipe = 0;
 	/* turn off job control */
 	sh_offstate(SH_INTERACTIVE);

src/cmd/ksh93/sh/expand.c

@@ -115,7 +115,7 @@ int path_expand(const char *pattern, struct argnod **arghead, int musttrim)
 		 */
 		if((ap = (struct argnod*)gp->gl_list) && !ap->argnxt.ap && strcmp(ap->argval,trimmedpat)==0)
 		{
-			gp->gl_list = (globlist_t*)stkalloc(sh.stk,ARGVAL+strlen(pattern)+1);
+			gp->gl_list = stkalloc(sh.stk,ARGVAL+strlen(pattern)+1);
 			memcpy(gp->gl_list,ap,ARGVAL);  /* copy fields *before* argval/gl_path */
 			strcpy(gp->gl_list->gl_path,pattern);
 		}
@@ -149,9 +149,9 @@ static int scantree(Dt_t *tree, const char *pattern, struct argnod **arghead)
 			continue;
 		if(strmatch(cp=nv_name(np),pattern))
 		{
-			(void)stkseek(sh.stk,ARGVAL);
+			stkseek(sh.stk,ARGVAL);
 			sfputr(sh.stk,cp,-1);
-			ap = (struct argnod*)stkfreeze(sh.stk,1);
+			ap = stkfreeze(sh.stk,1);
 			ap->argbegin = NULL;
 			ap->argchn.ap = *arghead;
 			ap->argflag = ARG_RAW|ARG_MAKE;
@@ -431,13 +431,13 @@ int path_generate(struct argnod *todo, struct argnod **arghead, int musttrim)
 		brace = *cp;
 		*cp = 0;
 		sh_sigcheck();
-		ap = (struct argnod*)stkseek(sh.stk,ARGVAL);
+		ap = stkseek(sh.stk,ARGVAL);
 		ap->argflag = ARG_RAW;
 		ap->argchn.ap = todo;
 		sfputr(sh.stk,apin->argval,-1);
 		sfputr(sh.stk,pat,-1);
 		sfputr(sh.stk,rescan,-1);
-		todo = ap = (struct argnod*)stkfreeze(sh.stk,1);
+		todo = ap = stkfreeze(sh.stk,1);
 		if(brace == '}')
 			break;
 		if(!range)

src/cmd/ksh93/sh/fault.c

@@ -497,7 +497,7 @@ int sh_trap(const char *trap, int mode)
 	char	was_no_trapdontexec = !sh.st.trapdontexec;
 	char	save_chldexitsig = sh.chldexitsig;
 	int	staktop = stktell(sh.stk);
-	char	*savptr = stkfreeze(sh.stk,0);
+	void	*savptr = stkfreeze(sh.stk,0);
 	struct	checkpt buff;
 	Fcin_t	savefc;
 	fcsave(&savefc);