2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001 John Levon <moz@compsoc.man.ac.uk>
|
|
|
|
.\" Based in part on GNU libc documentation
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\" License.
|
2010-06-12 13:05:02 +00:00
|
|
|
.TH GETLINE 3 2010-06-12 "GNU" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
getline, getdelim \- delimited string input
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.B #include <stdio.h>
|
|
|
|
.sp
|
|
|
|
.BI "ssize_t getline(char **" lineptr ", size_t *" n ", FILE *" stream );
|
2007-12-23 13:45:24 +00:00
|
|
|
|
2007-12-23 21:05:57 +00:00
|
|
|
.BI "ssize_t getdelim(char **" lineptr ", size_t *" n ", int " delim \
|
|
|
|
", FILE *" stream );
|
|
|
|
.fi
|
2009-12-05 13:58:09 +00:00
|
|
|
.sp
|
|
|
|
.in -4n
|
|
|
|
Feature Test Macro Requirements for glibc (see
|
|
|
|
.BR feature_test_macros (7)):
|
|
|
|
.in
|
2010-09-19 05:13:50 +00:00
|
|
|
.sp
|
2010-09-17 15:46:55 +00:00
|
|
|
.ad l
|
2009-12-05 13:58:09 +00:00
|
|
|
.BR getline (),
|
|
|
|
.BR getdelim ():
|
2010-09-19 05:13:50 +00:00
|
|
|
.PD 0
|
|
|
|
.RS 4
|
|
|
|
.TP 4
|
|
|
|
Since glibc 2.10:
|
2010-09-17 15:46:55 +00:00
|
|
|
_POSIX_C_SOURCE\ >=\ 200809L || _XOPEN_SOURCE\ >=\ 700
|
2010-09-19 05:13:50 +00:00
|
|
|
.TP
|
|
|
|
Before glibc 2.10:
|
|
|
|
_GNU_SOURCE
|
|
|
|
.RE
|
|
|
|
.PD
|
2010-09-17 15:46:55 +00:00
|
|
|
.ad
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR getline ()
|
2007-04-12 22:42:49 +00:00
|
|
|
reads an entire line from \fIstream\fP,
|
2006-05-18 22:24:03 +00:00
|
|
|
storing the address of the buffer containing the text into
|
2005-07-19 15:36:19 +00:00
|
|
|
.IR "*lineptr" .
|
2006-05-18 22:24:03 +00:00
|
|
|
The buffer is null-terminated and includes the newline character, if
|
|
|
|
one was found.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
|
|
|
If
|
2007-09-20 16:26:31 +00:00
|
|
|
.I "*lineptr"
|
2006-05-18 22:24:03 +00:00
|
|
|
is NULL, then
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR getline ()
|
2007-06-16 09:11:52 +00:00
|
|
|
will allocate a buffer for storing the line,
|
|
|
|
which should be freed by the user program.
|
2010-06-12 13:00:57 +00:00
|
|
|
(In this case, the value in
|
2007-06-16 09:11:52 +00:00
|
|
|
.I *n
|
|
|
|
is ignored.)
|
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
Alternatively, before calling
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR getline (),
|
2007-09-20 16:26:31 +00:00
|
|
|
.I "*lineptr"
|
2004-11-03 13:51:07 +00:00
|
|
|
can contain a pointer to a
|
2007-05-12 00:30:29 +00:00
|
|
|
.BR malloc (3)\-allocated
|
2004-11-03 13:51:07 +00:00
|
|
|
buffer
|
2007-09-20 16:26:31 +00:00
|
|
|
.I "*n"
|
2007-04-12 22:42:49 +00:00
|
|
|
bytes in size.
|
|
|
|
If the buffer is not large enough to hold the line,
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR getline ()
|
2006-05-18 22:24:03 +00:00
|
|
|
resizes it with
|
2007-05-12 00:30:29 +00:00
|
|
|
.BR realloc (3),
|
2004-11-03 13:51:07 +00:00
|
|
|
updating
|
2007-09-20 16:26:31 +00:00
|
|
|
.I "*lineptr"
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2007-09-20 16:26:31 +00:00
|
|
|
.I "*n"
|
2007-04-12 22:42:49 +00:00
|
|
|
as necessary.
|
2007-06-16 09:11:52 +00:00
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
In either case, on a successful call,
|
2007-09-20 16:26:31 +00:00
|
|
|
.I "*lineptr"
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2007-09-20 16:26:31 +00:00
|
|
|
.I "*n"
|
2006-05-18 22:24:03 +00:00
|
|
|
will be updated to reflect the buffer address and allocated size respectively.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR getdelim ()
|
2004-11-03 13:51:07 +00:00
|
|
|
works like
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR getline (),
|
2010-09-17 15:46:55 +00:00
|
|
|
except that a line delimiter other than newline can be specified as the
|
2007-09-20 16:26:31 +00:00
|
|
|
.I delimiter
|
2007-04-12 22:42:49 +00:00
|
|
|
argument.
|
|
|
|
As with
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR getline (),
|
2004-11-03 13:51:07 +00:00
|
|
|
a delimiter character is not added if one was not present
|
|
|
|
in the input before end of file was reached.
|
|
|
|
.SH "RETURN VALUE"
|
|
|
|
On success,
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR getline ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 16:30:05 +00:00
|
|
|
.BR getdelim ()
|
2004-11-03 13:51:07 +00:00
|
|
|
return the number of characters read, including the delimiter character,
|
2007-04-12 22:42:49 +00:00
|
|
|
but not including the terminating null byte.
|
|
|
|
This value can be used
|
2006-01-13 02:09:44 +00:00
|
|
|
to handle embedded null bytes in the line read.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2011-09-27 03:07:24 +00:00
|
|
|
Both functions return \-1 on failure to read a line (including end-of-file
|
2004-11-03 13:51:07 +00:00
|
|
|
condition).
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
2008-07-10 20:53:08 +00:00
|
|
|
Bad arguments
|
2004-11-03 13:51:07 +00:00
|
|
|
.RI ( n
|
|
|
|
or
|
|
|
|
.I lineptr
|
|
|
|
is NULL, or
|
|
|
|
.I stream
|
|
|
|
is not valid).
|
2009-12-05 13:58:09 +00:00
|
|
|
.SH VERSIONS
|
|
|
|
These functions are available since libc 4.6.27.
|
2007-05-19 04:30:20 +00:00
|
|
|
.SH "CONFORMING TO"
|
|
|
|
Both
|
|
|
|
.BR getline ()
|
|
|
|
and
|
|
|
|
.BR getdelim ()
|
2009-12-05 13:58:09 +00:00
|
|
|
were originally GNU extensions.
|
|
|
|
They were standardized in POSIX.1-2008.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "EXAMPLE"
|
|
|
|
.nf
|
|
|
|
#define _GNU_SOURCE
|
|
|
|
#include <stdio.h>
|
|
|
|
#include <stdlib.h>
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
int
|
2007-04-05 12:36:57 +00:00
|
|
|
main(void)
|
2004-11-03 13:51:07 +00:00
|
|
|
{
|
2010-06-12 12:59:07 +00:00
|
|
|
FILE *fp;
|
|
|
|
char *line = NULL;
|
2007-04-05 12:36:57 +00:00
|
|
|
size_t len = 0;
|
|
|
|
ssize_t read;
|
2007-12-25 16:21:21 +00:00
|
|
|
|
2007-04-05 12:36:57 +00:00
|
|
|
fp = fopen("/etc/motd", "r");
|
|
|
|
if (fp == NULL)
|
|
|
|
exit(EXIT_FAILURE);
|
2007-12-25 16:21:21 +00:00
|
|
|
|
2007-04-05 12:36:57 +00:00
|
|
|
while ((read = getline(&line, &len, fp)) != \-1) {
|
time.1, atexit.3, bsearch.3, dlopen.3, envz_add.3, errno.3, fmtmsg.3, getgrent_r.3, getline.3, getmntent.3, getnameinfo.3, getpass.3, getpwent_r.3, gets.3, isalpha.3, printf.3, puts.3, recno.3, scandir.3, stdarg.3, sysconf.3, termios.3, wordexp.3, null.4, core.5, dir_colors.5, issue.5, proc.5, termcap.5, utmp.5, ascii.7, cpuset.7, glob.7, man-pages.7, man.7, mdoc.7, mdoc.samples.7, regex.7: Global fix: use \\ rather than \e for literal backslash
Reported-by: Jan Engelhardt <jengelh@inai.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2012-09-24 08:23:07 +00:00
|
|
|
printf("Retrieved line of length %zu :\\n", read);
|
2007-04-05 12:36:57 +00:00
|
|
|
printf("%s", line);
|
|
|
|
}
|
2007-12-25 16:21:21 +00:00
|
|
|
|
2010-06-12 13:05:02 +00:00
|
|
|
free(line);
|
2007-12-25 16:21:21 +00:00
|
|
|
exit(EXIT_SUCCESS);
|
2004-11-03 13:51:07 +00:00
|
|
|
}
|
|
|
|
.fi
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR read (2),
|
|
|
|
.BR fgets (3),
|
|
|
|
.BR fopen (3),
|
|
|
|
.BR fread (3),
|
|
|
|
.BR gets (3),
|
getresuid.2, intro.2, mremap.2, open.2, poll.2, posix_fadvise.2, pread.2, remap_file_pages.2, setresuid.2, signal.2, splice.2, sync_file_range.2, tee.2, vmsplice.2, INFINITY.3, asprintf.3, assert_perror.3, basename.3, bsd_signal.3, canonicalize_file_name.3, clog10.3, crypt.3, dl_iterate_phdr.3, dlopen.3, dprintf.3, encrypt.3, exp10.3, fcloseall.3, fenv.3, ffs.3, fmemopen.3, fopencookie.3, ftw.3, getdate.3, getline.3, getloadavg.3, getopt.3, getsubopt.3, getutent.3, grantpt.3, hsearch.3, intro.3, lseek64.3, memmem.3, mempcpy.3, mq_receive.3, mq_send.3, posix_fallocate.3, pow10.3, program_invocation_name.3, ptsname.3, putgrent.3, readdir.3, sigset.3, sincos.3, stpcpy.3, stpncpy.3, strchr.3, strfry.3, strnlen.3, strptime.3, strsignal.3, strstr.3, strverscmp.3, swab.3, sysv_signal.3, tsearch.3, unlocked_stdio.3, unlockpt.3, wcpcpy.3, wcpncpy.3, wcsdup.3, wcwidth.3: SEE ALSO: Remove redundant reference to feature_test_macros(7)
Reported-by: Florian Lehmann <flo.lehmann@googlemail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-10-31 05:05:22 +00:00
|
|
|
.BR scanf (3)
|