jcs.org
jcs's openbsd hax
openbsd
1.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved.
2.\"
3.\" Redistribution and use in source and binary forms, with or without
4.\" modification, are permitted provided that the following conditions
5.\" are met:
6.\" 1. Redistributions of source code must retain the above copyright
7.\" notice, this list of conditions and the following disclaimer.
8.\" 2. Redistributions in binary form must reproduce the above copyright
9.\" notice, this list of conditions and the following disclaimer in the
10.\" documentation and/or other materials provided with the distribution.
11.\"
12.\" This software is provided by Joseph Koshy ``as is'' and
13.\" any express or implied warranties, including, but not limited to, the
14.\" implied warranties of merchantability and fitness for a particular purpose
15.\" are disclaimed. in no event shall Joseph Koshy be liable
16.\" for any direct, indirect, incidental, special, exemplary, or consequential
17.\" damages (including, but not limited to, procurement of substitute goods
18.\" or services; loss of use, data, or profits; or business interruption)
19.\" however caused and on any theory of liability, whether in contract, strict
20.\" liability, or tort (including negligence or otherwise) arising in any way
21.\" out of the use of this software, even if advised of the possibility of
22.\" such damage.
23.\"
24.\" $Id: elf_next.3,v 1.3 2025/06/10 17:19:45 schwarze Exp $
25.\"
26.Dd February 27, 2019
27.Dt ELF_NEXT 3
28.Os
29.Sh NAME
30.Nm elf_next
31.Nd provide sequential access to the next archive member
32.Sh SYNOPSIS
33.Lb libelf
34.In libelf.h
35.Ft Elf_Cmd
36.Fn elf_next "Elf *elf"
37.Sh DESCRIPTION
38The
39.Fn elf_next
40function causes the ELF archive descriptor corresponding to argument
41.Ar elf
42to be adjusted to provide access to the next member in
43the archive on a subsequent call to
44.Fn elf_begin .
45.Pp
46The return value of
47.Fn elf_next
48is suitable for use in a loop invoking
49.Fn elf_begin .
50.Sh RETURN VALUES
51If successful, function
52.Fn elf_next
53returns the value
54.Dv ELF_C_READ .
55Otherwise, if argument
56.Ar elf
57was not associated with an archive, or if it was
58.Dv NULL ,
59or if any other error occurred, the value
60.Dv ELF_C_NULL
61is returned.
62.Sh EXAMPLES
63To process all the members of an archive use:
64.Bd -literal -offset indent
65Elf_Cmd cmd;
66Elf *archive, *e;
67\&...
68cmd = ELF_C_READ;
69archive = elf_begin(fd, cmd, NULL);
70while ((e = elf_begin(fd, cmd, archive)) != (Elf *) 0)
71{
72 ... process `e' here ...
73
74 cmd = elf_next(e);
75 elf_end(e);
76}
77elf_end(archive);
78.Ed
79.Sh ERRORS
80Function
81.Fn elf_next
82may fail with the following error:
83.Bl -tag -width "[ELF_E_RESOURCE]"
84.It Bq Er ELF_E_ARGUMENT
85Argument
86.Ar elf
87was not associated with a containing
88.Xr ar 1
89archive.
90.It Bq Er ELF_E_ARGUMENT
91An error was encountered while parsing the archive containing argument
92.Ar elf .
93.El
94.Sh SEE ALSO
95.Xr elf 3 ,
96.Xr elf_begin 3 ,
97.Xr elf_end 3 ,
98.Xr elf_rand 3