---
name: "liblolowlevel"
section: "3"
platform: "linux"
package: "liblo"
version: "1:0.36-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/liblolowlevel"
---

# liblolowlevel(3)

Low-level OSC API

## NAME

liblolowlevel - Low-level OSC API

## SYNOPSIS

### Data Structures

struct **lo\_server\_config**\
 A configuration struct for initializing **lo\_server** using **lo\_server\_new\_from\_config()**.

### Typedefs

typedef long double **lo\_hires**\
 Type used to represent numerical values in conversions between OSC types.

### Enumerations

enum **lo\_slip\_encoding** \
 Used with **lo\_address\_set\_stream\_slip()** to specify whether sent messages should be encoded with SLIP, and whether the encoding should be single- or double-ENDed.

### Functions

int **lo\_send\_message** (**lo\_address** targ, const char \*path, **lo\_message** msg)\
 Send a **lo\_message** object to target targ.  int **lo\_send\_message\_from** (**lo\_address** targ, **lo\_server** serv, const char \*path, **lo\_message** msg)\
 Send a **lo\_message** object to target targ from address of serv.  int **lo\_send\_bundle** (**lo\_address** targ, **lo\_bundle** b)\
 Send a **lo\_bundle** object to address targ.  int **lo\_send\_bundle\_from** (**lo\_address** targ, **lo\_server** serv, **lo\_bundle** b)\
 Send a **lo\_bundle** object to address targ from address of serv.  **lo\_message** **lo\_message\_new** (void)\
 Create a new **lo\_message** object.  void **lo\_message\_incref** (**lo\_message** m)\
 Add one to a message's reference count.  int **lo\_message\_decref** (**lo\_message** m)\
 Subtract one from a message's reference count.  **lo\_message** **lo\_message\_clone** (**lo\_message** m)\
 Create a new **lo\_message** object by cloning an already existing one.  void **lo\_message\_free** (**lo\_message** m)\
 Free memory allocated by **lo\_message\_new()** and any subsequent **lo\_message\_add\_int32** lo\_message\_add\*() calls.  void **lo\_message\_clear** (**lo\_message** m)\
 Clear elements from a **lo\_message** but do not free allocated memory.  int **lo\_message\_add** (**lo\_message** m, const char \*types,...)\
 Append a number of arguments to a message.  int **lo\_message\_add\_varargs** (**lo\_message** m, const char \*types, va\_list ap)\
 Append a varargs list to a message.  int **lo\_message\_add\_int32** (**lo\_message** m, int32\_t a)\
 Append a data item and typechar of the specified type to a message.  int **lo\_message\_add\_float** (**lo\_message** m, float a)\
 Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.  int **lo\_message\_add\_string** (**lo\_message** m, const char \*a)\
 Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.  int **lo\_message\_add\_blob** (**lo\_message** m, **lo\_blob** a)\
 Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.  int **lo\_message\_add\_int64** (**lo\_message** m, int64\_t a)\
 Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.  int **lo\_message\_add\_timetag** (**lo\_message** m, **lo\_timetag** a)\
 Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.  int **lo\_message\_add\_double** (**lo\_message** m, double a)\
 Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.  int **lo\_message\_add\_symbol** (**lo\_message** m, const char \*a)\
 Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.  int **lo\_message\_add\_char** (**lo\_message** m, char a)\
 Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.  int **lo\_message\_add\_midi** (**lo\_message** m, uint8\_t a\[4\])\
 Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.  int **lo\_message\_add\_true** (**lo\_message** m)\
 Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.  int **lo\_message\_add\_false** (**lo\_message** m)\
 Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.  int **lo\_message\_add\_nil** (**lo\_message** m)\
 Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.  int **lo\_message\_add\_infinitum** (**lo\_message** m)\
 Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.  **lo\_address** **lo\_message\_get\_source** (**lo\_message** m)\
 Returns the source (**lo\_address**) of an incoming message.  **lo\_timetag** **lo\_message\_get\_timestamp** (**lo\_message** m)\
 Returns the timestamp (**lo\_timetag** \*) of a bundled incoming message.  char \* **lo\_message\_get\_types** (**lo\_message** m)\
 Return the message type tag string.  int **lo\_message\_get\_argc** (**lo\_message** m)\
 Return the message argument count.  **lo\_arg** \*\* **lo\_message\_get\_argv** (**lo\_message** m)\
 Return the message arguments. Do not free the returned data.  size\_t **lo\_message\_length** (**lo\_message** m, const char \*path)\
 Return the length of a message in bytes.  void \* **lo\_message\_serialise** (**lo\_message** m, const char \*path, void \*to, size\_t \*size)\
 Serialise the **lo\_message** object to an area of memory and return a pointer to the serialised form. Opposite of **lo\_message\_deserialise()**.  **lo\_message** **lo\_message\_deserialise** (void \*data, size\_t size, int \*result)\
 Deserialise a raw OSC message and return a new **lo\_message** object. Opposite of **lo\_message\_serialise()**.  int **lo\_server\_dispatch\_data** (**lo\_server** s, void \*data, size\_t size)\
 Dispatch a raw block of memory containing an OSC message.  const char \* **lo\_address\_get\_hostname** (**lo\_address** a)\
 Return the hostname of a **lo\_address** object.  const char \* **lo\_address\_get\_port** (**lo\_address** a)\
 Return the port/service name of a **lo\_address** object.  int **lo\_address\_get\_protocol** (**lo\_address** a)\
 Return the protocol of a **lo\_address** object.  char \* **lo\_address\_get\_url** (**lo\_address** a)\
 Return a URL representing an OSC address.  void **lo\_address\_set\_ttl** (**lo\_address** t, int ttl)\
 Set the Time-to-Live value for a given target address.  int **lo\_address\_get\_ttl** (**lo\_address** t)\
 Get the Time-to-Live value for a given target address.  int **lo\_address\_set\_iface** (**lo\_address** t, const char \*iface, const char \*ip)\
 Set the network interface to use for a given target address.  const char \* **lo\_address\_get\_iface** (**lo\_address** t)\
 Get the name of the network interface assigned to an OSC address.  int **lo\_address\_set\_tcp\_nodelay** (**lo\_address** t, int enable)\
 Set the TCP\_NODELAY flag on outgoing TCP connections.  int **lo\_address\_set\_stream\_slip** (**lo\_address** t, **lo\_slip\_encoding** encoding)\
 Set outgoing stream connections (e.g., TCP) to be transmitted using the SLIP packetizing protocol.  **lo\_bundle** **lo\_bundle\_new** (**lo\_timetag** tt)\
 Create a new bundle object.  void **lo\_bundle\_incref** (**lo\_bundle** b)\
 Add one to a bundle's reference count.  int **lo\_bundle\_add\_message** (**lo\_bundle** b, const char \*path, **lo\_message** m)\
 Adds an OSC message to an existing bundle.  int **lo\_bundle\_add\_bundle** (**lo\_bundle** b, **lo\_bundle** n)\
 Adds an OSC bundle to an existing bundle.  size\_t **lo\_bundle\_length** (**lo\_bundle** b)\
 Return the length of a bundle in bytes.  unsigned int **lo\_bundle\_count** (**lo\_bundle** b)\
 Return the number of top-level elements in a bundle.  **lo\_element\_type** **lo\_bundle\_get\_type** (**lo\_bundle** b, int index)\
 Gets the element type contained within a bundle.  **lo\_bundle** **lo\_bundle\_get\_bundle** (**lo\_bundle** b, int index)\
 Gets a nested bundle contained within a bundle.  **lo\_message** **lo\_bundle\_get\_message** (**lo\_bundle** b, int index, const char \*\*path)\
 Gets a message contained within a bundle.  **lo\_timetag** **lo\_bundle\_get\_timestamp** (**lo\_bundle** b)\
 Get the timestamp associated with a bundle.  void **lo\_bundle\_set\_timestamp** (**lo\_bundle** b, **lo\_timetag** t)\
 Get the timestamp associated with a bundle.  void \* **lo\_bundle\_serialise** (**lo\_bundle** b, void \*to, size\_t \*size)\
 Serialise the bundle object to an area of memory and return a pointer to the serialised form.  void **lo\_bundle\_clear** (**lo\_bundle** b)\
 Clear elements from a **lo\_bundle** but do not free allocated memory.  void **lo\_bundle\_free** (**lo\_bundle** b)\
 Frees the memory taken by a bundle object.  void **lo\_bundle\_free\_recursive** (**lo\_bundle** b)\
 Frees the memory taken by a bundle object and its messages and nested bundles recursively.  void **lo\_bundle\_free\_messages** (**lo\_bundle** b)\
 Obsolete, use lo\_bundle\_free\_recursive instead.  int **lo\_is\_numerical\_type** (**lo\_type** a)\
 Return true if the type specified has a numerical value, such as LO\_INT32, LO\_FLOAT etc.  int **lo\_is\_string\_type** (**lo\_type** a)\
 Return true if the type specified has a textual value, such as LO\_STRING or LO\_SYMBOL.  int **lo\_coerce** (**lo\_type** type\_to, **lo\_arg** \*to, **lo\_type** type\_from, **lo\_arg** \*from)\
 Attempt to convert one OSC type to another.  **lo\_hires** **lo\_hires\_val** (**lo\_type** type, **lo\_arg** \*p)\
 Return the numerical value of the given argument with the maximum native system precision.  **lo\_server** **lo\_server\_new** (const char \*port, **lo\_err\_handler** err\_h)\
 Create a new server instance.  **lo\_server** **lo\_server\_new\_with\_proto** (const char \*port, int proto, **lo\_err\_handler** err\_h)\
 Create a new server instance, specifying protocol.  **lo\_server** **lo\_server\_new\_multicast** (const char \*group, const char \*port, **lo\_err\_handler** err\_h)\
 Create a new server instance, and join a UDP multicast group.  **lo\_server** **lo\_server\_new\_multicast\_iface** (const char \*group, const char \*port, const char \*iface, const char \*ip, **lo\_err\_handler** err\_h)\
 Create a new server instance, and join a UDP multicast group, optionally specifying which network interface to use. Note that usually only one of iface or ip are specified.  **lo\_server** **lo\_server\_new\_from\_url** (const char \*url, **lo\_err\_handler** err\_h)\
 Create a new server instance, taking port and the optional multicast group IP from an URL string.  **lo\_server** **lo\_server\_new\_from\_config** (**lo\_server\_config** \*config)\
 Create a new server instance, using a configuration struct.  int **lo\_server\_enable\_coercion** (**lo\_server** server, int enable)\
 Enables or disables type coercion during message dispatch.  void **lo\_server\_free** (**lo\_server** s)\
 Free up memory used by the **lo\_server** object.  int **lo\_server\_wait** (**lo\_server** s, int timeout)\
 Wait for an OSC message to be received.  int **lo\_servers\_wait** (**lo\_server** \*s, int \*status, int num\_servers, int timeout)\
 Wait on multiple servers for an OSC message to be received.  int **lo\_server\_recv\_noblock** (**lo\_server** s, int timeout)\
 Look for an OSC message waiting to be received.  int **lo\_servers\_recv\_noblock** (**lo\_server** \*s, int \*recvd, int num\_servers, int timeout)\
 Look for an OSC message waiting to be received on multiple servers.  int **lo\_server\_recv** (**lo\_server** s)\
 Block, waiting for an OSC message to be received.  **lo\_method** **lo\_server\_add\_method** (**lo\_server** s, const char \*path, const char \*typespec, **lo\_method\_handler** h, const void \*user\_data)\
 Add an OSC method to the specifed server.  void **lo\_server\_del\_method** (**lo\_server** s, const char \*path, const char \*typespec)\
 Delete an OSC method from the specified server.  int **lo\_server\_del\_lo\_method** (**lo\_server** s, **lo\_method** m)\
 Delete a specific OSC method from the specified server.  int **lo\_server\_add\_bundle\_handlers** (**lo\_server** s, **lo\_bundle\_start\_handler** sh, **lo\_bundle\_end\_handler** eh, void \*user\_data)\
 Add bundle notification handlers to the specified server.  int **lo\_server\_get\_socket\_fd** (**lo\_server** s)\
 Return the file descriptor of the server socket.  int **lo\_server\_get\_port** (**lo\_server** s)\
 Return the port number that the server has bound to.  int **lo\_server\_get\_protocol** (**lo\_server** s)\
 Return the protocol that the server is using.  char \* **lo\_server\_get\_url** (**lo\_server** s)\
 Return an OSC URL that can be used to contact the server.  int **lo\_server\_enable\_queue** (**lo\_server** s, int queue\_enabled, int dispatch\_remaining)\
 Toggle event queue. If queueing is enabled, timetagged messages that are sent in advance of the current time will be put on an internal queue, and they will be dispatched at the indicated time. By default, queueing is enabled. Use this function to disable it, if it is desired to have a server process messages immediately. In that case, use **lo\_message\_get\_timestamp()** to get the message timestamp from within a method handler.  int **lo\_server\_events\_pending** (**lo\_server** s)\
 Return true if there are scheduled events (eg. from bundles) waiting to be dispatched by the server.  double **lo\_server\_next\_event\_delay** (**lo\_server** s)\
 Return the time in seconds until the next scheduled event.  int **lo\_server\_max\_msg\_size** (**lo\_server** s, int req\_size)\
 Set the maximum message size accepted by a server.  char \* **lo\_url\_get\_protocol** (const char \*url)\
 Return the protocol portion of an OSC URL, eg. udp, tcp.  int **lo\_url\_get\_protocol\_id** (const char \*url)\
 Return the protocol ID of an OSC URL.  char \* **lo\_url\_get\_hostname** (const char \*url)\
 Return the hostname portion of an OSC URL.  char \* **lo\_url\_get\_port** (const char \*url)\
 Return the port portion of an OSC URL.  char \* **lo\_url\_get\_path** (const char \*url)\
 Return the path portion of an OSC URL.  int **lo\_strsize** (const char \*s)\
 A function to calculate the amount of OSC message space required by a C char \*.  uint32\_t **lo\_blobsize** (**lo\_blob** b)\
 A function to calculate the amount of OSC message space required by a **lo\_blob** object.  int **lo\_pattern\_match** (const char \*str, const char \*p)\
 Test a string against an OSC pattern glob.  int **lo\_string\_contains\_pattern** (const char \*str)\
 Test if a string contains any OSC pattern characters.  double **lo\_timetag\_diff** (**lo\_timetag** a, **lo\_timetag** b)\
 Find the time difference between two timetags.  void **lo\_timetag\_now** (**lo\_timetag** \*t)\
 Return a timetag for the current time.  size\_t **lo\_arg\_size** (**lo\_type** type, void \*data)\
 Return the storage size, in bytes, of the given argument.  char \* **lo\_get\_path** (void \*data, ssize\_t size)\
 Given a raw OSC message, return the message path.  void **lo\_arg\_host\_endian** (**lo\_type** type, void \*data)\
 Convert the specified argument to host byte order where necessary.  void **lo\_arg\_network\_endian** (**lo\_type** type, void \*data)\
 Convert the specified argument to network byte order where necessary.

