iPXE scripts More...

#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include <ctype.h>
#include <errno.h>
#include <getopt.h>
#include <ipxe/command.h>
#include <ipxe/parseopt.h>
#include <ipxe/image.h>
#include <ipxe/shell.h>
#include <usr/prompt.h>
#include <ipxe/script.h>

Data Structures
struct	goto_options
	"goto" options More...

struct	prompt_options
	"prompt" options More...

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)

	FILE_SECBOOT (PERMITTED)

static int	process_script (struct image image, int(process_line)(struct image image, size_t offset, const char label, const char command), int(terminate)(int rc))
	Process script lines. More...

static int	terminate_on_exit_or_failure (int rc)
	Terminate script processing on shell exit or command failure. More...

static int	script_exec_line (struct image image, size_t offset, const char label __unused, const char *command)
	Execute script line. More...

static int	script_exec (struct image *image)
	Execute script. More...

static int	script_probe (struct image *image)
	Probe script image. More...

struct image_type script_image_type	__image_type (PROBE_NORMAL)
	Script image type. More...

static int	goto_find_label (struct image image, size_t offset, const char label, const char *command __unused)
	Check for presence of label. More...

static int	terminate_on_label_found (int rc)
	Terminate script processing when label is found. More...

static int	goto_exec (int argc, char **argv)
	"goto" command More...

	COMMAND (goto, goto_exec)
	"goto" command More...

static int	prompt_exec (int argc, char **argv)
	"prompt" command More...

	COMMAND (prompt, prompt_exec)
	"prompt" command More...

Variables
static size_t	script_offset
	Offset within current script. More...

static struct option_descriptor	goto_opts [] = {}
	"goto" option list More...

static struct command_descriptor	goto_cmd
	"goto" command descriptor More...

static const char *	goto_label
	Current "goto" label. More...

static struct option_descriptor	prompt_opts []
	"prompt" option list More...

static struct command_descriptor	prompt_cmd
	"prompt" command descriptor More...

Detailed Description

iPXE scripts

Definition in file script.c.

Function Documentation

◆ FILE_LICENCE()

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL )

◆ FILE_SECBOOT()

FILE_SECBOOT ( PERMITTED )

◆ process_script()

static int process_script	(	struct image *	image,
		int()(struct image image, size_t offset, const char label, const char command)	process_line,
		int(*)(int rc)	terminate
	)

static

Process script lines.

Parameters

image	Script
process_line	Line processor
terminate	Termination check

Return values

rc	Return status code

Definition at line 62 of file script.c.

                                                              {
         size_t len = 0;
         char *line = NULL;
         size_t line_offset;
         char *label;
         char *command;
         const void *eol;
         size_t frag_len;
         char *tmp;
         int rc;
 
         /* Initialise script and line offsets */
         script_offset = 0;
         line_offset = 0;
 
         do {
 
                 /* Find length of next line, excluding any terminating '\n' */
                 eol = memchr ( ( image->data + script_offset ), '\n',
                                ( image->len - script_offset ) );
                 if ( eol ) {
                         frag_len = ( ( eol - image->data ) - script_offset );
                 } else {
                         frag_len = ( image->len - script_offset );
                 }
 
                 /* Allocate buffer for line */
                 tmp = realloc ( line, ( len + frag_len + 1 /* NUL */ ) );
                 if ( ! tmp ) {
                         rc = -ENOMEM;
                         goto err_alloc;
                 }
                 line = tmp;
 
                 /* Copy line */
                 memcpy ( ( line + len ), ( image->data + script_offset ),
                          frag_len );
                 len += frag_len;
 
                 /* Move to next line in script */
                 script_offset += ( frag_len + 1 );
 
                 /* Strip trailing CR, if present */
                 if ( len && ( line[ len - 1 ] == '\r' ) )
                         len--;
 
                 /* Handle backslash continuations */
                 if ( len && ( line[ len - 1 ] == '\\' ) ) {
                         len--;
                         rc = -EINVAL;
                         continue;
                 }
 
                 /* Terminate line */
                 line[len] = '\0';
 
                 /* Split line into (optional) label and command */
                 command = line;
                 while ( isspace ( *command ) )
                         command++;
                 if ( *command == ':' ) {
                         label = ++command;
                         while ( *command && ! isspace ( *command ) )
                                 command++;
                         if ( *command )
                                 *(command++) = '\0';
                 } else {
                         label = NULL;
                 }
 
                 /* Process line */
                 rc = process_line ( image, line_offset, label, command );
                 if ( terminate ( rc ) )
                         goto err_process;
 
                 /* Free line */
                 free ( line );
                 line = NULL;
                 len = 0;
 
                 /* Update line offset */
                 line_offset = script_offset;
 
         } while ( script_offset < image->len );
 
  err_process:
  err_alloc:
         free ( line );
         return rc;
 }

References command, image::data, EINVAL, ENOMEM, free, isspace(), image::len, len, memchr(), memcpy(), NULL, rc, realloc(), script_offset, and tmp.

