usr/src/man/man1/builtin.1

   1 '\" te
   2 .\" Copyright (c) 1982-2007 AT&T Knowledge Ventures
   3 .\" To view license terms, see http://www.opensource.org/licenses/cpl1.0.txt
   4 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc.
   5 .TH BUILTIN 1 "May 1, 2007"
   6 .SH NAME
   7 builtin \- ksh93 built-in function to add, delete, or display shell built-ins
   8 .SH SYNOPSIS
   9 .LP
  10 .nf
  11 \fBbuiltin\fR [\fB-ds\fR] [\fB-f\fR \fIlib\fR] [\fIpathname\fR ...]
  12 .fi
  13
  14 .SH DESCRIPTION
  15 .sp
  16 .LP
  17 The \fBksh93\fR \fBbuiltin\fR command adds, deletes, or displays built-in
  18 commands in the current shell environment. A built-in command executes in the
  19 current shell process and can have side effects in the current shell. On most
  20 systems, the invocation time for built-in commands is one or two orders of
  21 magnitude less than commands that create a separate process.
  22 .sp
  23 .LP
  24 For each \fIpathname\fR specified, the basename of the pathname determines the
  25 name of the built-in. For each basename, the shell looks for a C level function
  26 in the current shell whose name is determined by pre-pending \fBb_\fR to the
  27 built-in name. If \fIpathname\fR contains a forward slash (\fB/\fR), the
  28 built-in is bound to \fIpathname\fR. A built-in bound to a pathname is only
  29 executed if \fIpathname\fR is the first executable found during a path search.
  30 Otherwise, built-ins are found prior to performing the path search.
  31 .sp
  32 .LP
  33 If \fIpathname\fR is not specified, \fBbuiltin\fR displays the current list of
  34 built-ins, or just the special built-ins if the \fB-s\fR option is specified,
  35 on standard output. The full pathname for built-ins that are bound to pathnames
  36 are displayed.
  37 .sp
  38 .LP
  39 Libraries containing built-ins can be specified with the \fB-f\fR option. If
  40 the library contains a function named \fBlib_init()\fR, this function is
  41 invoked with argument \fB0\fR when the library is loaded. The \fBlib_init()\fR
  42 function can load built-ins by invoking an appropriate C level function. In
  43 this case there is no restriction on the C level function name.
  44 .sp
  45 .LP
  46 The C level function is invoked with three arguments. The first two are the
  47 same as \fBmain()\fR and the third one is a pointer.
  48 .sp
  49 .LP
  50 The \fBksh93\fR \fBbuiltin\fR command cannot be invoked from a restricted
  51 shell.
  52 .SH OPTIONS
  53 .sp
  54 .LP
  55 The following options are supported:
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fB-d\fR\fR
  60 .ad
  61 .RS 10n
  62 Delete each of the specified built-ins. Special built-ins cannot be deleted.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fB-f\fR \fIlib\fR\fR
  69 .ad
  70 .RS 10n
  71 On systems with dynamic linking, load and search for built-ins in the shared
  72 library, \fIlib\fR.
  73 .sp
  74 Libraries are searched for in \fB$PATH\fR and system dependent library
  75 directories. The system dependent shared library prefix or suffix can be
  76 omitted. Once a library is loaded, its symbols become available for the current
  77 and subsequent invocations of \fBbuiltin\fR. Multiple libraries can be
  78 specified with separate invocations of \fBbuiltin\fR. Libraries are searched in
  79 the reverse order in which they are specified.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fB-s\fR\fR
  86 .ad
  87 .RS 10n
  88 Display only the special built-ins.
  89 .RE
  90
  91 .SH OPERANDS
  92 .sp
  93 .LP
  94 The following operands are supported:
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fIpathname\fR\fR
  99 .ad
 100 .RS 12n
 101 Specifies the \fIpathname\fR. The basename of the pathname determines the name
 102 of the built-in.
 103 .RE
 104
 105 .SH EXIT STATUS
 106 .sp
 107 .LP
 108 The following exit values are returned:
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fB0\fR\fR
 113 .ad
 114 .RS 6n
 115 Successful completion.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fB>0\fR\fR
 122 .ad
 123 .RS 6n
 124 An error occurred.
 125 .RE
 126
 127 .SH EXAMPLES
 128 .LP
 129 \fBExample 1 \fRLoading a \fBbuiltin\fR Command
 130 .sp
 131 .LP
 132 The following example loads a \fBbuiltin\fR command \fBmycmd\fR from the
 133 library \fBlibfoo.so\fR:
 134
 135 .sp
 136 .in +2
 137 .nf
 138 example% builtin -f foo mycmd
 139 .fi
 140 .in -2
 141 .sp
 142
 143 .SH AUTHORS
 144 .sp
 145 .LP
 146 David Korn, \fBdgk@research.att.com\fR
 147 .SH ATTRIBUTES
 148 .sp
 149 .LP
 150 See \fBattributes\fR(5) for descriptions of the following attributes:
 151 .sp
 152
 153 .sp
 154 .TS
 155 box;
 156 c | c
 157 l | l .
 158 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 159 _
 160 Interface Stability     Uncommitted
 161 .TE
 162
 163 .SH SEE ALSO
 164 .sp
 165 .LP
 166 \fBksh93\fR(1), \fBwhence\fR(1), \fBattributes\fR(5)