## Detailed Description

Use these functions if you require more precise control over OSC message contruction or handling that what is provided in the high-level functions described in liblo.

## Typedef Documentation

### typedef long double lo\_hires

Type used to represent numerical values in conversions between OSC types.

Definition at line **56** of file **lo\_lowlevel.h**.

## Enumeration Type Documentation

### enum lo\_slip\_encoding

Used with **lo\_address\_set\_stream\_slip()** to specify whether sent messages should be encoded with SLIP, and whether the encoding should be single- or double-ENDed.

Definition at line **85** of file **lo\_lowlevel.h**.

## Function Documentation

### const char \* lo\_address\_get\_hostname (lo\_address a)

Return the hostname of a **lo\_address** object. Returned value must not be modified or free'd. Value will be a dotted quad, colon'd IPV6 address, or resolvable name.

### const char \* lo\_address\_get\_iface (lo\_address t)

Get the name of the network interface assigned to an OSC address.

**Parameters**

*t* An OSC address.

**Returns**

A string pointer or 0 if no interface has been assigned. Caller should not modify the provided string. It is a legal pointer until the next call to lo\_address\_set\_iface or lo\_address\_free.

### const char \* lo\_address\_get\_port (lo\_address a)

Return the port/service name of a **lo\_address** object. Returned value must not be modified or free'd. Value will be a service name or ASCII representation of the port number.