Referenced by goto_exec(), and script_exec().

◆ terminate_on_exit_or_failure()

static int terminate_on_exit_or_failure ( int rc )

static

Terminate script processing on shell exit or command failure.

Parameters

rc	Line processing status

Return values

terminate Terminate script processing

Definition at line 164 of file script.c.

                                                    {
 
         return ( shell_stopped ( SHELL_STOP_COMMAND_SEQUENCE ) ||
                  ( rc != 0 ) );
 }

References rc, SHELL_STOP_COMMAND_SEQUENCE, and shell_stopped().

Referenced by script_exec().

◆ script_exec_line()

static int script_exec_line	(	struct image *	image,
		size_t	offset,
		const char *label	__unused,
		const char *	command
	)

static

Execute script line.

Parameters

image	Script
offset	Offset within script
label	Label, or NULL
command	Command

Return values

rc	Return status code

Definition at line 179 of file script.c.

                                                     {
         int rc;
 
         DBGC ( image, "[%04zx] $ %s\n", offset, command );
 
         /* Execute command */
         if ( ( rc = system ( command ) ) != 0 )
                 return rc;
 
         return 0;
 }

References DBGC, offset, rc, and system.

Referenced by script_exec().

◆ script_exec()

static int script_exec ( struct image * image )

static

Execute script.

Parameters

image Script

Return values

rc	Return status code

Definition at line 199 of file script.c.

                                                {
         size_t saved_offset;
         int rc;
 
         /* Preserve state of any currently-running script */
         saved_offset = script_offset;
 
         /* Process script */
         rc = process_script ( image, script_exec_line,
                               terminate_on_exit_or_failure );
 
         /* Restore saved state */
         script_offset = saved_offset;
 
         return rc;
 }

References process_script(), rc, script_exec_line(), script_offset, and terminate_on_exit_or_failure().

◆ script_probe()

static int script_probe ( struct image * image )

static

Probe script image.

Parameters

image Script

Return values

rc	Return status code

Definition at line 222 of file script.c.

                                                 {
         static const char ipxe_magic[] = "#!ipxe";
         static const char gpxe_magic[] = "#!gpxe";
         static_assert ( sizeof ( ipxe_magic ) == sizeof ( gpxe_magic ) );
         const struct {
                 char magic[ sizeof ( ipxe_magic ) - 1 /* NUL */ ];
                 char space;
         } __attribute__ (( packed )) *test;
 
         /* Sanity check */
         if ( image->len < sizeof ( *test ) ) {
                 DBGC ( image, "Too short to be a script\n" );
                 return -ENOEXEC;
         }
 
         /* Check for magic signature */
         test = image->data;
         if ( ! ( ( ( memcmp ( test->magic, ipxe_magic,
                               sizeof ( test->magic ) ) == 0 ) ||
                    ( memcmp ( test->magic, gpxe_magic,
                               sizeof ( test->magic ) ) == 0 ) ) &&
                  isspace ( test->space ) ) ) {
                 DBGC ( image, "Invalid magic signature\n" );
                 return -ENOEXEC;
         }
 
         return 0;
 }

References __attribute__, image::data, DBGC, ENOEXEC, isspace(), image::len, magic, memcmp(), static_assert, and test.

◆ __image_type()

struct image_type script_image_type __image_type ( PROBE_NORMAL )

Script image type.

◆ goto_find_label()

static int goto_find_label	(	struct image *	image,
		size_t	offset,
		const char *	label,
		const char *command	__unused
	)

static

Check for presence of label.

Parameters

image	Script
offset	Offset within script
label	Label
command	Command

Return values

rc	Return status code

Definition at line 284 of file script.c.

                                                                                {
 
         /* Check label exists */
         if ( ! label )
                 return -ENOENT;
 
         /* Check label matches */
         if ( strcmp ( goto_label, label ) != 0 )
                 return -ENOENT;
 
         /* Update script offset */
         script_offset = offset;
         DBGC ( image, "[%04zx] Gone to :%s\n", offset, label );
 
         return 0;
 }

References DBGC, ENOENT, goto_label, offset, script_offset, and strcmp().

Referenced by goto_exec().

◆ terminate_on_label_found()

static int terminate_on_label_found ( int rc )

static

Terminate script processing when label is found.

Parameters

rc	Line processing status

Return values

terminate Terminate script processing

Definition at line 308 of file script.c.

                                                {
         return ( rc == 0 );
 }

References rc.

Referenced by goto_exec().

◆ goto_exec()

static int goto_exec	(	int	argc,
		char **	argv
	)

static

"goto" command

Parameters

argc	Argument count
argv	Argument list

Return values

rc	Return status code

