- Generated on Tue Jul 21 2026 02:18:12 for BRL-CAD by
1.9.8
|
BRL-CAD
|
Files | |
| file | pkg.h |
Data Structures | |
| struct | pkg_switch |
| struct | pkg_header |
| struct | pkg_conn |
Macros | |
| #define | PKG_MAGIC 0x41FE |
| #define | PKG_STREAMLEN (32*1024) |
| #define | PKC_NULL ((struct pkg_conn *)0) |
| #define | PKC_ERROR ((struct pkg_conn *)(-1L)) |
| #define | pkg_send_vls(type, vlsp, pkg) pkg_send( (type), bu_vls_addr((vlsp)), bu_vls_strlen((vlsp))+1, (pkg) ) |
| #define | PKG_ADDR_ENVVAR "PKG_ADDR" |
| #define | PKG_TRANSPORT_PREFER_ENVVAR "PKG_TRANSPORT_PREFER" |
Typedefs | |
| typedef void(* | pkg_callback) (struct pkg_conn *, char *) |
| typedef void(* | pkg_errlog) (const char *msg) |
| typedef struct pkg_listener | pkg_listener_t |
| typedef struct pkg_mux | pkg_mux_t |
Enumerations | |
| enum | pkg_transport_t { PKG_TRANSPORT_AUTO = 0 , PKG_TRANSPORT_PIPE = 1 , PKG_TRANSPORT_SOCKET = 2 , PKG_TRANSPORT_TCP = 3 } |
| #define PKG_MAGIC 0x41FE |
| #define pkg_send_vls | ( | type, | |
| vlsp, | |||
| pkg | |||
| ) | pkg_send( (type), bu_vls_addr((vlsp)), bu_vls_strlen((vlsp))+1, (pkg) ) |
| #define PKG_ADDR_ENVVAR "PKG_ADDR" |
| #define PKG_TRANSPORT_PREFER_ENVVAR "PKG_TRANSPORT_PREFER" |
Optional transport preference hint for pkg_pair().
| typedef struct pkg_listener pkg_listener_t |
|
extern |
Open a network connection to a host/server.
Returns PKC_ERROR on error.
Close a network connection.
Gracefully release the connection block and close the connection.
|
extern |
|
extern |
Suck all data from the operating system into the internal buffer.
This is done with large buffers, to maximize the efficiency of the data transfer from kernel to user.
It is expected that the read() system call will return as much data as the kernel has, UP TO the size indicated. The only time the read() may be expected to block is when the kernel does not have any data at all. Thus, it is wise to call call this routine only if:
a) select() has indicated the presence of data, or b) blocking is acceptable.
This routine is the only place where data is taken off the network. All input is appended to the internal buffer for later processing.
Subscripting was used for pkc_incur/pkc_inend to avoid having to recompute pointers after a realloc().
Returns - -1 on error 0 on EOF 1 success
Send a message on the connection.
Send the user's data, prefaced with an identifying header which contains a message type value. All header fields are exchanged in "network order".
Note that the whole message (header + data) should be transmitted by TCP with only one TCP_PUSH at the end, due to the use of writev().
Returns number of bytes of user data actually sent.
|
extern |
Send a two part message on the connection.
Exactly like pkg_send, except user's data is located in two disjoint buffers, rather than one. Fiendishly useful!
Send a message that doesn't need a push.
Exactly like pkg_send except no "push" is necessary here. If the packet is sufficiently small (MAXQLEN) it will be placed in the pkc_stream buffer (after flushing this buffer if there insufficient room). If it is larger than this limit, it is sent via pkg_send (who will do a pkg_flush if there is already data in the stream queue).
Returns number of bytes of user data actually sent (or queued).
|
extern |
Empty the stream buffer of any queued messages.
Flush any pending data in the pkc_stream buffer.
Returns < 0 on failure, else number of bytes sent.
Wait for a specific msg, user buf, processing others.
This routine implements a blocking read on the network connection until a message of 'type' type is received. This can be useful for implementing the synchronous portions of a query/reply exchange. All messages of any other type are processed by pkg_block().
Returns the length of the message actually received, or -1 on error.
Wait for specific msg, malloc buf, processing others.
This routine implements a blocking read on the network connection until a message of 'type' type is received. This can be useful for implementing the synchronous portions of a query/reply exchange. All messages of any other type are processed by pkg_block().
The buffer to contain the actual message is acquired via malloc(), and the caller must free it.
Returns pointer to message buffer, or NULL.
|
extern |
Wait until a full message has been read.
This routine blocks, waiting for one complete message to arrive from the network. The actual handling of the message is done with _pkg_dispatch(), which invokes the user-supplied message handler.
This routine can be used in a loop to pass the time while waiting for a flag to be changed by the arrival of an asynchronous message, or for the arrival of a message of uncertain type.
The companion routine is pkg_process(), which does not block.
Control returns to the caller after one full message is processed. Returns -1 on error, etc.
Return the file descriptor a caller should pass to select(), poll(), QSocketNotifier, libuv, etc. for read-readiness notification.
Hides the distinction between bidirectional sockets (where read and write share a single fd) and pipe-pair connections (where the read end is a separate fd kept internally as pkc_in_fd). Callers should use this in preference to looking at pkc_fd / pkc_in_fd directly.
Returns -1 on error.
Return the file descriptor used for write-readiness notification. Equal to pkg_get_read_fd() for bidirectional transports (TCP / socketpair); for pipe-pair connections this is the write fd.
Returns -1 on error.
Return non-zero if the connection uses split read/write fds (i.e. the unidirectional pipe transport; pkc_in_fd != pkc_out_fd). Use this in preference to inspecting pkc_fd / pkc_in_fd / pkc_out_fd directly so future transport changes remain source-compatible.
Set the kernel send-buffer size on the underlying socket (equivalent to setsockopt(SOL_SOCKET, SO_SNDBUF)).
Silently succeeds (returns 0) for transports where send-buffer tuning is not applicable (pipe / split-fd connections).
Returns 0 on success, -1 on error.
Set the kernel receive-buffer size on the underlying socket (equivalent to setsockopt(SOL_SOCKET, SO_RCVBUF)).
Silently succeeds (returns 0) for transports where receive-buffer tuning is not applicable. Returns 0 on success, -1 on error.
|
extern |
Set TCP_NODELAY on the underlying socket. No-op on non-TCP transports. Returns 0 on success, -1 on error.
|
extern |
Install a TLS / framing-cipher I/O shim on the connection.
When tls_read / tls_write are non-NULL they completely replace the raw read()/write() calls inside pkg_suckin(), pkg_send(), pkg_2send(), and pkg_flush(). tls_ctx is the opaque context pointer forwarded as the first argument to both callbacks.
tls_free (if non-NULL) is invoked by pkg_close() before closing the underlying transport, giving the TLS layer a chance to send a clean close_notify and free its own state.
Returns 0 on success, -1 on error.
|
extern |
Wrap an already-connected socket fd in a pkg_conn without performing any network connect/accept.
Replaces the historical pattern of allocating a pkg_conn and hand-initialising pkc_magic / pkc_fd / pkc_switch / pkc_left etc. Used by callers that obtain a connected socket from another framework (Tcl/Qt) and want to drive it through libpkg's framing protocol.
On Windows this also performs WinSock initialisation if necessary.
Returns a pkg_conn handle on success, PKC_ERROR on failure.
|
extern |
Create a connected pair of pkg_conn handles.
Probe order: pipe -> socketpair -> TCP loopback (or use preferred). Returns 0 on success, -1 on failure.
|
extern |
Return a "KEY=VALUE" env string for passing to a spawned child. The pointer is valid until pkg_close(). Format: "PKG_ADDR=<addr>". For pair transports, the address may be a child-side or parent-side local IPC string, depending on which end is being exported.
Return just the raw address string (e.g. "pipe:4,7" or "socket:5") for use in argv["-I addr"] style arguments to a child process. Pair transports may also return parent-side variants such as "pipe_parent:4,7" and "socket_parent:5". The pointer is valid until pkg_close().
|
extern |
Connect an IPC endpoint from an address string. Supports child-side and parent-side pair addresses, reusable local IPC listener addresses returned by pkg_ipc_addr(), plus TCP loopback. Callers should treat local IPC listener addresses as opaque strings. Returns pkg_conn* on success, PKC_ERROR on failure.
Create an opaque local IPC listener address suitable for this process.
The resulting address string is for local same-host communication and is intended to be passed unchanged to a server's pkg_listen() and client-side pkg_connect_addr() calls. It does not bind the listener itself. The concrete transport is selected by libpkg for the current platform. Current implementations include POSIX FIFO/UNIX-domain transports and Windows named pipes; callers must not parse the returned address. Platforms may support inherited endpoint IPC via pkg_pair() even when they do not provide a reusable listener transport here.
Returns 0 on success, -1 if no local listener transport is available.
Return non-zero when addr names a reusable listener-style IPC endpoint, as opposed to a single inherited connected endpoint.
|
extern |
Connect using the PKG_ADDR env var (child side).
|
extern |
Wrap an already-open fd pair into a pkg_conn.
|
extern |
Wrap stdin(0)/stdout(1) as a pkg connection (inetd/pipe mode).
|
extern |
Move the connection's fds above min_fd. Returns 0 on success, -1 on error.
|
extern |
|
extern |
|
extern |
|
extern |
|
extern |
|
extern |
|
extern |
|
extern |
|
extern |
1.9.8