1.\" Copyright (c) 2018 Yubico AB. All rights reserved. 2.\" Use of this source code is governed by a BSD-style 3.\" license that can be found in the LICENSE file. 4.\" 5.Dd $Mdocdate: May 25 2018 $ 6.Dt FIDO_DEV_SET_IO_FUNCTIONS 3 7.Os 8.Sh NAME 9.Nm fido_dev_set_io_functions , 10.Nm fido_dev_set_sigmask 11.Nd FIDO 2 device I/O interface 12.Sh SYNOPSIS 13.In fido.h 14.Bd -literal 15typedef void *fido_dev_io_open_t(const char *); 16typedef void fido_dev_io_close_t(void *); 17typedef int fido_dev_io_read_t(void *, unsigned char *, size_t, int); 18typedef int fido_dev_io_write_t(void *, const unsigned char *, size_t); 19 20typedef struct fido_dev_io { 21 fido_dev_io_open_t *open; 22 fido_dev_io_close_t *close; 23 fido_dev_io_read_t *read; 24 fido_dev_io_write_t *write; 25} fido_dev_io_t; 26 27#ifdef _WIN32 28typedef int fido_sigset_t; 29#else 30typedef sigset_t fido_sigset_t; 31#endif 32.Ed 33.Ft int 34.Fn fido_dev_set_io_functions "fido_dev_t *dev" "const fido_dev_io_t *io" 35.Ft int 36.Fn fido_dev_set_sigmask "fido_dev_t *dev" "const fido_sigset_t *sigmask" 37.Sh DESCRIPTION 38The 39.Fn fido_dev_set_io_functions 40function sets the I/O handlers used by 41.Em libfido2 42to talk to 43.Fa dev . 44By default, these handlers are set to the operating system's native HID or NFC 45interfaces. 46They are defined as follows: 47.Bl -tag -width Ds 48.It Vt fido_dev_open_t 49Receives a 50.Vt const char * 51holding a path and opens the corresponding device, returning a 52non-NULL opaque pointer on success and NULL on error. 53.It Vt fido_dev_close_t 54Receives the opaque pointer returned by 55.Vt fido_dev_open_t 56and closes the device. 57.It Vt fido_dev_read_t 58Reads a single transmission unit (HID report, APDU) from a device. 59The first parameter is the opaque pointer returned by 60.Vt fido_dev_open_t . 61The second parameter is the read buffer, and the third parameter 62is the read buffer size. 63The fourth parameter is the number of milliseconds the caller is 64willing to sleep, should the call need to block. 65If this value holds -1, 66.Vt fido_dev_read_t 67may block indefinitely. 68On success, the number of bytes read is returned. 69On error, -1 is returned. 70.It Vt fido_dev_write_t 71Writes a single transmission unit (HID report, APDU) to 72.Fa dev . 73The first parameter is the opaque pointer returned by 74.Vt fido_dev_open_t . 75The second parameter is the write buffer, and the third parameter 76is the number of bytes to be written. 77A 78.Vt fido_dev_write_t 79may block. 80On success, the number of bytes written is returned. 81On error, -1 is returned. 82.El 83.Pp 84When calling 85.Fn fido_dev_set_io_functions , 86the 87.Fa open , 88.Fa close , 89.Fa read , 90and 91.Fa write 92fields of 93.Fa io 94may not be NULL. 95.Pp 96No references to 97.Fa io 98are held by 99.Fn fido_dev_set_io_functions . 100.Pp 101The 102.Fn fido_dev_set_sigmask 103function may be used to specify a non-NULL signal mask 104.Fa sigmask 105to be used while 106.Em libfido2's 107default I/O handlers wait on 108.Fa dev . 109On UNIX-like operating systems, 110.Vt fido_sigset_t 111is defined as 112.Vt sigset_t . 113On Windows, 114.Vt fido_sigset_t 115is defined as 116.Vt int 117and 118.Fn fido_dev_set_sigmask 119is a no-op. 120.Pp 121No references to 122.Fa sigmask 123are held by 124.Fn fido_dev_set_sigmask . 125.Sh RETURN VALUES 126On success, 127.Fn fido_dev_set_io_functions 128and 129.Fn fido_dev_set_sigmask 130return 131.Dv FIDO_OK . 132On error, a different error code defined in 133.In fido/err.h 134is returned. 135