9 Utility functions

There are a lot of helper functions to make writing Assuan code easier. Some of these functions provide information not available with the general functions.

Function: gpg_error_t assuan_write_status (assuan_context_t ctx, const char *keyword, const char *text)

This is a convenience function for a server to send a status line. You need to pass it the keyword and the content of the status line in text.

Function: gpg_error_t assuan_inquire (assuan_context_t ctx, const char *keyword, unsigned char **r_buffer, size_t *r_length, size_t maxlen)

A server may use this function to request specific data from a client. This function sends an ’INQUIRE’ command back to the client and returns the client’s response in a newly allocated buffer. You need to pass at least the server’s context (ctx) and a description of the required data (keyword). All other parameters may be NULL or 0, but this is rarely useful.

On success the result is stored in a newly allocated buffer stored at r_buffer. The length of the data is stored at r_length. If maxlen has not been given as 0, it specifies an upper size limit of the expected data. If the client returns too much data the function fails and an error with the error code GPG_ERR_ASS_TOO_MUCH_DATA will be returned.

Function: FILE* assuan_get_data_fp (assuan_context_t ctx)

Return a stdio stream for the Assuan context ctx. This stream may then be used for data output (assuan_write_data). The stream is valid until the end of the current handler. Calling fclose for that stream is not required. Assuan does all the buffering needed to insert the status line as well as the required line wrapping and quoting for data lines.

This function is only available on systems supporting either funopen or fopencookie. If it is not supported NULL is returned and errno is set to ENOSYS.

Function: gpg_error_t assuan_set_okay_line (assuan_context_t ctx, const char *line)

Set the text used for the next OK response to line. This is sometimes useful to send additional human readable information along with the OK line. The string is automatically reset at the end of the current handler.

Function: gpg_error_t assuan_command_parse_fd (assuan_context_t ctx, char *line, assuan_fd_t *rfd)

This is the core of the default INPUT and OUTPUT handler. It may be used in custom commands as well to negotiate a file descriptor. If line contains FD=n, it returns n in rfd assuming a local file descriptor. If line contains just FD it returns a file descriptor at rfd; this file descriptor needs to have been sent by the client right before using assuan_sendfd.

On W32 systems the returned file descriptor is a system handle and not a libc low level I/O file descriptor. Thus applications need to use _open_osfhandle before they can pass this descriptor to standard functions like fdopen or dup.

Function: const char * assuan_get_command_name (assuan_context_t ctx)

Return the name of the command currently processed by a handler. The returned string is valid until the next call to an Assuan function on the same context. Returns NULL if no handler is executed or the command is not known.

Function: assuan_fd_t assuan_get_input_fd (assuan_context_t ctx)

Return the file descriptor sent by the client using the last INPUT command. Returns ASSUAN_INVALID_FD if no file descriptor is available.

Function: assuan_fd_t assuan_get_output_fd (assuan_context_t ctx)

Return the file descriptor sent by the client using the last OUTPUT command. Returns ASSUAN_INVALID_FD if no file descriptor is available.

Function: gpg_error_t assuan_close_input_fd (assuan_context_t ctx)

Close the file descriptor set by the last INPUT command. This function has the advantage over a simple close that it can do some sanity checks and make sure that a following assuan_get_input_fd won’t return an already closed descriptor.

Function: gpg_error_t assuan_close_output_fd (assuan_context_t ctx)

Close the file descriptor set by the last OUTPUT command. This function has the advantage over a simple close that it can do some sanity checks and make sure that a following assuan_get_input_fd won’t return an already closed descriptor.

Function: gpg_error_t assuan_set_error (assuan_context_t ctx, gpg_error_t err, const char *text)

This is a helper to provide a more descriptive error text with ERR lines. For this to work, the text needs to be stored in the context ctx while still being in the command handler. This function is commonly called this way

  return assuan_set_error (ctx, err, "commands needs 5 arguments");

The value err is passed through and thus the return value of the command handler in the example. The provided text further explains that error to humans.

Function: pid_t assuan_get_pid (assuan_context_t ctx)

This function returns the pid of the connected connected peer. If that pid is not known ASSUAN_INVALID_PID is returned. Note that it is not always possible to learn the pid of the other process. For a pipe based server the client knows it instantly and a mechanism is in place to let the server learn it. For socket based servers the pid is only available on systems providing the SO_PEERCRED socket option ¹.

Data type: assuan_peercred_t

This structure is used to store the peer credentials. The available members depend on the operating system.

pid_t pid

The process ID of the peer.

uid_t uid

The user ID of the peer process.

gid_t gid

The group ID of the peer process.

Function: gpg_error_t assuan_get_peercred (assuan_context_t ctx, assuan_peercred_t *peercred)

Return user credentials of the peer. This will work only on certain systems and only when connected over a socket. On success, a pointer to the peer credentials is stored in peercred. The information is only valid as long as the state of the connection is unchanged (at least until the next assuan call to the same context).

As of now only the server is able to retrieve this information. Note, that for getting the pid of the peer assuan_get_pid is usually better suited.

Function: int assuan_get_active_fds (assuan_context_t ctx, int what, assuan_fd_t *fdarray, int fdarraysize)

Return all active file descriptors for the context ctx. This function can be used to select on the file descriptors and to call assuan_process_next if there is an active one. The first descriptor in the array is the one used for the command connection. Currently what needs to be 0 to return descriptors used for reading, 1 will eventually be used to return descriptors used for writing. fdarray is an array of integers provided by the caller; fdarraysize gives the size of that array.

On success the number of active descriptors are returned. These active descriptors are then stored in fdarray. On error -1 is returned; the most likely reason for this is a too small fdarray.

Note that on W32 systems the returned file descriptor is a system handle and not a libc low level I/O file descriptor.

Function: int assuan_pending_line (assuan_context_t ctx)

A call to this function return true if a full line has been buffered and thus an entire assuan line may be read without triggering any actual I/O.