doc/man3/string_to_tokens.3

.\"
.\" $Id: string_to_tokens.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
.\"
.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of version 2 of the GNU General Public License as
.\" published by the Free Software Foundation.
.\"
.\" This program is distributed in the hope that it would be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.\"
.\" Further, this software is distributed without any warranty that it is
.\" free of the rightful claim of any third person regarding infringement
.\" or the like.  Any license provided herein, whether implied or
.\" otherwise, applies only to this software file.  Patent licenses, if
.\" any, provided herein do not apply to combinations of this program with
.\" other software, or any other product whatsoever.
.\"
.\" You should have received a copy of the GNU General Public License along
.\" with this program; if not, write the Free Software Foundation, Inc.,
.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
.\"
.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
.\" Mountain View, CA  94043, or:
.\"
.\" http://www.sgi.com
.\"
.\" For further information regarding this notice, see:
.\"
.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
.\"
.TH STRING_TO_TOKEN 3 07/25/2000 "Linux Test Project"
.SH NAME
string_to_tokens \- Break a string into its tokens
.SH SYNOPSIS
.nf
\fB
int string_to_tokens(arg_string, arg_array, array_size, separator)
char *arg_string;
char *arg_array[];
int array_size;
char *separator;
\fR
.fi

.SH DESCRIPTION
This function parses the string \fIarg_string\fR, placing pointers to
the \fIseparator\fR separated tokens into the elements of \fIarg_array\fR.
The array is terminated with a null pointer.
\fIarg_array\fR must contains at least \fIarray_size\fR elements.
Only the first \fIarray_size\fR minus one tokens will be placed into
\fIarg_array\fR.  If there are more than \fIarray_size\fR-1 tokens, the rest are
ignored by this routine.
.RE

.SH "SEE ALSO"
strtok(3).

.SH DIAGNOSTICS
This function returns the number of \fIseparator\fR separated tokens that
were found in \fIarg_string\fR.
If \fIarg_array\fR or \fIseparator\fR is NULL or \fIarray_size\fR is less than 2,
-1 is returned.

.SH BUGS
This function uses \fBstrtok()\fR to parse \fIarg_string\fR, and thus
physically alters \fIarg_string\fR by placing null characters where the
separators originally were.