2fe8fb192f
There is important information about booting non-ack images in docs/UPDATING. ack/aout-format images can't be built any more, and booting clang/ELF-format ones is a little different. Updating to the new boot monitor is recommended. Changes in this commit: . drop boot monitor -> allowing dropping ack support . facility to copy ELF boot files to /boot so that old boot monitor can still boot fairly easily, see UPDATING . no more ack-format libraries -> single-case libraries . some cleanup of OBJECT_FMT, COMPILER_TYPE, etc cases . drop several ack toolchain commands, but not all support commands (e.g. aal is gone but acksize is not yet). . a few libc files moved to netbsd libc dir . new /bin/date as minix date used code in libc/ . test compile fix . harmonize includes . /usr/lib is no longer special: without ack, /usr/lib plays no kind of special bootstrapping role any more and bootstrapping is done exclusively through packages, so releases depend even less on the state of the machine making them now. . rename nbsd_lib* to lib* . reduce mtree
226 lines
5.4 KiB
Groff
226 lines
5.4 KiB
Groff
.\" $NetBSD: wordexp.3,v 1.2 2006/04/24 20:27:34 jld Exp $
|
|
.\"
|
|
.\" Copyright (c) 2002 Tim J. Robbins
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/gen/wordexp.3,v 1.6 2003/09/08 19:57:14 ru Exp $
|
|
.\"
|
|
.Dd July 13, 2004
|
|
.Dt WORDEXP 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm wordexp
|
|
.Nd "perform shell-style word expansions"
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In wordexp.h
|
|
.Ft int
|
|
.Fn wordexp "const char * restrict words" "wordexp_t * restrict pwordexp" "int flags"
|
|
.Ft void
|
|
.Fn wordfree "wordexp_t *pwordexp"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn wordexp
|
|
function performs shell-style word expansion on
|
|
.Fa words
|
|
and places the list of expanded words into the structure pointed to by
|
|
.Fa pwordexp .
|
|
.Pp
|
|
The
|
|
.Fa flags
|
|
argument is the bitwise inclusive OR of any of the following constants:
|
|
.Bl -tag -width ".Dv WRDE_SHOWERR"
|
|
.It Dv WRDE_APPEND
|
|
Append the words to those generated by a previous call to
|
|
.Fn wordexp .
|
|
.It Dv WRDE_DOOFFS
|
|
As many
|
|
.Dv NULL
|
|
pointers as are specified by the
|
|
.Va we_offs
|
|
member of
|
|
.Fa we
|
|
are added to the front of
|
|
.Va we_wordv .
|
|
.It Dv WRDE_NOCMD
|
|
Disallow command substitution in
|
|
.Fa words .
|
|
See the note in
|
|
.Sx BUGS
|
|
before using this.
|
|
.It Dv WRDE_REUSE
|
|
The
|
|
.Fa we
|
|
argument was passed to a previous successful call to
|
|
.Fn wordexp
|
|
but has not been passed to
|
|
.Fn wordfree .
|
|
The implementation may reuse the space allocated to it.
|
|
.It Dv WRDE_SHOWERR
|
|
Do not redirect shell error messages to
|
|
.Pa /dev/null .
|
|
.It Dv WRDE_UNDEF
|
|
Report error on an attempt to expand an undefined shell variable.
|
|
.El
|
|
.Pp
|
|
The structure type
|
|
.Nm wordexp_t
|
|
includes the following members:
|
|
.Bd -literal -offset indent
|
|
size_t we_wordc
|
|
char **we_wordv
|
|
size_t we_offs
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fa we_wordc
|
|
member is the count of generated words.
|
|
.Pp
|
|
The
|
|
.Fa we_wordv
|
|
member points to a list of pointers to expanded words.
|
|
.Pp
|
|
The
|
|
.Fa we_offs
|
|
member is the number of slots to reserve at the beginning of the
|
|
.Fa we_wordv
|
|
member.
|
|
.Pp
|
|
It is the caller's responsibility to allocate the storage pointed to by
|
|
.Fa pwordexp .
|
|
The
|
|
.Fn wordexp
|
|
function allocates other space as needed, including memory
|
|
pointed to by the
|
|
.Fa we_wordv
|
|
member.
|
|
.Pp
|
|
The
|
|
.Fn wordfree
|
|
function frees the memory allocated by
|
|
.Fn wordexp .
|
|
.Sh IMPLEMENTATION NOTES
|
|
The
|
|
.Fn wordexp
|
|
function is implemented as a wrapper around the undocumented
|
|
.Ic wordexp
|
|
shell built-in command.
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn wordexp
|
|
function returns zero if successful, otherwise it returns one of the following
|
|
error codes:
|
|
.Bl -tag -width ".Dv WRDE_NOSPACE"
|
|
.It Dv WRDE_BADCHAR
|
|
The
|
|
.Fa words
|
|
argument contains one of the following unquoted characters:
|
|
.Aq newline ,
|
|
.Ql | ,
|
|
.Ql \*[Am] ,
|
|
.Ql \&; ,
|
|
.Ql \*[Lt] ,
|
|
.Ql \*[Gt] ,
|
|
.Ql \&( ,
|
|
.Ql \&) ,
|
|
.Ql { ,
|
|
.Ql } .
|
|
.It Dv WRDE_BADVAL
|
|
An attempt was made to expand an undefined shell variable and
|
|
.Dv WRDE_UNDEF
|
|
is set in
|
|
.Fa flags .
|
|
.It Dv WRDE_CMDSUB
|
|
An attempt was made to use command substitution and
|
|
.Dv WRDE_NOCMD
|
|
is set in
|
|
.Fa flags .
|
|
.It Dv WRDE_NOSPACE
|
|
Not enough memory to store the result.
|
|
.It Dv WRDE_SYNTAX
|
|
Shell syntax error in
|
|
.Fa words .
|
|
.It Dv WRDE_ERRNO
|
|
An internal error occured and
|
|
.Va errno
|
|
is set to indicate the error.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn wordfree
|
|
function returns no value.
|
|
.Sh ENVIRONMENT
|
|
.Bl -tag -width ".Ev IFS"
|
|
.It Ev IFS
|
|
Field separator.
|
|
.El
|
|
.Sh EXAMPLES
|
|
Invoke the editor on all
|
|
.Pa .c
|
|
files in the current directory
|
|
and
|
|
.Pa /etc/motd
|
|
(error checking omitted):
|
|
.Bd -literal -offset indent
|
|
wordexp_t we;
|
|
|
|
wordexp("${EDITOR:-vi} *.c /etc/motd", \*[Am]we, 0);
|
|
execvp(we-\*[Gt]we_wordv[0], we-\*[Gt]we_wordv);
|
|
.Ed
|
|
.Sh DIAGNOSTICS
|
|
Diagnostic messages from the shell are written to the standard error output
|
|
if
|
|
.Dv WRDE_SHOWERR
|
|
is set in
|
|
.Fa flags .
|
|
.Sh SEE ALSO
|
|
.Xr sh 1 ,
|
|
.Xr fnmatch 3 ,
|
|
.Xr glob 3 ,
|
|
.Xr popen 3 ,
|
|
.Xr system 3
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn wordexp
|
|
and
|
|
.Fn wordfree
|
|
functions conform to
|
|
.St -p1003.1-2001 .
|
|
Their first release was in
|
|
.St -p1003.2-92 .
|
|
The return value
|
|
.Dv WRDE_ERRNO
|
|
is an extension.
|
|
.Sh BUGS
|
|
Do not pass untrusted user data to
|
|
.Fn wordexp ,
|
|
regardless of whether the
|
|
.Dv WRDE_NOCMD
|
|
flag is set.
|
|
The
|
|
.Fn wordexp
|
|
function attempts to detect input that would cause commands to be
|
|
executed before passing it to the shell
|
|
but it does not use the same parser so it may be fooled.
|