.\" Process this file with
.\" groff -man -Tascii cryptday.1
.\"
.TH js_buf_getline 3 "August 2000" JS "js library reference"
.\" We don't want hyphenation (it's too ugly)
.\" We also disable justification when using nroff
.hy 0
.if n .na
.SH NAME
js_buf_getline \- grab a line of text from a file (in a buffered
context)
.SH SYNOPSIS
.nf
.B #include "JsStr.h"
.sp
.B "int js_buf_getline(js_file *desc, js_string *js)"
.fi
.SH DESCRIPTION
.B js_buf_getline
reads, in a buffered context, a single line from the file
pointed to by 
.B desc,
and places the read contents in the 
.I js_string
object 
.B js.
.SH ARGUMENTS
.B desc
is a pointer to a file object we are reading a line from.

.B js
is the 
.I js_string
object we place the read contents in.
.SH WARNING
This routine should not be combined with non-buffered routines, such as
.B js_read.

The
.I js_string
object needs to be set to
.I JS_US_ASCII,
or another non-binary encoding,
before using this function.  This is because there are no newline characters
(nor any other special characters) in binary data.
.SH "RETURN VALUE"
.B js_buf_getline
returns 
.I JS_SUCCESS 
on successful reading of a line,
.I -2
if the line is too long for the destination js string, and
.I JS_ERROR
otherwise.
.SH EXAMPLE
The following reads a single line from the file "filename" after
reading a single line from the file:

.nf
	js_string *foo;
	js_file *bar;
	foo = js_create(256,1);		
	js_str2js(foo,"filename",8,1);
	js_open_read(foo,bar);
	js_set_encode(foo,JS_US_ASCII);
	js_buf_getline(bar,foo);
.fi
.SH AUTHOR
Sam Trenholme <kiwi-zttfryb@koala.samiam.org>