Skip to content

NAME

ltp_admin - LTP Administration API

SYNOPSIS

#include "ltp_admin.h"

/* System lifecycle */
int ltp_init(unsigned int est_max_sessions);
int ltp_start(void);
void ltp_stop(void);

/* Span management */
int add_span(uvast engine_id,
             unsigned int max_export_sessions,
             unsigned int max_import_sessions,
             unsigned int max_segment_size,
             unsigned int aggr_size_limit,
             unsigned int aggr_time_limit,
             char *lso_command,
             unsigned int queuing_latency,
             int purge_enabled);

int update_span(uvast engine_id,
                unsigned int max_export_sessions,
                unsigned int max_import_sessions,
                unsigned int max_segment_size,
                unsigned int aggr_size_limit,
                unsigned int aggr_time_limit,
                char *lso_command,
                unsigned int queuing_latency,
                int purge_enabled);

int remove_span(uvast engine_id);
int ltp_start_span(uvast engine_id);
void ltp_stop_span(uvast engine_id);

/* Seat management */
int add_seat(char *lsi_command);
int remove_seat(char *lsi_command);

/* Monitoring */
void ltp_list_spans(void);
void ltp_list_seats(void);

/* Bulk removal */
int ltp_remove_all_spans(void);
int ltp_remove_all_seats(void);

DESCRIPTION

The ltp_admin library provides programmatic access to LTP (Licklider Transmission Protocol) configuration and management functions that are traditionally accessible only through the ltpadmin(1) command-line interface. This enables applications to dynamically configure and manage LTP operations at runtime.

LTP manages communication with remote LTP engines through "spans" (for transmission) and "seats" (for reception). Unlike BP scheme operations, LTP span and seat operations are SAFE to perform while LTP is running, as they use SDR transactions for synchronization and automatically manage LSO/LSI process lifecycles.

Key Concepts

  • Span

    Configuration for transmitting data to a remote LTP engine. Each span manages sessions, segmentation, and retransmission for outbound traffic.

  • Seat

    Configuration for receiving data from remote LTP engines. Defines the Link Service Input (LSI) endpoint.

  • LSO

    Link Service Output - the transmission daemon, one per span.

  • LSI

    Link Service Input - the reception daemon, one per seat.

  • Engine ID

    Identifier for an LTP engine, typically corresponding to an IPN node number.

FUNCTIONS

System Lifecycle Functions

  • int ltp_init(unsigned int est_max_sessions)

    Initialize the LTP engine. Creates or recovers the LTP database in SDR. Must be called after ionAttach().

    est_max_sessions - Estimated maximum number of concurrent sessions.

    Returns 0 on success, -1 on error.

  • int ltp_start(void)

    Start the LTP engine and all its daemons. Launches ltpclock, ltpdeliv, and all configured LSO/LSI processes.

    Returns 0 on success, -1 on error.

  • void ltp_stop(void)

    Stop the LTP engine and all its daemons. Terminates ltpclock, ltpdeliv, and all LSO/LSI processes.

Span Management Functions

  • int add_span(uvast engine_id, ...)

    Add a span to a remote LTP engine. A span defines how to transmit data to a specific remote LTP engine.

    Parameters:

    • engine_id

      Remote LTP engine identifier (typically IPN node number).

    • max_export_sessions

      Maximum concurrent outbound sessions to this engine.

    • max_import_sessions

      Maximum concurrent inbound sessions from this engine.

    • max_segment_size

      Maximum LTP segment size in bytes.

    • aggr_size_limit

      Block aggregation size threshold in bytes.

    • aggr_time_limit

      Block aggregation time limit in seconds.

    • lso_command

      Link Service Output command (e.g., "udplso localhost:1113").

    • queuing_latency

      Expected transmission queuing delay in seconds.

    • purge_enabled

      Enable automatic session purging (0=no, 1=yes).

    Returns 1 on success, 0 if duplicate span exists, -1 on error.

    Example:

    add_span(2, 100, 100, 1400, 10000, 1, "udplso localhost:1113", 1, 0);

  • int update_span(uvast engine_id, ...)

    Update an existing span's parameters. Parameters are the same as add_span().

    Returns 1 on success, 0 if span not found, -1 on error.

  • int remove_span(uvast engine_id)

    Remove a span to a remote LTP engine. Automatically stops the LSO process before removal. The span must have no pending segments or open sessions.

    Returns 1 on success, 0 if span not found or has pending data, -1 on error.

  • int ltp_start_span(uvast engine_id)

    Start transmission on a span. Starts the LSO process for the specified span.

    Returns 1 on success, 0 if span not found, -1 on error.

  • void ltp_stop_span(uvast engine_id)

    Stop transmission on a span. Stops the LSO process for the specified span.

