{"size": 2619, "ext": "scrbl", "max_stars_repo_path": "scribblings/ffi-utils.scrbl", "max_stars_repo_name": "thinkmoore/ffi-utils", "max_stars_repo_stars_event_min_datetime": null, "max_stars_repo_stars_event_max_datetime": null, "max_issues_repo_path": "scribblings/ffi-utils.scrbl", "max_issues_repo_name": "thinkmoore/ffi-utils", "max_issues_repo_issues_event_min_datetime": null, "max_issues_repo_issues_event_max_datetime": null, "max_forks_repo_path": "scribblings/ffi-utils.scrbl", "max_forks_repo_name": "thinkmoore/ffi-utils", "max_forks_repo_forks_event_min_datetime": null, "max_forks_repo_forks_event_max_datetime": null}
{"max_stars_count": null, "max_issues_count": null, "max_forks_count": null, "avg_line_length": 40.2923076923, "max_line_length": 414, "alphanum_fraction": 0.7472317679}
#lang scribble/manual
@require[@for-label[ffi-utils/data
                    ffi-utils/errno]]

@title{ffi-utils}
@author{Scott Moore}

Utilities for accessing C code using Racket's FFI.

@section{Enumerations and bitmasks}

@defmodule[ffi-utils/data]

@defform[(define-enum name (bit-definer ...) type)
         #:grammar
	 [(name identifier?)
	  (bit-definer (option = value) option)
	  (option identifier?)
	  (value natural?)]]{
Takes a list of symbols and generates an enumeration FFI type @racket[_name] using @racket[_enum], but also defines a predicate @racket[name?] that recognizes symbols given as options and a list @racket[name-symbols] of the symbols that comprise the enumeration.
}

@defform[(provide-enum name)]{
A provide subform that exports the type, predicate, and symbol list generated by a corresponding @racket[define-enum] invocation.
}

@defform[(define-bitmask name (bit-definer ...) type)
         #:grammar
	 [(name identifier?)
	  (bit-definer (flag = value) flag)
	  (flag identifier?)
	  (value natural?)]]{
Takes a list of symbols and generates a bitmask FFI type @racket[_name] using @racket[_bitmask], but also defines a predicate @racket[name?] that recognizes symbols given as flags and a list @racket[name-symbols] of those symbols. In addition, defines a contract @racket[name/c] that recognizes values that are valid to use with the c type: either a symbol indicating a single flag or a list of valid flag symbols.
}

@defform[(provide-bitmask name)]{
A provide subform that exports the type, predicate, and symbol list generated by a corresponding @racket[define-bitmask] invocation.
}

@section{Automatically generating errno values}

@defmodule[ffi-utils/errno]{
During compilation, this module consults clang or gcc to search for system include files that define errno constants. Using the gathered information, it generates functions for converting between errno values, symbols corresponding to #define constants, and user-readable error messages.
}

@defproc[(errno? [v any/c]) boolean?]{
Returns true if @racket[v] is a symbol corresponding to a defined errno value, e.g. @racket['EIO].
}

@defproc[(code->errno [code integer?]) errno?]{
Returns the errno symbol corresponding to the errno value @racket[code].
}

@defproc[(errno->code [errno errno?]) integer?]{
Returns the integer value corresponding to the errno symbol @racket[errno].
}

@defproc[(errno->message [errno errno?]) string?]{
Returns a human-understandable error message for the given errno symbol.
}

@defthing[errno-symbols (listof errno?)]{
A list of the valid errno symbols detected by the module.
}
