---
name: "BRLAPI_AUTHNAME"
section: "3"
platform: "linux"
package: "libbrlapi-dev"
version: "3.4.1-4"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/brlapi_connection"
---

# BRLAPI\_AUTHNAME(3)

Part of [brlapi\_connection(3)](/brlapi_connection/3.md).

## NAME

Connecting to BrlAPI -

### Data Structures

struct **brlapi\_settings\_t**\
 *Settings structure for BrlAPI connection.*

### Defines

\#define **BRLAPI\_SOCKETPORT**   '35751'\
 \#define **BRLAPI\_ETCDIR**   '/etc'\
 \#define **BRLAPI\_AUTHFILE**   'brlapi.key'\
 \#define **BRLAPI\_AUTHNAME**   BRLAPI\_ETCDIR '/' BRLAPI\_AUTHFILE\

### Functions

int **brlapi\_initializeConnection** (const **brlapi\_settings\_t** \*clientSettings, **brlapi\_settings\_t** \*usedSettings)\
 void **brlapi\_closeConnection** (void)\
 int **brlapi\_loadAuthKey** (const char \*filename, int \*authlength, void \*auth)\
 int **brlapi\_getControllingTty** (void)\

## Detailed Description

Before calling any other function of the library, calling **brlapi\_initializeConnection()** is needed to establish a connection to *BrlAPI* 's server. When the connection is no more needed, **brlapi\_closeConnection()** must be called to close the connection.

## Define Documentation

### #define BRLAPI\_AUTHFILE 'brlapi.key'

Default name of the file containing *BrlAPI* 's authentication key

This name is relative to BRLAPI\_ETCDIR

### #define BRLAPI\_AUTHNAME BRLAPI\_ETCDIR '/' BRLAPI\_AUTHFILE

Final path for default authentication key file

### #define BRLAPI\_ETCDIR '/etc'

*brltty* 's settings directory

This is where authentication key and driver-dependent key names are found for instance.

### #define BRLAPI\_SOCKETPORT '35751'

Default port number on which connections to *BrlAPI* can be established

## Function Documentation

### void brlapi\_closeConnection (void)

Cleanly close the socket

This function locks until a closing acknowledgement is received from the server. The socket is then freed, so the file descriptor **brlapi\_initializeConnection()** gave has no meaning any more

### int brlapi\_getControllingTty (void)

Return the number of the caller's controlling terminal

BrlAPI needs to know on which VT the application is connected. This function tries to find it out. It first looks for the CONTROLTTY environment variable, then tries to get it from /proc/self/stat

Hence people has to modify their xinitrc & xsession so that CONTROLTTY is set to 7 for instance, if the X server is launched on VT 7. The value can be got by grepping 'using VT number \[0-9\]\*' from X's log.

I personnaly have

CONTROLVT='$(grep 'using VT number' '/var/log/XFree86.$(echo '$DISPLAY' \| sed -e 's/^.\*::\*\\(\[0-9\]\*\\).\*$/\\1/').log' \| sed -e 's/^.\*using VT number \\(\[0-9\]\*\\).\*$/\\1/')' export CONTROLVT

in my .xsession

People also have to set CONTROLTTY when working remotely (as well as BRLAPI\_HOSTNAME)

**Returns:**

\-1 if unknown or on error

### int brlapi\_initializeConnection (const brlapi\_settings\_t \* clientSettings, brlapi\_settings\_t \* usedSettings)

open a socket and connect it to *BrlAPI* 's server

This function first loads an authentication key as specified in settings. It then creates a TCP socket and connects it to the specified machine, on the specified port. It writes the authentication key on the socket and waits for acknowledgement.

**Returns:**

the file descriptor, or -1 on error

**Note:**

The file descriptor is returned in case the client wants to communicate with the server without using *libbrlapi* functions. If it uses them however, it won't have to pass the file descriptor later, since the library keeps a copy of it

**Example:**.RS 4

```
 if (brlapi_initializeConnection(&settings)<0) {
  fprintf(stderr,'couldn't connect to BrlAPI!0);
  exit(1);
 }
```

**Errors:**.RS 4 *BrlAPI* might not be on this TCP port, the host name might not be resolvable, the authentication may fail,...

**Parameters:**

*clientSettings* this gives the connection parameters, as described in **brlapi\_settings\_t**. If `NULL`, defaults values are used, so that it is generally a good idea to give `NULL` as default, and only fill a **brlapi\_settings\_t** structure when the user gave parameters to the program for instance. \
 *usedSettings* if not `NULL`, parameters which were actually used are stored here, if the application ever needs them.

**See also:**

**brlapi\_settings\_t** **brlapi\_loadAuthKey()** **brlapi\_writePacket()** **brlapi\_readPacket()**

### int brlapi\_loadAuthKey (const char \* filename, int \* authlength, void \* auth)

Load an authentication key from the given file

Calling this function shouldn't be needed if brlapi\_initializeConnection is used.

**Parameters:**

*filename* gives the full path of the file ; \
 *authlength* gives the size of the *auth* buffer ; \
 *auth* is a buffer where the function will store the authentication key

**Returns:**

the size of the key, -1 on error

**See also:**

**brlapi\_settings\_t**, **brlapi\_initializeConnection**