### int lo\_address\_get\_protocol (lo\_address a)

Return the protocol of a **lo\_address** object. Returned value will be one of LO\_UDP, LO\_TCP or LO\_UNIX.

### int lo\_address\_get\_ttl (lo\_address t)

Get the Time-to-Live value for a given target address.

**Parameters**

*t* An OSC address.

**Returns**

An integer specifying the scope of a multicast UDP message.

### char \* lo\_address\_get\_url (lo\_address a)

Return a URL representing an OSC address. Returned value must be free'd.

### int lo\_address\_set\_iface (lo\_address t, const char \* iface, const char \* ip)

Set the network interface to use for a given target address. The caller should specify either the iface or ip variable. The IP, if specified, should match the same network family as the OSC address. (That is, should correctly correspond to IPv4 or IPv6.) Typically the assigned network interface will only be used in the case of sending multicast messages. It is recommended to use the if\_nameindex POSIX function to get a list of network interface names.

**Parameters**

*t* An OSC address. \
 *iface* The name of a network interface on the local system. \
 *ip* The IP address of a network interface on the local system.

**Returns**

0 if the interface was successfully identified, or non-zero otherwise.

### int lo\_address\_set\_stream\_slip (lo\_address t, lo\_slip\_encoding encoding)

Set outgoing stream connections (e.g., TCP) to be transmitted using the SLIP packetizing protocol.

**Parameters**

*t* The address to set this flag for. \
 *encoding* Specify single- or double-ENDed SLIP, or disable SLIP.