Seat Management Functions

  • int add_seat(char *lsi_command)

    Add a seat (link service input). A seat defines how to receive data from remote LTP engines.

    lsi_command - Link Service Input command (e.g., "udplsi localhost:1113").

    Returns 1 on success, 0 if duplicate seat exists, -1 on error.

    Example:

    add_seat("udplsi localhost:1113");

  • int remove_seat(char *lsi_command)

    Remove a seat (link service input). Automatically stops the LSI process before removal.

    Returns 1 on success, 0 if seat not found, -1 on error.

Monitoring Functions

  • void ltp_list_spans(void)

    List all configured spans. Displays span engine IDs, session limits, segment sizes, aggregation parameters, LSO commands, and process IDs.

    Output is written to stdout.

  • void ltp_list_seats(void)

    List all configured seats. Displays LSI commands and process IDs.

    Output is written to stdout.

Bulk Removal Functions

These functions remove all items of a specific type. Useful for runtime reconfiguration or selective cleanup without full shutdown.

  • int ltp_remove_all_spans(void)

    Remove all LTP spans. Stops LSO processes and removes all configured spans. Useful for runtime reconfiguration or cleanup.

    Spans with pending data (segments, sessions) will be skipped. For complete shutdown, use ltp_stop() + ionTerminate(1) instead.

    Returns the number of spans successfully removed (>= 0), or -1 on fatal error.

    Example:

    /* Stop BP first for safe removal */
bp_stop();

/* Remove all spans */
int removed = ltp_remove_all_spans();
printf("Removed %d spans\n", removed);

  • int ltp_remove_all_seats(void)

    Remove all LTP seats. Stops LSI processes and removes all configured seats. Useful for runtime reconfiguration or cleanup.

    For complete shutdown, use ltp_stop() + ionTerminate(1) instead.

    Returns the number of seats successfully removed (>= 0), or -1 on fatal error.

    Example:

    /* Remove all seats */
int removed = ltp_remove_all_seats();
printf("Removed %d seats\n", removed);

RUNTIME SAFETY

Unlike BP scheme operations, LTP span and seat operations are safe to perform while LTP is running because:

  • All operations use SDR transactions for synchronization.
  • LSO/LSI process lifecycles are managed automatically.
  • No race conditions exist between configuration changes and active traffic.

Applications can safely add, update, or remove spans and seats at runtime without stopping the LTP engine.

RETURN VALUES

Most functions follow these conventions:

  • Return 1 on successful operation.
  • Return 0 when the operation cannot be completed (e.g., span not found, duplicate exists).
  • Return -1 on error (check error messages via putErrmsg).

Lifecycle functions (ltp_init, ltp_start) return 0 on success, -1 on error.

Void functions (ltp_stop, ltp_stop_span, ltp_list_*) do not return values.

EXAMPLES

Initialize and Start LTP

#include "ion.h"
#include "ltp_admin.h"

if (ionAttach() < 0)
{
    fprintf(stderr, "Can't attach to ION\n");
    return -1;
}

if (ltp_init(1000) < 0)
{
    fprintf(stderr, "Can't initialize LTP\n");
    return -1;
}

if (ltp_start() < 0)
{
    fprintf(stderr, "Can't start LTP\n");
    return -1;
}

Configure a Span

/* Add a span to engine 2 */
if (add_span(2,           /* engine_id */
             100,         /* max_export_sessions */
             100,         /* max_import_sessions */
             1400,        /* max_segment_size */
             10000,       /* aggr_size_limit */
             1,           /* aggr_time_limit */
             "udplso localhost:1113",
             1,           /* queuing_latency */
             0            /* purge_enabled */
             ) < 0)
{
    fprintf(stderr, "Can't add span\n");
    return -1;
}

/* Start transmission on the span */
if (ltp_start_span(2) < 0)
{
    fprintf(stderr, "Can't start span\n");
    return -1;
}

Configure a Seat

/* Add a seat for receiving data */
if (add_seat("udplsi localhost:1113") < 0)
{
    fprintf(stderr, "Can't add seat\n");
    return -1;
}

Monitor Configuration

/* List all configured spans */
ltp_list_spans();

/* List all configured seats */
ltp_list_seats();

Cleanup

/* Stop a span */
ltp_stop_span(2);

/* Remove the span */
remove_span(2);

/* Remove the seat */
remove_seat("udplsi localhost:1113");

/* Stop LTP engine */
ltp_stop();

SEE ALSO

ltpadmin(1), ion(3), ltp(3)

NOTES

This API provides the same functionality as the ltpadmin command-line interface, but allows for programmatic control of LTP configuration.

For detailed runtime safety analysis, see LTP_RUNTIME_SAFETY_ANALYSIS.md in the ION documentation.

AUTHORS

Jet Propulsion Laboratory, California Institute of Technology