Wiki code for shell.3

Hide Line numbers
1: {{{
2: 
3: Introduction to Library Functions                        SHELL(3)
4: 
5: NAME
6:      shell - a ksh library interface
7: 
8: SYNOPSIS
9:   HEADERS/LIBRARIES
10:      #include        <shell.h>
11:      libshell.a      -lshell
12: 
13:   DATA TYPES
14:      Shell_t;
15:      Shopt_t;
16:      Shscope_t;
17:      Shbltin_f;
18:      Shinit_f;
19:      Shwait_f;
20: 
21:   FUNCTIONS
22:      int     sh_main(int argc, char *argv[], Sh_init fn);
23:      Shell_t *sh_init(int argc, char *argv);
24:      Shell_t *sh_getinterp(void);
25: 
26:      Namval_t        *sh_addbuiltin(const char *name,Sh_bltin_f fn,void *arg);
27: 
28:      unsigned int    sh_isoption(int option);
29:      unsigned int    sh_onoption(int option);
30:      unsigned int    sh_offoption(int option);
31: 
32:      void    *sh_parse(Shell_t *shp, Sfio_t *sp, int flags);
33:      int     sh_trap(const char *string, int mode);
34:      int     sh_eval(Sfio_t *sp,int mode);
35:      int     sh_fun(Namval_t *funnode, Namval_t *varnode, char *argv[]);
36:      int     sh_funscope(int argc,char *argv[],int(*fn)(void*),void *arg,int flags);
37:      Shscope_t       *sh_getscope(int index,int whence);
38:      Shscope_t       *sh_setscope(Shscope_t *scope);
39: 
40:      int     (*sh_fdnotify(int(*fn)(int,int)))(int,int);
41:      char    *sh_fmtq(const char *string);
42:      void    *sh_waitnotify(Shwait_f fn);
43:      void    sh_delay(double sec);
44:      Sfio_t  *sh_iogetiop(int  fd, int mode);
45:      int     sh_sigcheck(void);
46: 
47: DESCRIPTION
48:      The Shell library is a set of  functions  used  for  writing
49:      extensions  to ksh or writing commands that embed shell com-
50:      mand processing.  The include file  <shell.h>  contains  the
51:      type definitions, function prototypes and symbolic constants
52:      defined by this  interface.   It  also  defines  replacement
53:      definitions  for  the  standard  library functions access(),
54:      close(), dup(), exit(), fcntl(),  lseek(),  open(),  pipe(),
55:      read(), and write() that must be used with all code intended
56:      to be compiled as built-in commands.
57: 
58: SunOS 5.10          Last change: 28 Feb 2003                    1
59: 
60: Introduction to Library Functions                        SHELL(3)
61: 
62:      The <shell.h> header includes <ast.h> which in turn includes
63:      the   standard   include   files,   <stddef.h>,  <stdlib.h>,
64:      <stdarg.h>, <limits.h>, <stdio.h>,  <string.h>,  <unistd.h>,
65:      <sys/types.h>,  <fcntl.h>,  and  <locale.h>.   The <shell.h>
66:      header also includes the headers <cdt.h>, <cmd.h>, <sfio.h>,
67:      <nval.h>, <stk.h>, and <error.h> so that in most cases, pro-
68:      grams only require the single header <shell.h>.
69: 
70:      Programs can use this library in one of the following ways:
71:      1    To write builtin commands and/or other code  that  will
72:           be  loaded  into the shell by loading dynamic libraries
73:           at run time using the builtin(1) command.  In this case
74:           the  shell  will  look for a function named lib_init in
75:           your library and, if found, will execute this  function
76:           with  argument  0 when the library is loaded.  In addi-
77:           tion, for each argument named on  the  builtin  command
78:           line,  it  will  look  for a function named b_name() in
79:           your library and will name as a built-in.
80:      2    To build separate a  separate  command  that  uses  the
81:           shell  as  a  library  at compile or run time.  In this
82:           case the sh_init() function must be called to  initial-
83:           ize  this  library  before  any  other commands in this
84:           library are invoked.  The arguments argc and  argv  are
85:           the  number of arguments and the vector of arguments as
86:           supplied by  the  shell.   It  returns  a  pointer  the
87:           Shell_t.
88:      3    To build a new version of ksh with  extended  capabili-
89:           ties,  for  example  tksh(1).   In  this case, the user
90:           writes a main() function that calls sh_main() with  the
91:           argc  and argv arguments from main and pointer to func-
92:           tion, fn as a third argument..  The function fn will be
93:           invoked  with argument 0 after ksh has done initializa-
94:           tion, but before ksh has processed any start  up  files
95:           or  executed  any  commands.   The  function fn will be
96:           invoked with an argument of 1 before ksh begins to exe-
97:           cute  a  script that has been invoked by name since ksh
98:           cleans up memory and long jumps back to  the  beginning
99:           of  the  shell  in  this case.  The function fn will be
100:           called with argument -1 before the shell exits.
101: 
102:      The Shell_t structure contains the following fields:
103:              Shopt_t options;                /* set -o options */
104:              Dt_t    *var_tree;              /* shell variable dictionary */
105:              Dt_t    *fun_tree;              /* shell function dictionary */
106:              Dt_t    *alias_tree;            /* shell alias dictionary */
107:              Dt_t    *bltin_tree;            /* shell built-in dictionary */
108:              Shscope_t       *topscope;              /* pointer to top-level scope */
109:              char    *infile_name;   /* path name of current input file*/
110:              int     inlineno;               /* line number of current input file*/
111:              int     exitval;                /* most recent exit value*/
112:      This structure is returned by  sh_init()  but  can  also  be
113:      retrieved by a call to sh_getinterp().
114: 
115: SunOS 5.10          Last change: 28 Feb 2003                    2
116: 
117: Introduction to Library Functions                        SHELL(3)
118: 
119:      All built-in commands to the shell are  invoked  with  three
120:      arguments.  The first two arguments give the number of argu-
121:      ments and the argument list and uses the same conventions as
122:      the  main()  function of a program.  The third argument is a
123:      pointer that can be  associated  with  each  built-in.   The
124:      sh_addbuiltin()  function  is used to add, replace or delete
125:      built-in commands. It takes the name of the built-in,  name,
126:      a  pointer to the function that implements the built-in, fn,
127:      and a pointer that will be passed to the function when it is
128:      invoked.   If,  fn is non-NULL the built-in command is added
129:      or replaced.  Otherwise, the given built-in command will  be
130:      deleted.   The name argument can be in the format of a path-
131:      name.  It cannot be the name of any of the special  built-in
132:      commands.   If  name  contains  a  /,  the  built-in  is the
133:      basename of the pathname and the built-in will only be  exe-
134:      cuted if the given pathname is encountered when performing a
135:      path  search.   When  adding  or   replacing   a   built-in,
136:      sh_addbuiltin() function returns a pointer to the name-value
137:      pair corresponding to the built-in on success and NULL if it
138:      is  unable  to add or replace the built-in.  When deleting a
139:      built-in, NULL is returned on success or if not  found,  and
140:      the name-value pair pointer is returned if the built-in can-
141:      not be deleted.
142: 
143:      The functions sh_onoption(),  sh_offoption(),  sh_isoption()
144:      are  used  to set, unset, and test for shell options respec-
145:      tively.  The option argument can be any one of  the  follow-
146:      ing:
147: 
148:           SH_ALLEXPORT:  The NV_EXPORT attribute is given to each
149:           variable  whose  name  is an identifier when a value is
150:           assigned.
151: 
152:           SH_BGNICE:  Each background process is run at  a  lower
153:           priority.
154: 
155:           SH_ERREXIT:  Causes a  non-interactive  shell  to  exit
156:           when  a  command,  other  than  a  conditional command,
157:           returns non-zero.
158: 
159:           SH_EMACS:  The emacs editing mode.
160: 
161:           SH_GMACS:  Same as the emacs editing  mode  except  for
162:           the behavior of CONTROL-T.
163: 
164:           SH_HISTORY:  Indicates that the history file  has  been
165:           created and that commands can be logged.
166: 
167:           SH_IGNOREEOF:  Do not treat end-of-file as exit.
168: 
169:           SH_INTERACTIVE:
170: 
171: SunOS 5.10          Last change: 28 Feb 2003                    3
172: 
173: Introduction to Library Functions                        SHELL(3)
174: 
175:           Set for interactive shells.  Do not set or  unset  this
176:           option.   SH_MARKDIRS:  A / is added to the end of each
177:           directory generated by pathname expansion.
178: 
179:           SH_MONITOR:   Indicates  that  the  monitor  option  is
180:           enabled for job control.
181: 
182:           SH_NOCLOBBER:  The > redirection will fail if the  file
183:           exists.   Each file created with > will have the O_EXCL
184:           bit set as described in <fcntl.h>
185: 
186:           SH_NOGLOB:  Do not perform pathname expansion.
187: 
188:           SH_NOLOG:  Do not save function definitions in the his-
189:           tory file.
190: 
191:           SH_NOTIFY:  Cause a message to be generated as soon  as
192:           each background job completes.
193: 
194:           SH_NOUNSET:  Cause the shell to fail with an  error  of
195:           an unset variable is referenced.
196: 
197:           SH_PRIVILEGED:
198: 
199:           SH_VERBOSE:  Cause each line to be echoed as it is read
200:           by the parser.
201: 
202:           SH_XTRACE:  Cause each command to  be  displayed  after
203:           all expansions, but before execution.
204: 
205:           SH_VI:  The vi edit mode.
206: 
207:           SH_VIRAW:  Read character at a time rather than line at
208:           a time when in vi edit mode.
209: 
210:      The sh_trap() function can be used to compile and execute  a
211:      string  or  file.  A value of 0 for mode indicates that name
212:      refers to a string.  A value of 1 for  mode  indicates  that
213:      name is an Sfio_t* to an open stream.  A value of 2 for mode
214:      indicates that name points to a parse  tree  that  has  been
215:      returned  by  sh_parse().  The complete file associated with
216:      the string or file is compiled and  then  executed  so  that
217:      aliases  defined  within  the  string  or file will not take
218:      effect until the next command is executed.
219: 
220:      The sh_eval() function executes a string or file stream  sp.
221:      If  mode  is non-zero and the history file has been created,
222:      the stream defined by sp will be  appended  to  the  history
223:      file as a command.
224: 
225: SunOS 5.10          Last change: 28 Feb 2003                    4
226: 
227: Introduction to Library Functions                        SHELL(3)
228: 
229:      The sh_parse() function takes a pointer to the shell  inter-
230:      preter  shp,  a  pointer  to a string or file stream sp, and
231:      compilation flags, and returns a pointer to a parse tree  of
232:      the compiled stream.  This pointer can be used in subsequent
233:      calls to sh_trap().  The compilation flags can  be  zero  or
234:      more of the following:
235: 
236:           SH_NL:  Treat new-lines as ;.
237: 
238:           SH_EOF:  An  end  of  file  causes  syntax  error.   By
239:           default it will be treated as a new-line.
240: 
241:      ksh  executes  each  function  defined  with  the   function
242:      reserved  word in a separate scope.  The Shscope_t type pro-
243:      vides an interface to some of the information that is avail-
244:      able  on  each  scope.  The structure contains the following
245:      public members:
246:            Sh_scope_t      *par_scope;
247:            int             argc;
248:            char            **argv;
249:            char            *cmdname;
250:            Dt_t               *var_tree;
251:      The sh_getscope() function can be  used  to  the  the  scope
252:      information associated with existing scope.  Scopes are num-
253:      bered from 0 for the global scope up to  the  current  scope
254:      level.   The  whence  argument  uses  the symbolic constants
255:      associated with lseek() to indicate whether the Iscope argu-
256:      ment is absolute, relative to the current scope, or relative
257:      to the topmost scope.  Thesh_setscope() function can be used
258:      to  make  a  a  known scope the current scope.  It returns a
259:      pointer to the old current scope.
260: 
261:      The sh_funscope() function can be used to run a function  in
262:      a  new scope.  The arguments argc and argv are the number of
263:      arguments and the list of arguments respectively.  If fn  is
264:      non-NULL, then this function is invoked with argc, argv, and
265:      arg as arguments.
266: 
267:      The sh_fun() function can  be  called  within  a  discipline
268:      function or built-in extension to execute a discipline func-
269:      tion script. The argument funnode is a pointer to the  shell
270:      function  or built-in to execute.  The argument varnode is a
271:      pointer to the name value pair that has defined this discip-
272:      line.  The array argv is a NULL terminated list of arguments
273:      that are passed to the function.
274: 
275:      By default, ksh only records but does  not  act  on  signals
276:      when running a built-in command.  If a built-in takes a sub-
277:      stantial amount of time to execute, then it should check for
278:      interrupts periodically by calling sh_sigcheck().  If a sig-
279:      nal is pending, sh_sigcheck() will exit the function you are
280:      calling  and  return  to  the  point  where  the most recent
281: 
282: SunOS 5.10          Last change: 28 Feb 2003                    5
283: 
284: Introduction to Library Functions                        SHELL(3)
285: 
286:      built-in was invoked, or where sh_eval()  or  sh_trap()  was
287:      called.
288: 
289:      The sh_delay() function is used to cause the shell to  sleep
290:      for a period of time defined by sec.
291: 
292:      The sh_fmtq() function can be used to convert a string  into
293:      a  string  that  is  quoted so that it can be reinput to the
294:      shell. The quoted string returned by sh_fmtq may be returned
295:      on the current stack, so that it must be saved or copied.
296: 
297:      The sh_fdnotify() function causes  the  function  fn  to  be
298:      called  whenever  the shell duplicates or closes a file.  It
299:      is provided for extensions that need to keep track  of  file
300:      descriptors  that  could  be changed by shell commands.  The
301:      function fn is called with two arguments.  The  first  argu-
302:      ment  is  the original file descriptor.  The second argument
303:      is the  new  file  descriptor  for  duplicating  files,  and
304:      SH_FDCLOSE  when  a  file  has  been closed.  The previously
305:      installed sh_fdnotify() function pointer is returned.
306: 
307:      The sh_waitnotify() function causes the function  fn  to  be
308:      called  whenever  the shell is waiting for input from a slow
309:      device or waiting for a process to complete.  This  function
310:      can  process  events  and  run shell commands until there is
311:      input, the timer is reached  or  a  signal  arises.   It  is
312:      called  with three arguments. The first is the file descrip-
313:      tor from which the shell trying to read  or -1 if the  shell
314:      is  waiting  for  a  process  to  complete.  The second is a
315:      timeout in milliseconds.  A value  of  -1  for  the  timeout
316:      means  that no timeout should be set.  The third argument is
317:      0 for input file descriptors and 1 for output file  descrip-
318:      tor.  The  function  needs  to return a value >0 if there is
319:      input on the file descriptor, and a value <0 if the  timeout
320:      is reached or a signal has occurred.  A value of 0 indicates
321:      that the function has returned without processing  and  that
322:      the  shell should wait for input or process completion.  The
323:      previous  installed  sh_waitnotify()  function  pointer   is
324:      returned.
325: 
326:      The sh_iogetiop() function returns a  pointer  to  the  Sfio
327:      stream  corresponding  to  file descriptor number fd and the
328:      given  mode  mode.   The  mode  can  be  either  SF_READ  or
329:      SF_WRITE.   The  fd  argument can the number of an open file
330:      descriptor or one of the following symbolic constants:
331: 
332:           SH_IOCOPROCESS:  The stream corresponding to  the  most
333:           recent co-process.
334: 
335:           SH_IOHISTFILE:  The stream corresponding to the history
336:           file.   If  no stream exists corresponding to fd or the
337:           stream can not be accessed in the specified mode,  NULL
338: 
339: SunOS 5.10          Last change: 28 Feb 2003                    6
340: 
341: Introduction to Library Functions                        SHELL(3)
342: 
343:           is returned.
344: 
345: SEE ALSO
346:      builtin(1) cdt(3) error(3) nval(3) sfio(3) stk(3) tksh(1)
347: 
348: AUTHOR
349:      David G. Korn (dgk@research.att.com).
350: 
351: SunOS 5.10          Last change: 28 Feb 2003                    7
352: 
353: }}}
354: 
355: ----
356: Generated by [[GNU enscript 1.6.4>>http://www.iki.fi/~mtr/genscript/]].
OpenSolaris

Top Menu

Wiki code for shell.3

Search

Collectives

Community Group

Project

User Group

Subsites

Project ksh93-integration Pages