**Returns**

the previous value of this flag.

### int lo\_address\_set\_tcp\_nodelay (lo\_address t, int enable)

Set the TCP\_NODELAY flag on outgoing TCP connections.

**Parameters**

*t* The address to set this flag for. \
 *enable* Non-zero to set the flag, zero to unset it.

**Returns**

the previous value of this flag.

### void lo\_address\_set\_ttl (lo\_address t, int ttl)

Set the Time-to-Live value for a given target address. This is required for sending multicast UDP messages. A value of 1 (the usual case) keeps the message within the subnet, while 255 means a global, unrestricted scope.

**Parameters**

*t* An OSC address. \
 *ttl* An integer specifying the scope of a multicast UDP message.

### void lo\_arg\_host\_endian (lo\_type type, void \* data)

Convert the specified argument to host byte order where necessary.

**Parameters**

*type* The OSC type of the data item (eg. LO\_FLOAT). \
 *data* A pointer to the data item to be converted. It is changed in-place.

### void lo\_arg\_network\_endian (lo\_type type, void \* data)

Convert the specified argument to network byte order where necessary.

**Parameters**

*type* The OSC type of the data item (eg. LO\_FLOAT). \
 *data* A pointer to the data item to be converted. It is changed in-place.

### size\_t lo\_arg\_size (lo\_type type, void \* data)

Return the storage size, in bytes, of the given argument.

### uint32\_t lo\_blobsize (lo\_blob b)

A function to calculate the amount of OSC message space required by a **lo\_blob** object. Returns the storage size in bytes, which will always be a multiple of four.

### int lo\_bundle\_add\_bundle (lo\_bundle b, lo\_bundle n)

Adds an OSC bundle to an existing bundle. The child bundle passed is appended to the list of child bundles\|messages in the parent bundle to be dispatched.

**Returns**

0 if successful, less than 0 otherwise.

### int lo\_bundle\_add\_message (lo\_bundle b, const char \* path, lo\_message m)

Adds an OSC message to an existing bundle. The message passed is appended to the list of messages in the bundle to be dispatched to 'path'.

**Returns**

0 if successful, less than 0 otherwise.

### void lo\_bundle\_clear (lo\_bundle b)

Clear elements from a **lo\_bundle** but do not free allocated memory.

### unsigned int lo\_bundle\_count (lo\_bundle b)

Return the number of top-level elements in a bundle.

**Parameters**

*b* The bundle to be counted.

### void lo\_bundle\_free (lo\_bundle b)

Frees the memory taken by a bundle object.

**Parameters**

*b* The bundle to be freed.

### void lo\_bundle\_free\_messages (lo\_bundle b)

Obsolete, use lo\_bundle\_free\_recursive instead.

**Parameters**

*b* The bundle, which may contain messages and nested bundles, to be freed.

### void lo\_bundle\_free\_recursive (lo\_bundle b)

Frees the memory taken by a bundle object and its messages and nested bundles recursively.

**Parameters**

*b* The bundle, which may contain messages and nested bundles, to be freed.

### lo\_bundle lo\_bundle\_get\_bundle (lo\_bundle b, int index)

Gets a nested bundle contained within a bundle. Returns a **lo\_bundle** at a given index within a bundle.

**Returns**

The requested **lo\_bundle** if successful, otherwise 0.

### lo\_message lo\_bundle\_get\_message (lo\_bundle b, int index, const char \*\* path)

Gets a message contained within a bundle. Returns a **lo\_message** at a given index within a bundle, and optionally the path associated with that message.

**Returns**

The requested **lo\_message** if successful, otherwise 0.

### lo\_timetag lo\_bundle\_get\_timestamp (lo\_bundle b)

Get the timestamp associated with a bundle.

**Parameters**

*b* The bundle for which the timestamp should be returned.

**Returns**

The timestamp of the bundle as a **lo\_timetag**.

### lo\_element\_type lo\_bundle\_get\_type (lo\_bundle b, int index)

Gets the element type contained within a bundle. Returns a **lo\_element\_type** at a given index within a bundle.

**Returns**

The requested **lo\_element\_type** if successful, otherwise 0.

### void lo\_bundle\_incref (lo\_bundle b)

Add one to a bundle's reference count. Bundles are reference counted. If a bundle is multiply referenced, the bundle's counter should be incremented. It is automatically decremented by lo\_bundle\_free lo\_bundle\_free\_recursive, with lo\_bundle\_free\_recursive being the preferable method.

### size\_t lo\_bundle\_length (lo\_bundle b)

Return the length of a bundle in bytes. Includes the marker and typetag length.

**Parameters**

*b* The bundle to be sized

### lo\_bundle lo\_bundle\_new (lo\_timetag tt)

Create a new bundle object. OSC Bundles encapsulate one or more OSC messages and may include a timestamp indicating when the bundle should be dispatched.

**Parameters**

*tt* The timestamp when the bundle should be handled by the receiver. Pass LO\_TT\_IMMEDIATE if you want the receiving server to dispatch the bundle as soon as it receives it.

### void \* lo\_bundle\_serialise (lo\_bundle b, void \* to, size\_t \* size)

Serialise the bundle object to an area of memory and return a pointer to the serialised form.

**Parameters**

*b* The bundle to be serialised \
 *to* The address to serialise to, memory will be allocated if to is NULL. \
 *size* If this pointer is non-NULL the size of the memory area will be written here

The returned form is suitable to be sent over a low level OSC transport, having the correct endianess and bit-packed structure.

### void lo\_bundle\_set\_timestamp (lo\_bundle b, lo\_timetag t)

Get the timestamp associated with a bundle.

**Parameters**

*b* The bundle for which the timestamp should be returned. \
 *t* The timestamp to write.

### int lo\_coerce (lo\_type type\_to, lo\_arg \* to, lo\_type type\_from, lo\_arg \* from)

Attempt to convert one OSC type to another. Numerical types (eg LO\_INT32, LO\_FLOAT etc.) may be converted to other numerical types and string types (LO\_STRING and LO\_SYMBOL) may be converted to the other type. This is done automatically if a received message matches the path, but not the exact types, and is coercible (ie. all numerical types in numerical positions).

