Debian Codegraph @

upstream/debian-unstable/man7/rpm-lua.7

raw
1 .\" Generated by scdoc 1.11.4
2 .\" Complete documentation for this program is not available as a GNU info page
3 .ie \n(.g .ds Aq \(aq
4 .el .ds Aq '
5 .nh
6 .ad l
7 .\" Begin generated content:
8 .TH "RPM-LUA" "7" "2026-04-10" "RPM 6.0.1"
9 .PP
10 .SH NAME
11 .PP
12 rpm-lua - RPM embedded Lua interpreter
13 .PP
14 .SH SYNOPSIS
15 .PP
16 %scriptlet -p <lua>
17 .PP
18 %{lua:.\&.\&.\&}
19 .PP
20 .SH DESCRIPTION
21 Lua is a general purpose programming language specifically designed for
22 embedding in other programs, and RPM includes an embedded Lua interpreter
23 for use in advanced \fBrpm-macros\fR(7) and transaction scriptlets.\&
24 .PP
25 The embedded Lua interpreter makes possible various things that are
26 hard or impossible with plain macros or external shell scripts, such as
27 help eliminate dependency loops from package scriptlets.\&
28 .PP
29 .SH MACROS
30 .SS Accessing macros
31 The \fBrpm\fR extension has various functions for dealing with macros, but
32 the most convenient way to access \fBrpm-macroproc\fR(7) from the RPM Lua
33 environment is via the global \fBmacros\fR table.\&
34 .PP
35 Lua makes no difference between table index and field name syntaxes so
36 \fBmacros.\&foo\fR and \fBmacros['\&foo'\&]\fR are equivalent, use what better suits the
37 purpose.\&
38 .PP
39 Like any real Lua table, non-existent items are returned as \fBnil\fR,
40 and assignment can be used to define or undefine macros.\&
41 .PP
42 Example:
43 .nf
44 .RS 4
45 if not macros\&.yours then
46 macros\&.my = \&'my macro\&'
47 end
48
49 local v = { \&'_libdir\&', \&'_bindir\&', \&'_xbindir\&' }
50 for _, v in ipairs(v) do
51 if not macros[v] then
52 macros[v] = \&'default\&'
53 end
54 end
55 .fi
56 .RE
57 .PP
58 All macros share the same global Lua execution environment.\&
59 .PP
60 .SS Calling parametric macros
61 Parametric macros (including all built-in macros) can be called in a Lua
62 native manner via the \fBmacros\fR table, with either \fBmacros.\&\fR\fIname\fR\fB()\fR or
63 \fBmacros[\fR\fIname\fR\fB]()\fR syntax.\&
64 .PP
65 Arguments are passed through a single argument, which is either
66 .PD 0
67 .IP \(bu 4
68 a single string, in which case it'\&s expanded and split with the
69 macro-native rules
70 .IP \(bu 4
71 a table, in which case the table contents are used as literal arguments
72 that are not expanded in any way
73 .PD
74 .PP
75 Example 1:
76 .nf
77 .RS 4
78 macros\&.with(\&'foo\&')
79 .fi
80 .RE
81 .PP
82 Example 2:
83 .nf
84 .RS 4
85 macros\&.dostuff({\&'one\&', \&'two\&', \&'three\&'})
86 .fi
87 .RE
88 .PP
89 .SS Returning data
90 By definition, anything \fBprint()\fR'\&ed in Lua will end up in the macro
91 expansion.\& Lua macros can also \fBreturn\fR their output, which makes
92 programming helper macros look more natural.\&
93 .PP
94 Example:
95 .nf
96 .RS 4
97 %sum() %{lua:
98 local v = 0
99 for _, a in ipairs(arg) do
100 v = v + tonumber(a)
101 end
102 return v
103 }
104 .fi
105 .RE
106 .PP
107 .SS Options and arguments
108 Parametric Lua macros receive their options and arguments as two local
109 tables \fBopt\fR and \fBarg\fR, where \fBopt\fR holds processed option values keyed by
110 the option character, and \fBarg\fR contains arguments numerically indexed.\&
111 .PP
112 These tables are always present regardless of whether options or arguments
113 were actually passed to simplify use.\&
114 .PP
115 Example:
116 .nf
117 .RS 4
118 %foo(a:b) %{lua:
119 if opt\&.b then
120 print(\&'do b\&')
121 else
122 print(\&'or not\&')
123 end
124 if opt\&.a == \&'s\&' then
125 print(\&'do s\&')
126 end
127 if #arg == 0 then
128 print(\&'no arguments :(\&')
129 else
130 for i = 1, #arg do
131 print(arg[i])
132 end
133 end
134 }
135 .fi
136 .RE
137 .PP
138 .SH SCRIPTLETS
139 The internal Lua can be used as the interpreter of RPM any transaction
140 scriptlets, including triggers and file triggers:
141 .PP
142 Example:
143 .nf
144 .RS 4
145 %pre -p <lua>
146 print(\&'Hello from Lua\&')
147 .fi
148 .RE
149 .PP
150 While the venerable \fI/bin/sh\fR is usually more convenient for packaging related
151 scripting activities, the embedded Lua interpreter has some unique advantages
152 for transaction scriptlets: they add no extra dependencies to the packages
153 and so can help eliminate dependency loops.\& This can be a crucial
154 difference in the early "bootstrap" package set in an initial install.\&
155 .PP
156 In particular, an embedded Lua script is the only generally usable option
157 in \fB%pretrans\fR scriplets during the initial installation of a system.\&
158 .PP
159 Embedded Lua is also much faster than executing a potentially heavyweight
160 interpreter just to run a couple of lines of shell script.\&
161 .PP
162 Note: scriptlets using the internal Lua should not make assumptions about
163 sharing the execution environment with other scriptlets.\&
164 .PP
165 .SS Arguments
166 Scriptlet arguments are accessible from a global \fBarg\fR table.\&
167 .PP
168 Note: in Lua, indexes customarily start at 1 (one) instead of 0 (zero),
169 and for the better or worse, the RPM implementation follows this practise.\&
170 Thus the scriptlet arg indexes are off by one from general expectation based
171 on traditional scriptlet arguments.\& The argument containing number of
172 installed package instances is \fBarg[2]\fR and the similar argument for trigger
173 targets is \fBarg[3]\fR, vs the traditional \fB$1\fR and \fB$2\fR in shell scripts.\&
174 .PP
175 Example:
176 .nf
177 .RS 4
178 %postun -p <lua>
179 if arg[2] == 0 then
180 print("erasing")
181 end
182 .fi
183 .RE
184 .PP
185 .SS Relocatable packages
186 Scriptlets of relocatable packages additionally carry a global
187 \fBRPM_INSTALL_PREFIX\fR table containing all the possible prefixes of the
188 package.\&
189 .PP
190 Added: 4.\&18.\&0
191 .PP
192 .SS Exit status
193 While scriptlets shouldn'\&t be allowed to fail normally, you can signal
194 scriptlet failure status by using Lua'\&s \fBerror(\fR\fImsg\fR, [\fIlevel\fR]\fB)\fR
195 function if you need to.\&
196 .PP
197 .SH SPEC FILES
198 In the context of a \fBrpm-spec\fR(5) file parse with \fBrpmbuild\fR(1) or
199 \fBrpmspec\fR(1), the RPM Lua environment contains the following spec specific
200 global tables:
201 .PP
202 \fBpatches\fR
203 .RS 4
204 The filenames of the patches in the spec, in the
205 order they appeared in the spec.\&
206 .PP
207 .RE
208 \fBpatch_nums\fR
209 .RS 4
210 The numbers of the patches in the spec, in the
211 order they appeared in the spec.\&
212 .PP
213 .RE
214 \fBsources\fR
215 .RS 4
216 The filenames of the sources in the spec, in the
217 order they appeared in the spec.\&
218 .PP
219 .RE
220 \fBsource_nums\fR
221 .RS 4
222 The numbers of the sources in the spec, in the
223 order they appeared in the spec.\&
224 .PP
225 .RE
226 Example:
227 .nf
228 .RS 4
229 for i, p in ipairs(patches) do
230 print(string\&.format("echo %d: %sn", patch_nums[i], patches[i]))
231 end
232 .fi
233 .RE
234 .PP
235 .SH EXTENSIONS
236 In addition to Lua standard libraries (subject to the Lua version RPM
237 is linked to), the following extensions are available in the RPM internal
238 Lua interpreter.\& These can be used in all contexts where the internal
239 Lua can be used.\&
240 .PP
241 .SS rpm extension
242 .PP
243 The following RPM specific functions are available:
244 .PP
245 \fBb64decode(\fR\fIarg\fR\fB)\fR
246 .RS 4
247 Perform base64 decoding on argument.\&
248 See also b64encode().\&
249 .PP
250 Example:
251 .nf
252 .RS 4
253 blob = \&'binary data\&'
254 print(blob)
255 e = rpm\&.b64encode(blob)
256 print(e)
257 d = rpm\&.b64decode(e)
258 print(d)
259 .fi
260 .RE
261 .PP
262 .RE
263 \fBb64encode(\fR\fIarg\fR [, \fIlinelen\fR]\fB)\fR
264 .RS 4
265 Perform base64 encoding on argument.\&
266 Line length may be optionally specified via second argument.\&
267 See also b64decode().\&
268 .PP
269 .RE
270 \fBdefine("\fR\fIname\fR \fIbody\fR\fB")\fR
271 .RS 4
272 Define a global macro \fIname\fR with \fIbody\fR.\& See also \fBMACROS\fR.\&
273 .PP
274 Example:
275 .nf
276 .RS 4
277 rpm\&.define(\&'foo 1\&')
278 .fi
279 .RE
280 .PP
281 .RE
282 \fBexecute(\fR\fIpath\fR [, \fIarg1\fR [,.\&.\&.\&]\fB)\fR
283 .RS 4
284 Execute an external command.\&
285 This is handy for executing external helper commands without depending
286 on the shell.\& \fIpath\fR is the command to execute, followed
287 by optional number of arguments to pass to the command.\&
288 .PP
289 For a better control over the process execution and output,
290 see rpm.\&spawn().\&
291 .PP
292 Added: 4.\&15.\&0
293 .PP
294 Example:
295 .nf
296 .RS 4
297 rpm\&.execute(\&'ls\&', \&'-l\&', \&'/\&')
298 .fi
299 .RE
300 .RE
301 \fBexpand(\fR\fIarg\fR\fB)\fR
302 .RS 4
303 Perform RPM macro expansion on \fIarg\fR string.\& See also \fBMACROS\fR.\&
304 .PP
305 Example:
306 .nf
307 .RS 4
308 rpm\&.expand(\&'%{_libdir}/mydir\&')
309 .fi
310 .RE
311 .PP
312 .RE
313 \fBglob(\fR\fIpattern\fR, [\fIflags\fR]\fB)\fR
314 .RS 4
315 Return a table of pathnames matching \fIpattern\fR.\&
316 If \fIflags\fR contains \fBc\fR, return \fIpattern\fR in case of no matches.\&
317 .PP
318 Example:
319 .nf
320 .RS 4
321 for i, p in ipairs(rpm\&.glob(\&'*\&')) do
322 print(p)
323 end
324 .fi
325 .RE
326 .PP
327 .RE
328 \fBinteractive()\fR
329 .RS 4
330 Launch interactive session for testing and debugging.\&
331 Use \fBrpmlua\fR(1) instead.\&
332 .PP
333 Example:
334 .nf
335 .RS 4
336 rpm --eval "%{lua: rpm\&.interactive()}"
337 .fi
338 .RE
339 .PP
340 .RE
341 \fBisdefined(\fR\fIname\fR\fB)\fR
342 .RS 4
343 Test whether a macro \fIname\fR is defined and whether it'\&s parametric,
344 returned in two booleans.\& See also \fBMACROS\fR.\& (Added: 4.\&17.\&0)
345 .PP
346 Example:
347 .nf
348 .RS 4
349 if rpm\&.isdefined(\&'_libdir\&') then
350 \&.\&.\&.
351 end
352 .fi
353 .RE
354 .PP
355 .RE
356 \fBload(\fR\fIpath\fR\fB)\fR
357 .RS 4
358 Load a macro file from given path.\&
359 Same as the built-in \fB%{load:.\&.\&.\&}\fR macro.\&
360 .PP
361 Example:
362 .nf
363 .RS 4
364 rpm\&.load(\&'my\&.macros\&')
365 .fi
366 .RE
367 .PP
368 .RE
369 \fBopen(\fR\fIpath\fR, [\fImode\fR[.\&\fIflags\fR]]\fB)\fR
370 .RS 4
371 Open a file stream using RPM IO facilities, with support for
372 transparent compression and decompression.\&
373 .PP
374 \fIpath\fR is filename string, optionally followed with \fImode\fR string to
375 specify open behavior:
376 .PD 0
377 .IP \(bu 4
378 \fBa\fR: open for append
379 .IP \(bu 4
380 \fBw\fR: open for writing, truncate
381 .IP \(bu 4
382 \fBr\fR: open for reading (default)
383 .IP \(bu 4
384 \fB+\fR: open for reading and writing
385 .IP \(bu 4
386 \fBx\fR: fail if file exists
387 .PD
388 .PP
389 and optionally followed by \fBrpm-payloadflags\fR(7) for compression and
390 decompression.\&
391 .PP
392 Added: 4.\&17.\&0
393 .PP
394 Example:
395 .nf
396 .RS 4
397 f = rpm\&.open(\&'some\&.txt\&.gz\&', \&'r\&.gzdio\&')
398 print(f:read())
399 .fi
400 .RE
401 .PP
402 The returned rpm.\&fd object has the following methods:
403 .PP
404 \fBfd:close()\fR
405 .PP
406 Close the file stream.\&
407 .PP
408 Example:
409 .nf
410 .RS 4
411 f = rpm\&.open(\&'file\&')
412 f:close()
413 .fi
414 .RE
415 .PP
416 \fBfd:flush()\fR
417 .PP
418 Flush the file stream.\&
419 .PP
420 Example:
421 .nf
422 .RS 4
423 f = rpm\&.open(\&'file\&', \&'w\&')
424 f:write(\&'foo\&')
425 f:flush()
426 f:close()
427 .fi
428 .RE
429 .PP
430 \fBfd:read(\fR[\fIlen\fR]\fB)\fR
431 .PP
432 Read data from the file stream up to \fIlen\fR bytes or if not specified,
433 the entire file.\&
434 .PP
435 Example:
436 .nf
437 .RS 4
438 f = rpm\&.open(\&'/some/file\&')
439 print(f:read())
440 .fi
441 .RE
442 .PP
443 \fBfd:seek(\fR\fImode\fR, \fIoffset\fR\fB)\fR
444 .PP
445 Reposition the file offset of the stream.\& \fImode\fR is one of \fBset\fR,
446 \fBcur\fR and \fBend\fR, and offset is relative to the mode: absolute,
447 relative to current or relative to end.\& Not all streams support seeking.\&
448 .PP
449 Returns file offset after the operation.\&
450 .PP
451 See also \fBlseek\fR(3).\&
452 .PP
453 Example:
454 .nf
455 .RS 4
456 f = rpm\&.open(\&'newfile\&', \&'w\&')
457 f:seek(\&'set\&', 555)
458 f:close()
459 .fi
460 .RE
461 .PP
462 \fBfd:write(\fR\fIbuf\fR [, \fIlen\fR]\fB)\fR
463 .PP
464 Write data in \fIbuf\fR to the file stream, either in its entirety or up
465 to \fIlen\fR bytes if specified.\&
466 .PP
467 Example:
468 .nf
469 .RS 4
470 f = rpm\&.open(\&'newfile\&', \&'w\&')
471 f:write(\&'data data\&')
472 f:close()
473 .fi
474 .RE
475 .PP
476 \fBfd:reopen(\fR\fImode\fR\fB)\fR
477 .PP
478 Reopen a stream with a new mode (see \fBrpm.\&open()\fR).\&
479 .PP
480 Example:
481 .nf
482 .RS 4
483 rpm\&.open(\&'some\&.txt\&.gz\&')
484 f = f:reopen(\&'r\&.gzdio\&')
485 print(f:read())}
486 .fi
487 .RE
488 .PP
489 .RE
490 \fBredirect2null(\fR\fIfdno\fR\fB)\fR (OBSOLETE)
491 .RS 4
492 Redirect file descriptor fdno to /dev/null
493 (prior to 4.\&16 this was known as posix.\&redirect2null())
494 .PP
495 This function is obsolete and only available for RPM v4 packages
496 for backwards compatibility.\&
497 Use `rpm.\&spawn()` or `rpm.\&execute()` instead.\&
498 .PP
499 .nf
500 .RS 4
501 pid = posix\&.fork()
502 if pid == 0 then
503 posix\&.redirect2null(2)
504 assert(posix\&.exec(\&'/bin/awk\&'))
505 elseif pid > 0 then
506 posix\&.wait(pid)
507 end
508 .fi
509 .RE
510 .PP
511 .RE
512 \fBspawn(\fR{\fIcommand\fR} [, {\fIactions\fR}]\fB)\fR
513 .RS 4
514 Spawn, aka execute, an external program.\&
515 .PP
516 {\fIcommand\fR} is a table consisting of the command and its arguments.\&
517 An optional second table can be used to pass various actions related
518 to the command execution, currently supported are:
519 .PP
520 .nf
521 .RS 4
522 | Action | Argument(s) | Description
523 |---------|----------------------
524 | *stdin* | path | Redirect standard input to path
525 | *stdout*| path | Redirect standard output to path
526 | *stderr*| path | Redirect standard error to path
527 .fi
528 .RE
529 .PP
530 Returns the command exit status: zero on success, or a tuplet
531 of (\fBnil\fR, message, code) on failure.\&
532 .PP
533 Added: 4.\&20
534 .PP
535 Example:
536 .nf
537 .RS 4
538 rpm\&.spawn({\&'systemctl\&', \&'restart\&', \&'httpd\&'}, {stderr=\&'/dev/null\&'})
539 .fi
540 .RE
541 .PP
542 .RE
543 \fBundefine(\fR\fIname\fR\fB)\fR
544 .RS 4
545 Undefine a macro.\& See also \fBMACROS\fR.\&
546 .PP
547 Note that this is only pops the most recent macro definition by the
548 given name from stack, ie there may be still macro definitions by the
549 same name after an undefine operation.\&
550 .PP
551 Example:
552 .nf
553 .RS 4
554 rpm\&.undefine(\&'zzz\&')
555 .fi
556 .RE
557 .PP
558 .PP
559 .RE
560 \fBvercmp(\fR\fIv1\fR, \fIv2\fR\fB)\fR
561 .RS 4
562 Perform RPM version comparison on argument strings.\&
563 Returns -1, 0 or 1 if \fIv1\fR is smaller, equal or larger than \fIv2\fR.\&
564 See \fBrpm-version\fR(7).\&
565 .PP
566 Note: in RPM < 4.\&16 this operated on version segments only, which
567 does not produce correct results on full \fIEVR\fR strings.\&
568 .PP
569 Example:
570 .nf
571 .RS 4
572 rpm\&.vercmp(\&'1\&.2-1\&', \&'2\&.0-1\&')
573 .fi
574 .RE
575 .PP
576 .RE
577 \fBver(\fR\fIevr\fR\fB)\fR, \fBver(\fR\fIe\fR, \fIv\fR, \fIr\fR\fB)\fR
578 .RS 4
579 Create RPM version object.\&
580 This takes either an \fIevr\fR string which is parsed to it'\&s components,
581 or epoch, version and release in separate arguments (which can be either
582 strings or numbers).\& The object has three attributes: \fBe\fR for epoch,
583 \fBv\fR for version and \fBr\fR for release, can be printed in it'\&s EVR form and
584 supports native comparison in Lua.\&
585 .PP
586 Added: 4.\&17.\&0
587 .PP
588 Example:
589 .nf
590 .RS 4
591 v1 = rpm\&.ver(\&'5:1\&.0-2)
592 v2 = rpm\&.ver(3, \&'5a\&', 1)
593 if v1 < v2 then
594 \&.\&.\&.
595 end
596
597 if v1\&.e then
598 \&.\&.\&.
599 end
600 .fi
601 .RE
602 .PP
603 .RE
604 .SS posix extension
605 .PP
606 Lua standard library offers fairly limited set of io operations.\&
607 The \fBposix\fR extension greatly enhances what can be done from Lua.\&
608 .PP
609 The following functions are available in the \fBposix\fR namespace, ie to call
610 them use \fBposix.\&function()\fR.\& This documentation concentrates on the Lua
611 API conventions, for further information on the corresponding system
612 calls refer to the system manual, eg \fBaccess\fR(3) for \fBposix.\&access()\fR.\&
613 .PP
614 \fBaccess(\fR\fIpath\fR [, \fImode\fR]\fB)\fR
615 .RS 4
616 Test accessibility of file/directory \fIpath\fR.\& See \fBaccess\fR(3).\&
617 If \fImode\fR is omitted then existence is tested, otherwise it is
618 a combination of the following tests:
619 .PD 0
620 .IP \(bu 4
621 \fBr\fR: readable
622 .IP \(bu 4
623 \fBw\fR: writable
624 .IP \(bu 4
625 \fBx\fR: executable
626 .IP \(bu 4
627 \fBf\fR: exists
628 .PD
629 .PP
630 Example:
631 .nf
632 .RS 4
633 if posix\&.access(\&'/bin/rpm\&', \&'x\&') then
634 \&.\&.\&.
635 end
636 .fi
637 .RE
638 .PP
639 .RE
640 \fBchdir(\fR\fIpath\fR\fB)\fR
641 .RS 4
642 Change current working directory to \fIpath\fR.\& See \fBchdir\fR(1).\&
643 .PP
644 Example:
645 .nf
646 .RS 4
647 posix\&.chdir(\&'/tmp\&')
648 .fi
649 .RE
650 .PP
651 .RE
652 \fBchmod(\fR\fIpath\fR, \fImode\fR\fB)\fR
653 .RS 4
654 Change file/directory mode.\& Mode can be either an octal number as for
655 \fBchmod\fR(2) system call, or a string presentation similar to \fBchmod\fR(1).\&
656 .PP
657 Example:
658 .nf
659 .RS 4
660 posix\&.chmod(\&'aa\&', 600)
661 posix\&.chmod(\&'bb\&', \&'rw-\&')
662 posix\&.chmod(\&'cc\&', \&'u+x\&')
663 .fi
664 .RE
665 .PP
666 .RE
667 \fBchown(\fR\fIpath\fR, \fIuser\fR, \fIgroup\fR\fB)\fR
668 .RS 4
669 Change file/directory owner/group of \fIpath\fR.\& The \fIuser\fR and \fIgroup\fR
670 arguments may be either numeric id values or user/groupnames.\&
671 See \fBchown\fR(2) and \fBchown\fR(1).\&
672 .PP
673 Note: This is a privileged operation.\&
674 .PP
675 Example:
676 .nf
677 .RS 4
678 posix\&.chown(\&'aa\&', 0, 0)
679 posix\&.chown(\&'bb\&', \&'nobody\&', \&'nobody\&')
680 .fi
681 .RE
682 .PP
683 .RE
684 \fBctermid()\fR
685 .RS 4
686 Get controlling terminal name.\& See \fBctermid\fR(3).\&
687 .PP
688 Example:
689 .nf
690 .RS 4
691 print(posix\&.ctermid())
692 .fi
693 .RE
694 .PP
695 .RE
696 \fBdir(\fR[\fIpath\fR]\fB)\fR
697 .RS 4
698 Get directory contents - like \fBreaddir\fR(3).\& If \fIpath\fR is omitted,
699 current directory is used.\&
700 .PP
701 Example:
702 .nf
703 .RS 4
704 for i,p in pairs(posix\&.dir(\&'/\&')) do
705 print(p\&.\&.\&'n\&')
706 end
707 .fi
708 .RE
709 .PP
710 .RE
711 \fBerrno()\fR
712 .RS 4
713 Get \fBstrerror\fR(3) message and the corresponding number for current
714 \fBerrno\fR(3).\&
715 .PP
716 Example:
717 .nf
718 .RS 4
719 f = \&'/zzz\&'
720 if not posix\&.chmod(f, 100) then
721 s, n = posix\&.errno()
722 print(f, s)
723 end
724 .fi
725 .RE
726 .PP
727 .RE
728 \fBexec(\fR\fIpath\fR [, \fIargs\fR.\&.\&.\&]\fB)\fR (OBSOLETE)
729 .RS 4
730 Execute a program.\& This may only be performed after posix.\&fork().\&
731 .PP
732 This function is obsolete and only available for RPM v4 packages
733 for backwards compatibility.\&
734 Use \fBrpm.\&spawn()\fR or \fBrpm.\&execute()\fR instead.\&
735 .PP
736 .RE
737 \fBfiles(\fR[\fIpath\fR]\fB)\fR
738 .RS 4
739 Iterate over directory contents.\& If path is omitted, current directory
740 is used.\&
741 .PP
742 Example:
743 .nf
744 .RS 4
745 for f in posix\&.files(\&'/\&') do
746 print(f\&.\&.\&'n\&')
747 end
748 .fi
749 .RE
750 .PP
751 .RE
752 \fBfork()\fR (OBSOLETE)
753 .RS 4
754 Fork a new process.\& See \fBfork\fR(2).\&
755 .PP
756 This function is obsolete and only available for RPM v4 packages
757 for backwards compatibility.\&
758 Use \fBrpm.\&spawn()\fR or \fBrpm.\&execute()\fR instead.\&
759 .PP
760 Example:
761 .nf
762 .RS 4
763 pid = posix\&.fork()
764 if pid == 0 then
765 posix\&.exec(\&'/foo/bar\&')
766 elseif pid > 0 then
767 posix\&.wait(pid)
768 end
769 .fi
770 .RE
771 .PP
772 .RE
773 \fBgetcwd()\fR
774 .RS 4
775 Get current directory.\& See \fBgetcwd\fR(3).\&
776 .PP
777 Example:
778 .nf
779 .RS 4
780 if posix\&.getcwd() ~= \&'/\&' then
781 \&.\&.\&.
782 endif
783 .fi
784 .RE
785 .PP
786 .RE
787 \fBgetenv(\fR\fIname\fR\fB)\fR
788 .RS 4
789 Get an environment variable.\& See \fBgetenv\fR(3).\&
790 .PP
791 Example:
792 .nf
793 .RS 4
794 if posix\&.getenv(\&'HOME\&') ~= posix\&.getcwd() then
795 print(\&'not at home\&')
796 end
797 .fi
798 .RE
799 .PP
800 .RE
801 \fBgetgroup(\fR\fIgroup\fR\fB)\fR
802 .RS 4
803 Get \fBgroup\fR(5) information for a group.\& \fIgroup\fR may be either a
804 numeric id or group name.\& If omitted, current group is used.\&
805 Returns a table with fields \fBname\fR and \fBgid\fR set to group
806 name and id respectively, and indexes from 1 onwards specifying group
807 members.\&
808 .PP
809 Example:
810 .nf
811 .RS 4
812 print(posix\&.getgroup(\&'wheel\&')\&.gid)
813 .fi
814 .RE
815 .PP
816 .RE
817 \fBgetlogin()\fR
818 .RS 4
819 Get login name.\& See \fBgetlogin\fR(3).\&
820 .PP
821 Example:
822 .nf
823 .RS 4
824 n = posix\&.getlogin()
825 .fi
826 .RE
827 .PP
828 .RE
829 \fBgetpasswd\fR([\fIuser\fR [, \fIselector\fR]]\fB)\fR
830 .RS 4
831 Get \fBpasswd\fR(5) information for a user account.\& \fIuser\fR may be either a
832 numeric id or username.\& If omitted, current user is used.\&
833 The optional \fIselector\fR argument may be one of:
834 .PD 0
835 .IP \(bu 4
836 \fBname\fR
837 .IP \(bu 4
838 \fBuid\fR
839 .IP \(bu 4
840 \fBgid\fR
841 .IP \(bu 4
842 \fBdir\fR
843 .IP \(bu 4
844 \fBshell\fR
845 .IP \(bu 4
846 \fBgecos\fR
847 .IP \(bu 4
848 \fBpasswd\fR
849 .PD
850 .PP
851 If omitted, a table with all these fields is returned.\&
852 .PP
853 Example:
854 .nf
855 .RS 4
856 pw = posix\&.getpasswd(posix\&.getlogin(), \&'shell\&')|
857 .fi
858 .RE
859 .PP
860 .RE
861 \fBgetprocessid(\fR[\fIselector\fR]\fB)\fR
862 .RS 4
863 Get information about current process.\& The optional \fIselector\fR
864 argument may be one of
865 .PD 0
866 .IP \(bu 4
867 \fBegid\fR: effective group id
868 .IP \(bu 4
869 \fBeuid\fR: effective user id
870 .IP \(bu 4
871 \fBgid\fR: group id
872 .IP \(bu 4
873 \fBuid\fR: user id
874 .IP \(bu 4
875 \fBpgrp\fR: parent group id
876 .IP \(bu 4
877 \fBpid\fR: process id
878 .IP \(bu 4
879 \fBppid\fR: parent pid
880 .PD
881 .PP
882 If omitted, a table with all these fields is returned.\&
883 .PP
884 Example:
885 .nf
886 .RS 4
887 if posix\&.getprocessid(\&'pid\&') == 1 then
888 \&.\&.\&.
889 end
890 .fi
891 .RE
892 .PP
893 .RE
894 \fBkill(\fR\fIpid\fR [, \fIsignal\fR]\fB)\fR
895 .RS 4
896 Send a \fBsignal\fR(7) to a process.\& \fIsignal\fR must be a numeric value,
897 eg.\& \fB9\fR for \fBSIGKILL\fR.\& If omitted, \fBSIGTERM\fR is used.\&
898 See also \fBkill\fR(2).\&
899 .PP
900 Example:
901 .nf
902 .RS 4
903 posix\&.kill(posix\&.getprocessid(\&'pid\&'))
904 .fi
905 .RE
906 .PP
907 .RE
908 \fBlink(\fR\fIoldpath\fR, \fInewpath\fR\fB)\fR
909 .RS 4
910 Create a new name at \fInewpath\fR for a file at \fIoldpath\fR, aka hard link.\&
911 See also \fBlink\fR(2).\&
912 .PP
913 Example:
914 .nf
915 .RS 4
916 f = rpm\&.open(\&'aaa\&', \&'w\&')
917 posix\&.link(\&'aaa\&', \&'bbb\&')
918 .fi
919 .RE
920 .PP
921 .RE
922 \fBmkdir(\fR\fIpath\fR\fB)\fR
923 .RS 4
924 Create a new directory at \fIpath\fR.\& See also \fBmkdir\fR(2).\&
925 .PP
926 Example:
927 .nf
928 .RS 4
929 posix\&.mkdir(\&'/tmp\&')
930 .fi
931 .RE
932 .PP
933 .RE
934 \fBmkfifo(\fR\fIpath\fR\fB)\fR
935 .RS 4
936 Create a FIFO aka named pipe at \fIpath\fR.\& See also \fBmkfifo\fR(2).\&
937 .PP
938 Example:
939 .nf
940 .RS 4
941 posix\&.mkfifo(\&'/tmp/badplace\&')
942 .fi
943 .RE
944 .PP
945 .RE
946 \fBpathconf(\fR\fIpath\fR [, \fIselector\fR]\fB)\fR
947 .RS 4
948 Get \fBpathconf\fR(3) information for \fIpath\fR.\&
949 The optional \fIselector\fR may be one of
950 .PD 0
951 .IP \(bu 4
952 \fBlink_max\fR
953 .IP \(bu 4
954 \fBmax_canon\fR
955 .IP \(bu 4
956 \fBmax_input\fR
957 .IP \(bu 4
958 \fBname_max\fR
959 .IP \(bu 4
960 \fBpath_max\fR
961 .IP \(bu 4
962 \fBpipe_buf\fR
963 .IP \(bu 4
964 \fBchown_restricted\fR
965 .IP \(bu 4
966 \fBno_trunc\fR
967 .IP \(bu 4
968 \fBvdisable\fR.\&
969 .PD
970 .PP
971 If omitted, a table with all these fields is returned.\&
972 .PP
973 Example:
974 .nf
975 .RS 4
976 posix\&.pathconf(\&'/\&', \&'path_max\&')
977 .fi
978 .RE
979 .PP
980 .RE
981 \fBputenv(\fR\fIstring\fR\fB)\fR
982 .RS 4
983 Change or add an environment variable.\& See also \fBputenv\fR(3).\&
984 .PP
985 Example:
986 .nf
987 .RS 4
988 posix\&.putenv(\&'HOME=/me\&')
989 .fi
990 .RE
991 .PP
992 .RE
993 \fBreadlink(\fR\fIpath\fR\fB)\fR
994 .RS 4
995 Read value of the symbolic link at \fIpath\fR.\& See also \fBreadlink\fR(2).\&
996 .PP
997 Example:
998 .nf
999 .RS 4
1000 posix\&.mkdir(\&'aaa\&')
1001 posix\&.symlink(\&'aaa\&', \&'bbb\&')
1002 print(posix\&.readlink(\&'bbb\&'))
1003 .fi
1004 .RE
1005 .PP
1006 .RE
1007 \fBrmdir(\fR\fIpath\fR\fB)\fR
1008 .RS 4
1009 Remove a directory \fIpath\fR.\& See also \fBrmdir\fR(2).\&
1010 .PP
1011 Example:
1012 .nf
1013 .RS 4
1014 posix\&.rmdir(\&'/tmp\&')
1015 .fi
1016 .RE
1017 .PP
1018 .RE
1019 \fBsetgid(\fR\fIgroup\fR\fB)\fR
1020 .RS 4
1021 Set group identity.\& \fIgroup\fR may be specified either as a numeric id or
1022 group name.\& See also \fBsetgid\fR(2).\&
1023 .PP
1024 Note: This is a privileged operation.\&
1025 .PP
1026 .RE
1027 \fBsetuid(\fR\fIuser\fR\fB)\fR
1028 .RS 4
1029 Set user identity.\& \fIuser\fR may be specified either as a numeric id or
1030 username.\& See also \fBsetuid\fR(2).\&
1031 .PP
1032 Note: This is a privileged operation.\&
1033 .PP
1034 Example:
1035 .nf
1036 .RS 4
1037 posix\&.setuid(\&'nobody\&')
1038 .fi
1039 .RE
1040 .PP
1041 .RE
1042 \fBsleep(\fR\fIseconds\fR\fB)\fR
1043 .RS 4
1044 Sleep for the duration of \fIseconds\fR.\& See also \fBsleep\fR(3).\&
1045 .PP
1046 Example:
1047 .nf
1048 .RS 4
1049 posix\&.sleep(5)
1050 .fi
1051 .RE
1052 .PP
1053 .RE
1054 \fBstat(\fR\fIpath\fR [, \fIselector\fR]\fB)\fR
1055 .RS 4
1056 Get file \fBstat\fR(3) information about a file at \fIpath\fR.\&
1057 The optional \fIselector\fR may be one of
1058 .PD 0
1059 .IP \(bu 4
1060 \fBmode\fR
1061 .IP \(bu 4
1062 \fBino\fR
1063 .IP \(bu 4
1064 \fBdev\fR
1065 .IP \(bu 4
1066 \fBnlink\fR
1067 .IP \(bu 4
1068 \fBuid\fR
1069 .IP \(bu 4
1070 \fBgid\fR
1071 .IP \(bu 4
1072 \fBsize\fR
1073 .IP \(bu 4
1074 \fBatime\fR
1075 .IP \(bu 4
1076 \fBmtime\fR
1077 .IP \(bu 4
1078 \fBctime\fR
1079 .IP \(bu 4
1080 \fBtype\fR.\&
1081 .PD
1082 .PP
1083 If omitted, a table with all these fields is returned.\&
1084 .PP
1085 Example:
1086 .nf
1087 .RS 4
1088 print(posix\&.stat(\&'/tmp\&', \&'mode\&'))|
1089
1090 s1 = posix\&.stat(\&'f1\&')
1091 s2 = posix\&.stat(\&'f2\&')
1092 if s1\&.ino == s2\&.ino and s1\&.dev == s2\&.dev then
1093 \&.\&.\&.
1094 end
1095 .fi
1096 .RE
1097 .PP
1098 .RE
1099 \fBsymlink(\fR\fIoldpath\fR, \fInewpath\fR\fB)\fR
1100 .RS 4
1101 Create a symbolic link at \fInewpath\fR to \fIoldpath\fR.\&
1102 See also \fBsymlink\fR(2).\&
1103 .PP
1104 Example:
1105 .nf
1106 .RS 4
1107 posix\&.mkdir(\&'aaa\&')
1108 posix\&.symlink(\&'aaa\&', \&'bbb\&')
1109 .fi
1110 .RE
1111 .PP
1112 .RE
1113 \fBsysconf(\fR[\fIselector\fR]\fB)\fR
1114 .RS 4
1115 Get \fBsysconf\fR(3) information.\& The optional \fIselector\fR argument
1116 may be one of:
1117 .PD 0
1118 .IP \(bu 4
1119 \fBarg_max\fR
1120 .IP \(bu 4
1121 \fBchild_max\fR
1122 .IP \(bu 4
1123 \fBclk_tck\fR
1124 .IP \(bu 4
1125 \fBngroups_max\fR
1126 .IP \(bu 4
1127 \fBstream_max\fR
1128 .IP \(bu 4
1129 \fBtzname_max\fR
1130 .IP \(bu 4
1131 \fBopen_max\fR
1132 .IP \(bu 4
1133 \fBjob_control\fR
1134 .IP \(bu 4
1135 \fBsaved_ids\fR
1136 .IP \(bu 4
1137 \fBversion\fR.\&
1138 .PD
1139 .PP
1140 If omitted, a table with all these fields is returned.\&
1141 .PP
1142 Example:
1143 .nf
1144 .RS 4
1145 posix\&.sysconf(\&'open_max\&')|
1146 .fi
1147 .RE
1148 .PP
1149 .RE
1150 \fBtimes(\fR[\fIselector\fR]\fB)\fR
1151 .RS 4
1152 Get process and waited-for child process \fBtimes\fR(2).\&
1153 The optional \fIselector\fR argument may be one of
1154 .PD 0
1155 .IP \(bu 4
1156 \fButime\fR
1157 .IP \(bu 4
1158 \fBstime\fR
1159 .IP \(bu 4
1160 \fBcutime\fR
1161 .IP \(bu 4
1162 \fBcstime\fR
1163 .IP \(bu 4
1164 \fBelapsed\fR
1165 .PD
1166 .PP
1167 If omitted, a table with all these fields is returned.\&
1168 .PP
1169 Example:
1170 .nf
1171 .RS 4
1172 t = posix\&.times()
1173 print(t\&.utime, t\&.stime)
1174 .fi
1175 .RE
1176 .PP
1177 .RE
1178 \fBttyname(\fR[\fIfd\fR]\fB)\fR
1179 .RS 4
1180 Get name of a terminal associated with file descriptor \fIfd\fR.\&
1181 If \fIfd\fR is omitted, \fB0\fR (aka standard input) is used.\& See \fBttyname\fR(3).\&
1182 .PP
1183 Example:
1184 .nf
1185 .RS 4
1186 if not posix\&.ttyname() then
1187 \&.\&.\&.
1188 endif
1189 .fi
1190 .RE
1191 .PP
1192 .RE
1193 \fBumask(\fR[\fImode\fR]\fB)\fR
1194 .RS 4
1195 Get or set process \fBumask\fR(2).\& \fImode\fR may be specified as an octal
1196 number or mode string similarly to \fBposix.\&chmod()\fR.\&
1197 .PP
1198 Example:
1199 .nf
1200 .RS 4
1201 print(posix\&.umask())
1202 posix\&.umask(222)
1203 posix\&.umask(\&'ug-w\&')
1204 posix\&.umask(\&'rw-rw-r--\&')
1205 .fi
1206 .RE
1207 .PP
1208 .RE
1209 \fBuname(\fR\fIformat\fR\fB)\fR
1210 .RS 4
1211 Get \fBuname\fR(2) information about the current system.\&
1212 The following format directives are supported:
1213 .PP
1214 .PD 0
1215 .IP \(bu 4
1216 \fB%m\fR: Name of the hardware type
1217 .IP \(bu 4
1218 \fB%n\fR: Name of this node
1219 .IP \(bu 4
1220 \fB%r\fR: Current release level of this implementation
1221 .IP \(bu 4
1222 \fB%s\fR: Name of this operation system
1223 .IP \(bu 4
1224 \fB%v\fR: Current version level of this implementation
1225 .PD
1226 .PP
1227 Example:
1228 .nf
1229 .RS 4
1230 print(posix\&.uname(\&'%s %r\&'))
1231 .fi
1232 .RE
1233 .PP
1234 .RE
1235 \fButime(\fR\fIpath\fR [, \fImtime\fR [, \fIctime\fR]]\fB)\fR
1236 .RS 4
1237 Change last access and modification times.\&
1238 mtime and ctime are expressed seconds since epoch.\& See \fButime\fR(2).\&
1239 .PP
1240 If \fImtime\fR or \fIctime\fR are omitted, current time is used, similar
1241 to \fBtouch\fR(1).\&
1242 .PP
1243 Example:
1244 .nf
1245 .RS 4
1246 posix\&.mkdir(\&'aaa\&')
1247 posix\&.utime(\&'aaa\&', 0, 0)
1248 .fi
1249 .RE
1250 .PP
1251 .RE
1252 \fBwait(\fR[\fIpid\fR]\fB)\fR (DEPRECATED)
1253 .RS 4
1254 Wait for a child process.\& If \fIpid\fR is specified wait for that
1255 particular child.\& See also \fBwait\fR(2).\&
1256 .PP
1257 This function is obsolete and only available for RPM v4 packages
1258 for backwards compatibility.\&
1259 Use \fBrpm.\&spawn()\fR or \fBrpm.\&execute()\fR instead.\&
1260 .PP
1261 Example:
1262 .nf
1263 .RS 4
1264 pid = posix\&.fork()
1265 if pid == 0 then
1266 posix\&.exec(\&'/bin/ls\&'))
1267 elseif pid > 0 then
1268 posix\&.wait(pid)
1269 end
1270 .fi
1271 .RE
1272 .PP
1273 .PP
1274 .RE
1275 \fBsetenv(\fR\fIname\fR, \fIvalue\fR [, \fIoverwrite\fR]\fB)\fR
1276 .RS 4
1277 Change or add environment variable \fIname\fR.\& The optional \fIoverwrite\fR
1278 is a boolean which defines behavior when a variable by the same name
1279 already exists.\& See also \fBsetenv\fR(3).\&
1280 .PP
1281 Example:
1282 .nf
1283 .RS 4
1284 posix\&.setenv(\&'HOME\&', \&'/me\&', true)
1285 .fi
1286 .RE
1287 .PP
1288 .RE
1289 \fBunsetenv(\fR\fIname\fR\fB)\fR
1290 .RS 4
1291 Remove a variable \fIname\fR from environment.\& See also \fBunsetenv\fR(3).\&
1292 .PP
1293 Example:
1294 .nf
1295 .RS 4
1296 posix\&.unsetenv(\&'HOME\&')
1297 .fi
1298 .RE
1299 .PP
1300 .RE
1301 .SH EXTENDING AND CUSTOMIZING
1302 On initialization, RPM executes a global \fIinit.\&lua\fR Lua initialization
1303 script from the directory \fB%getconfdir\fR expands to, typically
1304 \fI/usr/lib/rpm/init.\&lua\fR.\& This can be used to customize the rpm Lua
1305 environment without recompiling RPM.\&
1306 .PP
1307 For the embedded Lua interpreter, module'\&s loaded with \fBrequire\fR are
1308 primarily searched from \fB%{getconfdir}/lua/\fR.\& \fB%_rpmluadir\fR is a shorthand
1309 for this path.\&
1310 .PP
1311 .SH SEE ALSO
1312 \fBrpm-macros\fR(7) \fBrpm-payloadflags\fR(7) \fBrpmlua\fR(1) \fBrpm-version\fR(7)
1313 .PP
1314 \fBhttps://www.\&lua.\&org/\fR