Module: SysBasic¶
Types for low-level programming and C integration.
This module provides basic types when those types are not platform-dependent. The module SysCTypes contains the platform-dependent declarations for C compatability.
This module also defines the error types syserr and err_t.
When should one use syserr and when should one use err_t? err_t is a system error code (a c_int by a nicer name to indicate its purpose). syserr is an enhanced error that might also include an error message. All user-facing Chapel library code, or user Chapel code, should generally use syserr. When wrapping functions or declaring them in C, use err_t to indicate that a function is returning an error code.
A note about the error code documentation in this file. Error descriptions for system errors are included here for convenience only. Other documentation, such as system man pages or the POSIX specification are the authority on system error codes.
- type c_float = real(32)¶
The type corresponding to a C float
- type c_double = real(64)¶
The type corresponding to a C double
- type off_t = int(64)¶
The type corresponding to C’s off_t
- type mode_t = uint(32)¶
The type corresponding to C’s mode_t
- type socklen_t = int(32)¶
The type corresponding to C’s socklen_t
- type syserr¶
A type storing an error code or an error message. A syserr can be compared using == or != to an err_t (ie integer error code) or to another syserr. A syserr can be cast to or from an err_t. It can be assigned the value of an err_t or another syserr. In addition, syserr can be checked directly in an if statement like so:
var err: syserr; if err then do writeln("err contains an error, ie err != ENOERR"); if !err then do writeln("err does not contain an error; err == ENOERR");
When a syserr formal has blank intent, the actual is copied to the formal upon a function call and the formal cannot be assigned within the function.
The default value of the syserr type is undefined.
- type err_t = c_int¶
An integral error code. This is really just a c_int, but code is clearer if you use err_t to indicate arguments, variables, and return types that are system error codes.
- type fd_t = c_int¶
A system file descriptior. This is really just a c_int, but code is clearer if you use fd_t to indicate arguments, variables, and return types that are system file descriptors.
- const c_nil: c_void_ptr¶
A Chapel version of a C NULL pointer.
- proc is_c_nil(x): bool¶
Returns: true if the passed value is a NULL pointer (ie 0)
- class c_ptr¶
A local C pointer class used in C integration. This class represents the equivalent to a C language pointer. Instances of this class support assignment to other instances or nil, == or != comparison with a c_void_ptr or with nil, and casting to another c_ptr type or to the c_void_ptr type. In addition, c_ptr works within an if statement directly like so:
var x: c_ptr; if x then do writeln("x is not nil"); if !x then do writeln("x is nil");
- type eltType¶
The type that this pointer points to
- proc c_ptr(i: integral) ref¶
Retrieve the i’th element (zero based) from a pointer to an array. Does the equivalent of ptr[i] in C.
- proc deref() ref¶
Get element pointed to directly by this pointer. If the pointer refers to an array, this will return ptr[0].
- proc c_calloc(type eltType, size: integral)¶
Allocate memory that is filled with zeros. This memory should eventually be freed with c_free.
Arguments: - eltType – the type of the elements to allocate
- size – the number of elements to allocate
Returns: a c_ptr(eltType) to allocated memory
- proc c_free(data: c_ptr)¶
Free memory that was allocated with c_free. :arg data: the c_ptr to memory that was allocated
- proc c_ptrTo(arr: [])¶
Returns a c_ptr to a Chapel rectangular array. Note that the existence of this c_ptr has no impact on the lifetime of the array. The returned pointer will be invalid if the original array is freed or even reallocated. Any domain assignment will probably make this c_ptr invalid.
Arguments: arr – the array for which we should retrieve a pointer Returns: a pointer to the array data
- proc c_ptrTo(ref x: ?t): c_ptr(t)
Returns a c_ptr to any Chapel object. Note that the existence of the c_ptr has no impact of the lifetime of the object. In many cases the object will be stack allocated and could go out of scope even if this c_ptr remains.
Arguments: x – the by-reference argument to get a pointer to. The argument should not be an array or domain (there is a different overload for arrays). Records, class instances, integral, real, imag, and complex types are supported. Returns: a pointer to the argument passed by reference
- proc ENOERR¶
The error code indicating that no error occured (Chapel specific)
- proc EEOF¶
An error code indicating the end of file has been reached (Chapel specific)
- proc ESHORT¶
An error code indicating that the end of file or the end of the input was reached before the requested amount of data could be read. (Chapel specific)
- proc EFORMAT¶
An error code indicating a format error; for example when reading a quoted string literal, this would be returned if we never encountered the opening quote. (Chapel specific)
- const E2BIG: err_t¶
Argument list too long. The number of bytes used for the argument and environment list of the new process exceeded the current limit. (POSIX.1)
- const EACCES: err_t¶
Permission denied. An attempt was made to access a file in a way forbidden by its file access permissions. (POSIX.1)
- const EADDRINUSE: err_t¶
Address already in use. Only one usage of each address is normally permitted. (POSIX.1)
- const EADDRNOTAVAIL: err_t¶
Can’t assign requested address. Normally results from an attempt to create a socket with an address not on this machine. (POSIX.1)
- const EAFNOSUPPORT: err_t¶
Address family not supported by protocol family. An address incompatible with the requested protocol was used. For example, you should not necessarily expect to be able to use NS addresses with ARPA Internet protocols. (POSIX.1)
- const EAGAIN: err_t¶
Resource temporarily unavailable. This is a temporary condition and later calls to the same routine may complete normally. (POSIX.1)
- const EALREADY: err_t¶
Operation already in progress. An operation was attempted on a non-blocking object that already had an operation in progress. (POSIX.1)
- const EBADE: err_t¶
Invalid exchange (linux only)
- const EBADF: err_t¶
Bad file descriptor. A file descriptor argument was out of range, referred to no open file, or a read (write) request was made to a file that was only open for writing (reading). (POSIX.1)
- const EBADFD: err_t¶
File descriptor in bad state (linux only)
- const EBADMSG: err_t¶
Bad message. A corrupted message was detected. (POSIX.1)
- const EBADR: err_t¶
Invalid request descriptor (linux only)
- const EBADRQC: err_t¶
Invalid request code (linux only)
- const EBADSLT: err_t¶
Invalid slot (linux only)
- const EBUSY: err_t¶
Device or resource busy. An attempt to use a system resource which was in use at the time in a manner which would have conflicted with the request. (POSIX.1)
- const ECANCELED: err_t¶
Operation canceled. The scheduled operation was canceled. (POSIX.1)
- const ECHILD: err_t¶
No child processes. A wait or waitpid system call was executed by a process that had no existing or unwaited-for child processes. (POSIX.1)
- const ECHRNG: err_t¶
Channel number out of range (linux only)
- const ECOMM: err_t¶
Communication error on send (linux only)
- const ECONNABORTED: err_t¶
Software caused connection abort. A connection abort was caused internal to your host machine. (POSIX.1)
- const ECONNREFUSED: err_t¶
Connection refused. No connection could be made because the target machine actively refused it. This usually results from trying to connect to a service that is inactive on the foreign host. (POSIX.1)
- const ECONNRESET: err_t¶
Connection reset by peer. A connection was forcibly closed by a peer. This normally results from a loss of the connection on the remote socket due to a timeout or a reboot. (POSIX.1)
- const EDEADLK: err_t¶
Resource deadlock avoided. An attempt was made to lock a system resource that would have resulted in a deadlock situation. (POSIX.1)
- const EDESTADDRREQ: err_t¶
Destination address required. A required address was omitted from an operation on a socket. (POSIX.1)
- const EDOM: err_t¶
Numerical argument out of domain. A numerical input argument was outside the defined domain of the mathematical function. (POSIX.1, C99)
- const EDQUOT: err_t¶
Disc quota exceeded. A write system call to an ordinary file, the creation of a directory or symbolic link, or the creation of a directory entry failed because the user’s quota of disk blocks was exhausted, or the allocation of an inode for a newly created file failed because the user’s quota of inodes was exhausted. (POSIX.1)
- const EEXIST: err_t¶
File exists. An existing file was mentioned in an inappropriate context, for instance, as the new link name in a link system call. (POSIX.1)
- const EFAULT: err_t¶
Bad address. The system detected an invalid address in attempting to use an argument of a call. (POSIX.1)
- const EFBIG: err_t¶
File too large. The size of a file exceeded the maximum. (POSIX.1)
- const EHOSTDOWN: err_t¶
Host is down. A socket operation failed because the destination host was down. (linux, FreeBSD)
- const EHOSTUNREACH: err_t¶
No route to host. A socket operation was attempted to an unreachable host. (POSIX.1)
- const EIDRM: err_t¶
Identifier removed. An IPC identifier was removed while the current process was waiting on it. (POSIX.1)
- const EILSEQ: err_t¶
Illegal byte sequence. While decoding a multibyte character the function came along an invalid or an incomplete sequence of bytes or the given wide character is invalid.
This error might be returned for example in the case of an illegal UTF-8 byte sequence. (POSIX.1, C99)
- const EINPROGRESS: err_t¶
Operation now in progress. An operation that takes a long time to complete (such as a connect system call) was attempted on a non-blocking object. (POSIX.1)
- const EINTR: err_t¶
Interrupted system call. An asynchronous signal (such as SIGINT or SIGQUIT) was caught by the process during the execution of an interruptible function. If the signal handler performs a normal return, the interrupted system call will seem to have returned the error condition. (POSIX.1)
- const EINVAL: err_t¶
Invalid argument. Some invalid argument was supplied. (For example, specifying an undefined signal to a signal system call or a kill system call). (POSIX.1)
- const EIO: err_t¶
Input/output error. Some physical input or output error occurred. This error will not be reported until a subsequent operation on the same file descriptor and may be lost (over written) by any subsequent errors. (POSIX.1)
- const EISCONN: err_t¶
Socket is already connected. A connect system call was made on an already connected socket; or, a sendto or sendmsg system call on a connected socket specified a destination when already connected. (POSIX.1)
- const EISDIR: err_t¶
Is a directory. An attempt was made to open a directory with write mode specified. (POSIX.1)
- const EISNAM: err_t¶
Is a named type file (linux only)
- const EKEYEXPIRED: err_t¶
Key has expired (linux only)
- const EKEYREJECTED: err_t¶
Key was rejected by service (linux only)
- const EKEYREVOKED: err_t¶
Key has been revoked (linux only)
- const EL2HLT: err_t¶
Level 2 halted (linux only)
- const EL2NSYNC: err_t¶
Level 2 not synchronized (linux only)
- const EL3HLT: err_t¶
Level 3 halted (linux only)
- const EL3RST: err_t¶
Level 3 halted (linux only)
- const ELIBACC: err_t¶
Cannot access a needed shared library (linux only)
- const ELIBBAD: err_t¶
Accessing a corrupted shared library (linux only)
- const ELIBMAX: err_t¶
Attempting to link in too many shared libraries (linux only)
- const ELIBSCN: err_t¶
lib section in a.out corrupted (linux only)
- const ELIBEXEC: err_t¶
Cannot exec a shared library directly (linux only)
- const ELOOP: err_t¶
Too many levels of symbolic links. A path name lookup involved more than 32 (MAXSYMLINKS) symbolic links. (POSIX.1)
- const EMEDIUMTYPE: err_t¶
Wrong medium type (linux only)
- const EMFILE: err_t¶
Too many open files. Maximum number of file descriptors allowable in the process has been reached and requests for an open cannot be satisfied until at least one has been closed. The getdtablesize system call will obtain the current limit. (POSIX.1)
- const EMLINK: err_t¶
Too many links. Maximum allowable hard links to a single file has been exceeded. (POSIX.1)
- const EMSGSIZE: err_t¶
Message too long. A message sent on a socket was larger than the internal message buffer or some other network limit. (POSIX.1)
- const EMULTIHOP: err_t¶
Multihop attempted. (POSIX.1)
- const ENAMETOOLONG: err_t¶
File name too long. A component of a path name exceeded {NAME_MAX} characters, or an entire path name exceeded {PATH_MAX} characters. (POSIX.1)
- const ENETDOWN: err_t¶
Network is down. A socket operation encountered a dead network. (POSIX.1)
- const ENETRESET: err_t¶
Network dropped connection on reset. The host you were connected to crashed and rebooted. (POSIX.1)
- const ENETUNREACH: err_t¶
Network is unreachable. A socket operation was attempted to an unreachable network. (POSIX.1)
- const ENFILE: err_t¶
Too many open files in system. Maximum number of open files allowable on the system has been reached and requests for an open cannot be satisfied until at least one has been closed. (POSIX.1)
- const ENOBUFS: err_t¶
No buffer space available. An operation on a socket or pipe was not performed because the system lacked sufficient buffer space or because a queue was full. (POSIX.1 XSI STREAMS option)
- const ENODATA: err_t¶
No message is available on the STREAM head read queue (POSIX.1)
- const ENODEV: err_t¶
Operation not supported by device. An attempt was made to apply an inappropriate function to a device, for example, trying to read a write-only device such as a printer. (POSIX.1)
- const ENOENT: err_t¶
No such file or directory. A component of a specified pathname did not exist, or the pathname was an empty string. (POSIX.1)
- const ENOEXEC: err_t¶
Exec format error. A request was made to execute a file that, although it has the appropriate permissions, was not in the format required for an executable file. (POSIX.1)
- const ENOKEY: err_t¶
Required key not available (linux only)
- const ENOLCK: err_t¶
No locks available. A system-imposed limit on the number of simultaneous file locks was reached. (POSIX.1)
- const ENOLINK: err_t¶
Link has been severed. (POSIX.1)
- const ENOMEDIUM: err_t¶
No medium found (linux only)
- const ENOMEM: err_t¶
Cannot allocate memory. The new process image required more memory than was allowed by the hardware or by system-imposed memory management constraints. A lack of swap space is normally temporary; however, a lack of core is not. Soft limits may be increased to their corresponding hard limits. (POSIX.1)
- const ENOMSG: err_t¶
No message of desired type. An IPC message queue does not contain a message of the desired type, or a message catalog does not contain the requested message. (POSIX.1)
- const ENONET: err_t¶
Machine is not on the network (linux only)
- const ENOPKG: err_t¶
Package not installed (linux only)
- const ENOPROTOOPT: err_t¶
Protocol not available. A bad option or level was specified in a getsockopt or setsockopt system call. (POSIX.1)
- const ENOSPC: err_t¶
No space left on device. A write system call to an ordinary file, the creation of a directory or symbolic link, or the creation of a directory entry failed because no more disk blocks were available on the file system, or the allocation of an inode for a newly created file failed because no more inodes were available on the file system. (POSIX.1)
- const ENOSR: err_t¶
No STREAM resources (POSIX.1 XSI STREAMS option)
- const ENOSTR: err_t¶
Not a STREAM (POSIX.1 XSI STREAMS option)
- const ENOSYS: err_t¶
Function not implemented. Attempted a system call that is not available on this system. (POSIX.1)
- const ENOTBLK: err_t¶
Block device required. A block device operation was attempted on a non-block device or file. (linux, FreeBSD)
- const ENOTCONN: err_t¶
Socket is not connected. An request to send or receive data was disallowed because the socket was not connected and (when sending on a datagram socket) no address was supplied. (POSIX.1)
- const ENOTDIR: err_t¶
Not a directory. A component of the specified pathname existed, but it was not a directory, when a directory was expected. (POSIX.1)
- const ENOTEMPTY: err_t¶
Directory not empty. A directory with entries other than ‘.’ and ‘..’ was supplied to a remove directory or rename call. (POSIX.1)
- const ENOTSOCK: err_t¶
Socket operation on non-socket. (POSIX.1)
- const ENOTSUP: err_t¶
Operation not supported. The attempted operation is not supported for the type of object referenced. Usually this occurs when a file descriptor refers to a file or socket that cannot support this operation, for example, trying to accept a connection on a datagram socket. (POSIX.1)
- const ENOTTY: err_t¶
Inappropriate ioctl for device. A control function (e.g. ioctl system call) was attempted for a file or special device for which the operation was inappropriate. (POSIX.1)
- const ENOTUNIQ: err_t¶
Name not unique on network (linux only)
- const ENXIO: err_t¶
Device not configured. Input or output on a special file referred to a device that did not exist, or made a request beyond the limits of the device. This error may also occur when, for example, a tape drive is not online or no disk pack is loaded on a drive. (POSIX.1)
- const EOPNOTSUPP: err_t¶
Operation not supported. The attempted operation is not supported for the type of object referenced. Usually this occurs when a file descriptor refers to a file or socket that cannot support this operation, for example, trying to accept a connection on a datagram socket. (POSIX.1)
- const EOVERFLOW: err_t¶
Value too large to be stored in data type. A numerical result of the function was too large to be stored in the caller provided space. (POSIX.1)
- const EPERM: err_t¶
Operation not permitted. An attempt was made to perform an operation limited to processes with appropriate privileges or to the owner of a file or other resources. (POSIX.1)
- const EPFNOSUPPORT: err_t¶
Protocol family not supported. The protocol family has not been configured into the system or no implementation for it exists. (linux, FreeBSD)
- const EPIPE: err_t¶
Broken pipe. A write on a pipe, socket or FIFO for which there is no process to read the data. (POSIX.1)
- const EPROTO: err_t¶
Protocol error. A device or socket encountered an unrecoverable protocol error. (POSIX.1)
- const EPROTONOSUPPORT: err_t¶
Protocol not supported. The protocol has not been configured into the system or no implementation for it exists. (POSIX.1)
- const EPROTOTYPE: err_t¶
Protocol wrong type for socket. A protocol was specified that does not sup- port the semantics of the socket type requested. For example, you cannot use the ARPA Internet UDP protocol with type SOCK_STREAM. (POSIX.1)
- const ERANGE: err_t¶
Result too large. A numerical result of the function was too large to fit in the available space (perhaps exceeded precision). (POSIX.1, C99)
- const EREMCHG: err_t¶
Remote address changed (linux only)
- const EREMOTE: err_t¶
Object is remote (linux only)
- const EREMOTEIO: err_t¶
Remote I/O error (linux only)
- const ERESTART: err_t¶
Interrupted system call should be restarted (linux only)
- const EROFS: err_t¶
Read-only file system. An attempt was made to modify a file or directory on a file system that was read-only at the time. (POSIX.1)
- const ESHUTDOWN: err_t¶
Can’t send after socket shutdown. A request to send data was disallowed because the socket had already been shut down with a previous shutdown system call.
- const ESPIPE: err_t¶
Illegal seek. An lseek system call was issued on a socket, pipe or FIFO. (POSIX.1)
- const ESOCKTNOSUPPORT: err_t¶
Socket type not supported. The support for the socket type has not been configured into the system or no implementation for it exists. (linux, FreeBSD)
- const ESRCH: err_t¶
No such process. No process could be found corresponding to that specified by the given process ID. (POSIX.1)
- const ESTALE: err_t¶
Stale NFS file handle. An attempt was made to access an open file (on an NFS file system) which is now unavailable as referenced by the file descriptor. This may indicate the file was deleted on the NFS server or some other catastrophic event occurred. (POSIX.1)
- const ESTRPIPE: err_t¶
Streams pipe error (linux only)
- const ETIME: err_t¶
Timer expired (POSIX.1 XSI STREAMS option)
- const ETIMEDOUT: err_t¶
Operation timed out. A connect or send system call failed because the connected party did not properly respond after a period of time. (The timeout period is dependent on the communication protocol.) (POSIX.1)
- const ETXTBSY: err_t¶
Text file busy. The new process was a pure procedure (shared text) file which was open for writing by another process, or while the pure procedure file was being executed an open system call requested write access. (POSIX.1)
- const EUCLEAN: err_t¶
Structure needs cleaning (linux only)
- const EUNATCH: err_t¶
Protocol driver not attached (linux only)
- const EUSERS: err_t¶
Too many users. The quota system ran out of table entries. (linux, FreeBSD)
- const EWOULDBLOCK: err_t¶
Operation would block (may be same value as EAGAIN) (POSIX.1)
- const EXDEV: err_t¶
Cross-device link. A hard link to a file on another file system was attempted. (POSIX.1)
- const EXFULL: err_t¶
Exchange full (linux only)