On failure no translation occurs and false is returned.

**Parameters**

*type\_to* The type of the destination variable. \
 *to* A pointer to the destination variable. \
 *type\_from* The type of the source variable. \
 *from* A pointer to the source variable.

### char \* lo\_get\_path (void \* data, ssize\_t size)

Given a raw OSC message, return the message path.

**Parameters**

*data* A pointer to the raw OSC message data. \
 *size* The size of data in bytes (total buffer bytes).

Returns the message path or NULL if an error occurs. Do not free() the returned pointer.

### lo\_hires lo\_hires\_val (lo\_type type, lo\_arg \* p)

Return the numerical value of the given argument with the maximum native system precision.

### int lo\_is\_numerical\_type (lo\_type a)

Return true if the type specified has a numerical value, such as LO\_INT32, LO\_FLOAT etc.

**Parameters**

*a* The type to be tested.

### int lo\_is\_string\_type (lo\_type a)

Return true if the type specified has a textual value, such as LO\_STRING or LO\_SYMBOL.

**Parameters**

*a* The type to be tested.

### int lo\_message\_add (lo\_message m, const char \* types, ...)

Append a number of arguments to a message. The data will be added in OSC byteorder (bigendian).

**Parameters**

*m* The message to be extended. \
 *types* The types of the data items in the message, types are defined in lo\_types\_common.h \
 *...* The data values to be transmitted. The types of the arguments passed here must agree with the types specified in the type parameter.

**Returns**

Less than 0 on failure, 0 on success.

### int lo\_message\_add\_blob (lo\_message m, lo\_blob a)

Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.

**Returns**

Less than 0 on failure, 0 on success.

### int lo\_message\_add\_char (lo\_message m, char a)

Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.

**Returns**

Less than 0 on failure, 0 on success.

### int lo\_message\_add\_double (lo\_message m, double a)

Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.

**Returns**

Less than 0 on failure, 0 on success.

### int lo\_message\_add\_false (lo\_message m)

Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.

**Returns**

Less than 0 on failure, 0 on success.

### int lo\_message\_add\_float (lo\_message m, float a)

Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.

**Returns**

Less than 0 on failure, 0 on success.

### int lo\_message\_add\_infinitum (lo\_message m)

Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.

**Returns**

Less than 0 on failure, 0 on success.

### int lo\_message\_add\_int32 (lo\_message m, int32\_t a)

Append a data item and typechar of the specified type to a message. The data will be added in OSC byteorder (bigendian).

**Parameters**

*m* The message to be extended. \
 *a* The data item.

**Returns**

Less than 0 on failure, 0 on success.

### int lo\_message\_add\_int64 (lo\_message m, int64\_t a)

Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.

**Returns**

Less than 0 on failure, 0 on success.

### int lo\_message\_add\_midi (lo\_message m, uint8\_t a\[4\])

Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.

**Returns**

Less than 0 on failure, 0 on success.

### int lo\_message\_add\_nil (lo\_message m)

Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.

**Returns**

Less than 0 on failure, 0 on success.

### int lo\_message\_add\_string (lo\_message m, const char \* a)

Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.

**Returns**

Less than 0 on failure, 0 on success.

### int lo\_message\_add\_symbol (lo\_message m, const char \* a)

Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.

**Returns**

Less than 0 on failure, 0 on success.

### int lo\_message\_add\_timetag (lo\_message m, lo\_timetag a)

Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.

**Returns**

Less than 0 on failure, 0 on success.

### int lo\_message\_add\_true (lo\_message m)

Append a data item and typechar of the specified type to a message. See **lo\_message\_add\_int32()** for details.

**Returns**

Less than 0 on failure, 0 on success.

### int lo\_message\_add\_varargs (lo\_message m, const char \* types, va\_list ap)

Append a varargs list to a message. The data will be added in OSC byteorder (bigendian). IMPORTANT: args list must be terminated with LO\_ARGS\_END, or this call will fail. This is used to do simple error checking on the sizes of parameters passed.

**Parameters**

*m* The message to be extended. \
 *types* The types of the data items in the message, types are defined in lo\_types\_common.h \
 *ap* The va\_list created by a C function declared with an ellipsis (...) argument, and pre-initialised with "va\_start(ap)". The types of the arguments passed here must agree with the types specified in the type parameter.

**Returns**

Less than 0 on failure, 0 on success.

### void lo\_message\_clear (lo\_message m)

Clear elements from a **lo\_message** but do not free allocated memory.

### lo\_message lo\_message\_clone (lo\_message m)

Create a new **lo\_message** object by cloning an already existing one.

### int lo\_message\_decref (lo\_message m)

Subtract one from a message's reference count. Messages are reference counted. In general decrementing the counter should be handled automatically using **lo\_message\_free or lo\_bundle\_free\_recursive, however if necessary the counter can be decremented manually.**

### lo\_message lo\_message\_deserialise (void \* data, size\_t size, int \* result)

**Deserialise a raw OSC message and return a new lo\_message object. Opposite of lo\_message\_serialise().**

**Parameters**

*data* **Pointer to the raw OSC message data in network transmission form (network byte order where appropriate).** \
 *size* **The size of data in bytes** \
 *result* **If this pointer is non-NULL, the result or error code will be written here.**

**Returns a new lo\_message, or NULL if deserialisation fails. Use lo\_message\_free() to free the resulting object.**

### void lo\_message\_free (lo\_message m)

**Free memory allocated by lo\_message\_new() and any subsequent lo\_message\_add\_int32 lo\_message\_add\*() calls.**

### int lo\_message\_get\_argc (lo\_message m)

**Return the message argument count. The result is valid until further data is added with lo\_message\_add\*().**

### lo\_arg \*\* lo\_message\_get\_argv (lo\_message m)

**Return the message arguments. Do not free the returned data. The result is valid until further data is added with lo\_message\_add\*().**

### lo\_address lo\_message\_get\_source (lo\_message m)

