git.saurik.com Git - apple/libc.git/blame_incremental

... / ...

Commit	Line	Data
	1	.\"
	2	.\" Copyright (c) 2002 Tim J. Robbins
	3	.\" All rights reserved.
	4	.\"
	5	.\" Redistribution and use in source and binary forms, with or without
	6	.\" modification, are permitted provided that the following conditions
	7	.\" are met:
	8	.\" 1. Redistributions of source code must retain the above copyright
	9	.\" notice, this list of conditions and the following disclaimer.
	10	.\" 2. Redistributions in binary form must reproduce the above copyright
	11	.\" notice, this list of conditions and the following disclaimer in the
	12	.\" documentation and/or other materials provided with the distribution.
	13	.\"
	14	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
	15	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	16	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	17	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
	18	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	19	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	20	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	21	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	22	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	23	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	24	.\" SUCH DAMAGE.
	25	.\"
	26	.\" $FreeBSD$
	27	.\"
	28	.Dd July 29, 2004
	29	.Dt WORDEXP 3
	30	.Os
	31	.Sh NAME
	32	.Nm wordexp
	33	.Nd "perform shell-style word expansions"
	34	.\" .Sh LIBRARY
	35	.\" .Lb libc
	36	.Sh SYNOPSIS
	37	.In wordexp.h
	38	.Ft int
	39	.Fn wordexp "const char * restrict words" "wordexp_t * restrict we" "int flags"
	40	.Ft void
	41	.Fn wordfree "wordexp_t *we"
	42	.Sh DESCRIPTION
	43	The
	44	.Fn wordexp
	45	function performs shell-style word expansion on
	46	.Fa words
	47	and places the list of words into the
	48	.Va we_wordv
	49	member of
	50	.Fa we ,
	51	and the number of words into
	52	.Va we_wordc .
	53	.Pp
	54	The
	55	.Fa flags
	56	argument is the bitwise inclusive OR of any of the following constants:
	57	.Bl -tag -width ".Dv WRDE_SHOWERR"
	58	.It Dv WRDE_APPEND
	59	Append the words to those generated by a previous call to
	60	.Fn wordexp .
	61	.It Dv WRDE_DOOFFS
	62	As many
	63	.Dv NULL
	64	pointers as are specified by the
	65	.Va we_offs
	66	member of
	67	.Fa we
	68	are added to the front of
	69	.Va we_wordv .
	70	.It Dv WRDE_NOCMD
	71	Disallow command substitution in
	72	.Fa words .
	73	See the note in
	74	.Sx BUGS
	75	before using this.
	76	.It Dv WRDE_REUSE
	77	The
	78	.Fa we
	79	argument was passed to a previous successful call to
	80	.Fn wordexp
	81	but has not been passed to
	82	.Fn wordfree .
	83	The implementation may reuse the space allocated to it.
	84	.It Dv WRDE_SHOWERR
	85	Do not redirect shell error messages to
	86	.Pa /dev/null .
	87	.It Dv WRDE_UNDEF
	88	Report error on an attempt to expand an undefined shell variable.
	89	.El
	90	.Pp
	91	The
	92	.Vt wordexp_t
	93	structure is defined in
	94	.In wordexp.h
	95	as:
	96	.Bd -literal -offset indent
	97	typedef struct {
	98	size_t we_wordc; /* count of words matched */
	99	char *we_wordv; / pointer to list of words */
	100	size_t we_offs; /* slots to reserve in we_wordv */
	101	} wordexp_t;
	102	.Ed
	103	.Pp
	104	The
	105	.Fn wordfree
	106	function frees the memory allocated by
	107	.Fn wordexp .
	108	.Sh IMPLEMENTATION NOTES
	109	The
	110	.Fn wordexp
	111	function is implemented as a wrapper around the undocumented
	112	.Ic wordexp
	113	shell built-in command.
	114	.Sh RETURN VALUES
	115	The
	116	.Fn wordexp
	117	function returns zero if successful, otherwise it returns one of the following
	118	error codes:
	119	.Bl -tag -width ".Dv WRDE_NOSPACE"
	120	.It Dv WRDE_BADCHAR
	121	The
	122	.Fa words
	123	argument contains one of the following unquoted characters:
	124	.Aq newline ,
	125	.Ql \| ,
	126	.Ql & ,
	127	.Ql \&; ,
	128	.Ql < ,
	129	.Ql > ,
	130	.Ql \&( ,
	131	.Ql \&) ,
	132	.Ql { ,
	133	.Ql } .
	134	.It Dv WRDE_BADVAL
	135	An attempt was made to expand an undefined shell variable and
	136	.Dv WRDE_UNDEF
	137	is set in
	138	.Fa flags .
	139	.It Dv WRDE_CMDSUB
	140	An attempt was made to use command substitution and
	141	.Dv WRDE_NOCMD
	142	is set in
	143	.Fa flags .
	144	.It Dv WRDE_NOSPACE
	145	Not enough memory to store the result.
	146	.It Dv WRDE_SYNTAX
	147	Shell syntax error in
	148	.Fa words .
	149	.El
	150	.Pp
	151	The
	152	.Fn wordfree
	153	function returns no value.
	154	.Sh ENVIRONMENT
	155	.Bl -tag -width ".Ev IFS"
	156	.It Ev IFS
	157	Field separator.
	158	.El
	159	.Sh EXAMPLES
	160	Invoke the editor on all
	161	.Pa .c
	162	files in the current directory
	163	and
	164	.Pa /etc/motd
	165	(error checking omitted):
	166	.Bd -literal -offset indent
	167	wordexp_t we;
	168
	169	wordexp("${EDITOR:-vi} *.c /etc/motd", &we, 0);
	170	execvp(we.we_wordv[0], we.we_wordv);
	171	.Ed
	172	.Sh DIAGNOSTICS
	173	Diagnostic messages from the shell are written to the standard error output
	174	if
	175	.Dv WRDE_SHOWERR
	176	is set in
	177	.Fa flags .
	178	.Sh SEE ALSO
	179	.Xr sh 1 ,
	180	.Xr fnmatch 3 ,
	181	.Xr glob 3 ,
	182	.Xr popen 3 ,
	183	.Xr system 3
	184	.Sh STANDARDS
	185	The
	186	.Fn wordexp
	187	and
	188	.Fn wordfree
	189	functions conform to
	190	.St -p1003.1-2001 .
	191	.Sh BUGS
	192	Do not pass untrusted user data to
	193	.Fn wordexp ,
	194	regardless of whether the
	195	.Dv WRDE_NOCMD
	196	flag is set.
	197	The
	198	.Fn wordexp
	199	function attempts to detect input that would cause commands to be
	200	executed before passing it to the shell
	201	but it does not use the same parser so it may be fooled.
	202	.Pp
	203	The current
	204	.Fn wordexp
	205	implementation does not recognize multibyte characters, since the
	206	shell (which it invokes to perform expansions) does not.