Definition at line 319 of file script.c.

                                                {
         struct image *image = current_image.image;
         struct goto_options opts;
         size_t saved_offset;
         int rc;
 
         /* Parse options */
         if ( ( rc = parse_options ( argc, argv, &goto_cmd, &opts ) ) != 0 )
                 return rc;
 
         /* Sanity check */
         if ( ! image ) {
                 rc = -ENOTTY;
                 printf ( "Not in a script: %s\n", strerror ( rc ) );
                 return rc;
         }
 
         /* Parse label */
         goto_label = argv[optind];
 
         /* Find label */
         saved_offset = script_offset;
         if ( ( rc = process_script ( image, goto_find_label,
                                      terminate_on_label_found ) ) != 0 ) {
                 script_offset = saved_offset;
                 DBGC ( image, "[%04zx] No such label :%s\n",
                        script_offset, goto_label );
                 return rc;
         }
 
         /* Terminate processing of current command */
         shell_stop ( SHELL_STOP_COMMAND );
 
         return 0;
 }

References current_image, DBGC, ENOTTY, goto_cmd, goto_find_label(), goto_label, image_tag::image, optind, opts, parse_options(), printf(), process_script(), rc, script_offset, shell_stop(), SHELL_STOP_COMMAND, strerror(), and terminate_on_label_found().

◆ COMMAND() [1/2]

COMMAND	(	goto	,
		goto_exec
	)

"goto" command

◆ prompt_exec()

static int prompt_exec	(	int	argc,
		char **	argv
	)

static

"prompt" command

Parameters

argc	Argument count
argv	Argument list

Return values

rc	Return status code

Definition at line 386 of file script.c.

                                                  {
         struct prompt_options opts;
         char *text;
         int rc;
 
         /* Parse options */
         if ( ( rc = parse_options ( argc, argv, &prompt_cmd, &opts ) ) != 0 )
                 goto err_parse;
 
         /* Parse prompt text */
         text = concat_args ( &argv[optind] );
         if ( ! text ) {
                 rc = -ENOMEM;
                 goto err_concat;
         }
 
         /* Display prompt and wait for key */
         if ( ( rc = prompt ( text, opts.timeout, opts.key ) ) != 0 )
                 goto err_prompt;
 
         /* Free prompt text */
         free ( text );
 
         return 0;
 
  err_prompt:
         free ( text );
  err_concat:
  err_parse:
         return rc;
 }

References concat_args(), ENOMEM, free, optind, opts, parse_options(), prompt(), prompt_cmd, and rc.

◆ COMMAND() [2/2]

COMMAND	(	prompt	,
		prompt_exec
	)

"prompt" command

Variable Documentation

◆ script_offset

size_t script_offset

static

Offset within current script.

This is a global in order to allow goto_exec() to update the offset.

Definition at line 52 of file script.c.

Referenced by goto_exec(), goto_find_label(), process_script(), and script_exec().

◆ goto_opts

struct option_descriptor goto_opts[] = {}

static

"goto" option list

Definition at line 262 of file script.c.

◆ goto_cmd

struct command_descriptor goto_cmd

static

Initial value:

=

COMMAND_DESC ( struct goto_options, goto_opts, 1, 1, "<label>" )

goto_options

"goto" options

Definition: script.c:259

goto_opts

static struct option_descriptor goto_opts[]

"goto" option list

Definition: script.c:262

COMMAND_DESC

#define COMMAND_DESC(_struct, _options, _min_args, _max_args, _usage)

Construct command descriptor.

Definition: parseopt.h:109

"goto" command descriptor

Definition at line 265 of file script.c.

Referenced by goto_exec().

◆ goto_label

const char* goto_label

static

Current "goto" label.

Valid only during goto_exec(). Consider this part of a closure.

Definition at line 273 of file script.c.

Referenced by goto_exec(), and goto_find_label().

◆ prompt_opts

struct option_descriptor prompt_opts[]

static

Initial value:

= {
        OPTION_DESC ( "key", 'k', required_argument,
                      struct prompt_options, key, parse_key ),
        OPTION_DESC ( "timeout", 't', required_argument,
                      struct prompt_options, timeout, parse_timeout ),
}

"prompt" option list

Definition at line 367 of file script.c.

◆ prompt_cmd

struct command_descriptor prompt_cmd

static

Initial value:

=
        COMMAND_DESC ( struct prompt_options, prompt_opts, 0, MAX_ARGUMENTS,
                       "[<text>]" )

"prompt" command descriptor

Definition at line 375 of file script.c.

Referenced by prompt_exec().

Data Structures

Functions

Variables

Detailed Description

Function Documentation

◆ FILE_LICENCE()

◆ FILE_SECBOOT()

◆ process_script()

◆ terminate_on_exit_or_failure()

◆ script_exec_line()

◆ script_exec()

◆ script_probe()

◆ __image_type()

◆ goto_find_label()

◆ terminate_on_label_found()

◆ goto_exec()

◆ COMMAND() [1/2]

◆ prompt_exec()

◆ COMMAND() [2/2]

Variable Documentation

◆ script_offset

◆ goto_opts

◆ goto_cmd

◆ goto_label

◆ prompt_opts

◆ prompt_cmd