**Returns the source (lo\_address) of an incoming message. Returns NULL if the message is outgoing. Do not free the returned address. This is usually called on the lo\_message passed to lo\_method\_handler, to set up bidirectional communication. See example\_tcp\_echo\_server.c for an example of this.**

### lo\_timetag lo\_message\_get\_timestamp (lo\_message m)

**Returns the timestamp (lo\_timetag \*) of a bundled incoming message. Returns LO\_TT\_IMMEDIATE if the message is outgoing, or did not arrive contained in a bundle. Do not free the returned timetag.**

### char \* lo\_message\_get\_types (lo\_message m)

**Return the message type tag string. The result is valid until further data is added with lo\_message\_add\*().**

### void lo\_message\_incref (lo\_message m)

**Add one to a message's reference count. Messages are reference counted. If a message is multiply referenced, the message's counter should be incremented. It is automatically decremented by lo\_message\_free or lo\_bundle\_free\_recursive, with lo\_bundle\_free\_recursive being the preferable method if bundles are used.**

### size\_t lo\_message\_length (lo\_message m, const char \* path)

**Return the length of a message in bytes.**

**Parameters**

*m* **The message to be sized** \
 *path* **The path the message will be sent to**

### lo\_message lo\_message\_new (void )

**Create a new lo\_message object.**

### void \* lo\_message\_serialise (lo\_message m, const char \* path, void \* to, size\_t \* size)

**Serialise the lo\_message object to an area of memory and return a pointer to the serialised form. Opposite of lo\_message\_deserialise().**

**Parameters**

*m* **The message to be serialised** \
 *path* **The path the message will be sent to** \
 *to* **The address to serialise to, memory will be allocated if to is NULL.** \
 *size* **If this pointer is non-NULL the size of the memory area will be written here**

**The returned form is suitable to be sent over a low level OSC transport, having the correct endianess and bit-packed structure.**

### int lo\_pattern\_match (const char \* str, const char \* p)

**Test a string against an OSC pattern glob.**

**Parameters**

*str* **The string to test** \
 *p* **The pattern to test against**

**Returns**

**1 if true, 0 otherwise.**

### int lo\_send\_bundle (lo\_address targ, lo\_bundle b)

**Send a lo\_bundle object to address targ. Bundles are constructed with the lo\_bundle\_new() and lo\_bundle\_add\_message() functions.**

### int lo\_send\_bundle\_from (lo\_address targ, lo\_server serv, lo\_bundle b)

**Send a lo\_bundle object to address targ from address of serv. Bundles are constructed with the lo\_bundle\_new() and lo\_bundle\_add\_message() functions.**

**Parameters**

*targ* **The address to send the bundle to** \
 *serv* **The server socket to send the bundle from (can be NULL to use new socket)** \
 *b* **The bundle itself**

### int lo\_send\_message (lo\_address targ, const char \* path, lo\_message msg)

**Send a lo\_message object to target targ. This is slightly more efficient than lo\_send() if you want to send a lot of similar messages. The messages are constructed with the lo\_message\_new() and lo\_message\_add\*() functions.**

### int lo\_send\_message\_from (lo\_address targ, lo\_server serv, const char \* path, lo\_message msg)

**Send a lo\_message object to target targ from address of serv. This is slightly more efficient than lo\_send() if you want to send a lot of similar messages. The messages are constructed with the lo\_message\_new() and lo\_message\_add\*() functions.**

**Parameters**

*targ* **The address to send the message to** \
 *serv* **The server socket to send the message from (can be NULL to use new socket)** \
 *path* **The path to send the message to** \
 *msg* **The bundle itself**

### int lo\_server\_add\_bundle\_handlers (lo\_server s, lo\_bundle\_start\_handler sh, lo\_bundle\_end\_handler eh, void \* user\_data)

**Add bundle notification handlers to the specified server.**

**Parameters**

*s* **The server the method is to be added to.** \
 *sh* **The callback function that will be called before the messages of a bundle are dispatched** \
 *eh* **The callback function that will be called after the messages of a bundle are dispatched** \
 *user\_data* **A value that will be passed to the user\_data parameter of both callback functions.**

### lo\_method lo\_server\_add\_method (lo\_server s, const char \* path, const char \* typespec, lo\_method\_handler h, const void \* user\_data)

**Add an OSC method to the specifed server.**

**Parameters**

*s* **The server the method is to be added to.** \
 *path* **The OSC path to register the method to. If NULL is passed the method will match all paths.** \
 *typespec* **The typespec the method accepts. Incoming messages with similar typespecs (e.g. ones with numerical types in the same position) will be coerced to the typespec given here.** \
 *h* **The method handler callback function that will be called if a matching message is received** \
 *user\_data* **A value that will be passed to the callback function, h, when its invoked matching from this method.**

**Returns**

**A unique pointer identifying the method. It should not be freed.**

### int lo\_server\_del\_lo\_method (lo\_server s, lo\_method m)

**Delete a specific OSC method from the specified server.**

**Parameters**

*s* **The server the method is to be removed from.** \
 *m* **The lo\_method identifier returned from lo\_server\_add\_method for the method to delete from the server.**

**Returns**

**Non-zero if it was not found in the list of methods for the server.**

### void lo\_server\_del\_method (lo\_server s, const char \* path, const char \* typespec)

**Delete an OSC method from the specified server.**

**Parameters**

*s* **The server the method is to be removed from.** \
 *path* **The OSC path of the method to delete. If NULL is passed the method will match the generic handler.** \
 *typespec* **The typespec the method accepts.**

### int lo\_server\_dispatch\_data (lo\_server s, void \* data, size\_t size)

**Dispatch a raw block of memory containing an OSC message. This is useful when a raw block of memory is available that is structured as OSC, and you wish to use liblo to dispatch the message to a handler function as if it had been received over the network.**

**Parameters**

*s* **The lo\_server to use for dispatching.** \
 *data* **Pointer to the raw OSC message data in network transmission form (network byte order where appropriate).** \
 *size* **The size of data in bytes**

**Returns the number of bytes used if successful, or less than 0 otherwise.**

### int lo\_server\_enable\_coercion (lo\_server server, int enable)

**Enables or disables type coercion during message dispatch.**

**Parameters**

*server* **The server to toggle this option for.** \
 *enable* **Non-zero to enable, or zero to disable type coercion.**

**Returns**

**The previous value of this option.**

### int lo\_server\_enable\_queue (lo\_server s, int queue\_enabled, int dispatch\_remaining)

**Toggle event queue. If queueing is enabled, timetagged messages that are sent in advance of the current time will be put on an internal queue, and they will be dispatched at the indicated time. By default, queueing is enabled. Use this function to disable it, if it is desired to have a server process messages immediately. In that case, use lo\_message\_get\_timestamp() to get the message timestamp from within a method handler.**

**Parameters**

*s* **A liblo server** \
 *queue\_enabled* **Zero to disable queue, non-zero to enable.** \
 *dispatch\_remaining* **If non-zero, previously queued messages will be immediately dispatched when queue is disabled.**

**Returns**

**The previous state of queue behaviour. Zero if queueing was previously disabled, non-zero otherwise.**

### int lo\_server\_events\_pending (lo\_server s)

**Return true if there are scheduled events (eg. from bundles) waiting to be dispatched by the server.**

### void lo\_server\_free (lo\_server s)

**Free up memory used by the lo\_server object.**

**Referenced by lo::Server::~Server().**

### int lo\_server\_get\_port (lo\_server s)

**Return the port number that the server has bound to. Useful when NULL is passed for the port number and you wish to know how to address the server.**

### int lo\_server\_get\_protocol (lo\_server s)

**Return the protocol that the server is using. Returned value will be one of LO\_UDP, LO\_TCP or LO\_UNIX.**

### int lo\_server\_get\_socket\_fd (lo\_server s)

**Return the file descriptor of the server socket. If the server protocol supports exposing the server's underlying receive mechanism for monitoring with select() or poll(), this function returns the file descriptor needed, otherwise, it returns -1.**

**WARNING: when using this function beware that not all OSC packets that are received are dispatched immediately. lo\_server\_events\_pending() and lo\_server\_next\_event\_delay() can be used to tell if there are pending events and how long before you should attempt to receive them.**

### char \* lo\_server\_get\_url (lo\_server s)

**Return an OSC URL that can be used to contact the server. The return value should be free()'d when it is no longer needed.**

### int lo\_server\_max\_msg\_size (lo\_server s, int req\_size)

**Set the maximum message size accepted by a server. For UDP servers, the maximum message size cannot exceed 64k, due to the UDP transport specifications. For TCP servers, this number may be larger, but be aware that one or more contiguous blocks of memory of this size may be allocated by liblo. (At least one per connection.)**

**Parameters**

*s* **The server on which to operate.** \
 *req\_size* **The new maximum message size to request, 0 if it should not be modified, or -1 if it should be set to unlimited. Note that an unlimited message buffer may make your application open to a denial of service attack.**

**Returns**

**The new maximum message size is returned, which may or may not be equal to req\_size. If -1 is returned, maximum size is unlimited.**

### lo\_server lo\_server\_new (const char \* port, lo\_err\_handler err\_h)

**Create a new server instance. Using lo\_server\_recv(), lo\_servers block until they receive OSC messages. Most likely you want non-blocking behaviour, so use of lo\_server\_recv\_noblock() is encouraged or the lo\_server\_thread\_new and "lo\_server\_thread\_\*" functions.**

**Parameters**

*port* **If NULL is passed then an unused UDP port will be chosen by the system, its number may be retrieved with lo\_server\_thread\_get\_port() so it can be passed to clients. Otherwise a decimal port number, service name or UNIX domain socket path may be passed.** \
 *err\_h* **An error callback function that will be called if there is an error in messge reception or server creation. Pass NULL if you do not want error handling.**

**Referenced by lo::Server::Server(), and lo::Server::Server().**

### lo\_server lo\_server\_new\_from\_config (lo\_server\_config \* config)

**Create a new server instance, using a configuration struct.**

**Parameters**

*config* **A pre-initialized config struct. A pointer to it will not be kept.**

**Returns**

**A new lo\_server instance.**

### lo\_server lo\_server\_new\_from\_url (const char \* url, lo\_err\_handler err\_h)

**Create a new server instance, taking port and the optional multicast group IP from an URL string.**

**Parameters**

*url* **The URL to specify the server parameters.** \
 *err\_h* **An error callback function that will be called if there is an error in messge reception or server creation. Pass NULL if you do not want error handling.**

**Returns**

**A new lo\_server instance.**

### lo\_server lo\_server\_new\_multicast (const char \* group, const char \* port, lo\_err\_handler err\_h)

**Create a new server instance, and join a UDP multicast group.**

**Parameters**

*group* **The multicast group to join. See documentation on IP multicast for the acceptable address range; e.g., http://tldp.org/HOWTO/Multicast-HOWTO-2.html** \
 *port* **If using UDP then NULL may be passed to find an unused port. Otherwise a decimal port number or service name or may be passed. If using UNIX domain sockets then a socket path should be passed here.** \
 *err\_h* **An error callback function that will be called if there is an error in messge reception or server creation. Pass NULL if you do not want error handling.**

**Referenced by lo::Server::Server().**

### lo\_server lo\_server\_new\_multicast\_iface (const char \* group, const char \* port, const char \* iface, const char \* ip, lo\_err\_handler err\_h)

**Create a new server instance, and join a UDP multicast group, optionally specifying which network interface to use. Note that usually only one of iface or ip are specified.**

**Parameters**

*group* **The multicast group to join. See documentation on IP multicast for the acceptable address range; e.g., http://tldp.org/HOWTO/Multicast-HOWTO-2.html** \
 *port* **If using UDP then NULL may be passed to find an unused port. Otherwise a decimal port number or service name or may be passed. If using UNIX domain sockets then a socket path should be passed here.** \
 *iface* **A string specifying the name of a network interface to use, or zero if not specified.** \
 *ip* **A string specifying the IP address of a network interface to use, or zero if not specified.** \
 *err\_h* **An error callback function that will be called if there is an error in messge reception or server creation. Pass NULL if you do not want error handling.**

**Referenced by lo::Server::Server(), and lo::Server::Server().**

### lo\_server lo\_server\_new\_with\_proto (const char \* port, int proto, lo\_err\_handler err\_h)

**Create a new server instance, specifying protocol. Using lo\_server\_recv(), lo\_servers block until they receive OSC messages. Most likely you want non-blocking behaviour, so use of lo\_server\_recv\_noblock() is encouraged or the lo\_server\_thread\_new and "lo\_server\_thread\_\*" functions.**

**Parameters**

*port* **If using UDP then NULL may be passed to find an unused port. Otherwise a decimal port number orservice name or may be passed. If using UNIX domain sockets then a socket path should be passed here.** \
 *proto* **The protocol to use, should be one of LO\_UDP, LO\_TCP or LO\_UNIX.** \
 *err\_h* **An error callback function that will be called if there is an error in messge reception or server creation. Pass NULL if you do not want error handling.**

**Referenced by lo::Server::Server(), and lo::Server::Server().**

### double lo\_server\_next\_event\_delay (lo\_server s)

**Return the time in seconds until the next scheduled event. If the delay is greater than 100 seconds then it will return 100.0.**

### int lo\_server\_recv (lo\_server s)

**Block, waiting for an OSC message to be received. The blocking behavior of this function is, in most cases, undesireable, since a program with no incoming messages may never exit. It is encouraged to use lo\_server\_recv\_noblock() instead, which is equivalent to lo\_server\_wait() and then lo\_server\_recv().**

**The return value is the number of bytes in the received message. The message will be dispatched to a matching method if one is found. In cases where no message is received but returning is necessary anyway, this function may return 0.**

### int lo\_server\_recv\_noblock (lo\_server s, int timeout)

**Look for an OSC message waiting to be received. In new programs, this function should be prefered over lo\_server\_recv().**

**Parameters**

*s* **The server to wait for connections on.** \
 *timeout* **A timeout in milliseconds to wait for the incoming packet. a value of 0 will return immediately.**

**The return value is the number of bytes in the received message or 0 if there is no message. The message will be dispatched to a matching method if one is found.**

### int lo\_server\_wait (lo\_server s, int timeout)

**Wait for an OSC message to be received.**

**Parameters**

*s* **The server to wait for connections on.** \
 *timeout* **A timeout in milliseconds to wait for the incoming packet. a value of 0 will return immediately.**

**The return value is 1 if there is a message waiting, 0 if there is no message, and -1 if there is an error that causes the function to return early. If there is a message waiting you can now call lo\_server\_recv() to receive that message. This is preferable to using lo\_server\_recv() alone, since otherwise it may never exit if no new messages are incoming.**

### int lo\_servers\_recv\_noblock (lo\_server \* s, int \* recvd, int num\_servers, int timeout)

**Look for an OSC message waiting to be received on multiple servers.**

**Parameters**

*s* **As array of servers to wait for connections on.** \
 *recvd* **An array to store the number of bytes received by each server in array s.** \
 *num\_servers* **The number of servers in the array s.** \
 *timeout* **A timeout in milliseconds to wait for the incoming packet. a value of 0 will return immediately.**

**The return value is the total number of bytes received by all servers. The messages will be dispatched to a matching method if one is found.**

### int lo\_servers\_wait (lo\_server \* s, int \* status, int num\_servers, int timeout)

**Wait on multiple servers for an OSC message to be received.**

**Parameters**

*s* **An array of servers to wait for connections on.** \
 *status* **An array to receive the status of each server.** \
 *num\_servers* **The number of servers in the array s.** \
 *timeout* **A timeout in milliseconds to wait for the incoming packet. a value of 0 will return immediately.**

**The return value is the number of servers with a message waiting or -1 if there is an error that causes the function to return early. If there is a message waiting you can now call lo\_server\_recv() to receive that message. This is preferable to using lo\_server\_recv() alone, since otherwise it may never exit if no new messages are incoming.**

### int lo\_string\_contains\_pattern (const char \* str)

**Test if a string contains any OSC pattern characters.**

**Parameters**

*str* **The string to test**

**Returns**

**1 if true, 0 otherwise.**

### int lo\_strsize (const char \* s)

**A function to calculate the amount of OSC message space required by a C char \*. Returns the storage size in bytes, which will always be a multiple of four.**

### double lo\_timetag\_diff (lo\_timetag a, lo\_timetag b)

**Find the time difference between two timetags. Returns a - b in seconds.**

### void lo\_timetag\_now (lo\_timetag \* t)

**Return a timetag for the current time. On exit the timetag pointed to by t is filled with the OSC representation of this instant in time.**

**Referenced by lo::now().**

### char \* lo\_url\_get\_hostname (const char \* url)

**Return the hostname portion of an OSC URL. The return value should be free()'d when it is no longer needed.**

### char \* lo\_url\_get\_path (const char \* url)

**Return the path portion of an OSC URL. The return value should be free()'d when it is no longer needed.**

### char \* lo\_url\_get\_port (const char \* url)

**Return the port portion of an OSC URL. The return value should be free()'d when it is no longer needed.**

### char \* lo\_url\_get\_protocol (const char \* url)

**Return the protocol portion of an OSC URL, eg. udp, tcp. This library uses OSC URLs of the form: osc.prot://hostname:port/path if the prot part is missing, UDP is assumed.**

**The return value should be free()'d when it is no longer needed.**

### int lo\_url\_get\_protocol\_id (const char \* url)

**Return the protocol ID of an OSC URL. This library uses OSC URLs of the form: osc.prot://hostname:port/path if the prot part is missing, UDP is assumed. Returned value will be one of LO\_UDP, LO\_TCP, LO\_UNIX or -1.**

**Returns**

**An integer specifying the protocol. Return -1 when the protocol is not supported by liblo.**

## Author

**Generated automatically by Doxygen for liblo from the source code.**