1UnixLabels(3) OCaml library UnixLabels(3)
2
6 UnixLabels - Interface to the Unix system.
7
9 Module UnixLabels
10
12 Module UnixLabels
13 : sig end
14 Interface to the Unix system.
17 To use the labeled version of this module, add module Unix = UnixLabels
19 in your implementation.
20 Note: all the functions of this module (except UnixLabels.error_message
22 and UnixLabels.handle_unix_error ) are liable to raise the UnixLa‐
23 bels.Unix_error exception whenever the underlying system call signals
24 an error.
25 Error report
33 type error = Unix.error =
34 | E2BIG (* Argument list too long
35 *)
36 | EACCES (* Permission denied
37 *)
38 | EAGAIN (* Resource temporarily unavailable; try again
39 *)
40 | EBADF (* Bad file descriptor
41 *)
42 | EBUSY (* Resource unavailable
43 *)
44 | ECHILD (* No child process
45 *)
46 | EDEADLK (* Resource deadlock would occur
47 *)
48 | EDOM (* Domain error for math functions, etc.
49 *)
50 | EEXIST (* File exists
51 *)
52 | EFAULT (* Bad address
53 *)
54 | EFBIG (* File too large
55 *)
56 | EINTR (* Function interrupted by signal
57 *)
58 | EINVAL (* Invalid argument
59 *)
60 | EIO (* Hardware I/O error
61 *)
62 | EISDIR (* Is a directory
63 *)
64 | EMFILE (* Too many open files by the process
65 *)
66 | EMLINK (* Too many links
67 *)
68 | ENAMETOOLONG (* Filename too long
69 *)
70 | ENFILE (* Too many open files in the system
71 *)
72 | ENODEV (* No such device
73 *)
74 | ENOENT (* No such file or directory
75 *)
76 | ENOEXEC (* Not an executable file
77 *)
78 | ENOLCK (* No locks available
79 *)
80 | ENOMEM (* Not enough memory
81 *)
82 | ENOSPC (* No space left on device
83 *)
84 | ENOSYS (* Function not supported
85 *)
86 | ENOTDIR (* Not a directory
87 *)
88 | ENOTEMPTY (* Directory not empty
89 *)
90 | ENOTTY (* Inappropriate I/O control operation
91 *)
92 | ENXIO (* No such device or address
93 *)
94 | EPERM (* Operation not permitted
95 *)
96 | EPIPE (* Broken pipe
97 *)
98 | ERANGE (* Result too large
99 *)
100 | EROFS (* Read-only file system
101 *)
102 | ESPIPE (* Invalid seek e.g. on a pipe
103 *)
104 | ESRCH (* No such process
105 *)
106 | EXDEV (* Invalid link
107 *)
108 | EWOULDBLOCK (* Operation would block
109 *)
110 | EINPROGRESS (* Operation now in progress
111 *)
112 | EALREADY (* Operation already in progress
113 *)
114 | ENOTSOCK (* Socket operation on non-socket
115 *)
116 | EDESTADDRREQ (* Destination address required
117 *)
118 | EMSGSIZE (* Message too long
119 *)
120 | EPROTOTYPE (* Protocol wrong type for socket
121 *)
122 | ENOPROTOOPT (* Protocol not available
123 *)
124 | EPROTONOSUPPORT (* Protocol not supported
125 *)
126 | ESOCKTNOSUPPORT (* Socket type not supported
127 *)
128 | EOPNOTSUPP (* Operation not supported on socket
129 *)
130 | EPFNOSUPPORT (* Protocol family not supported
131 *)
132 | EAFNOSUPPORT (* Address family not supported by protocol family
133 *)
134 | EADDRINUSE (* Address already in use
135 *)
136 | EADDRNOTAVAIL (* Can't assign requested address
137 *)
138 | ENETDOWN (* Network is down
139 *)
140 | ENETUNREACH (* Network is unreachable
141 *)
142 | ENETRESET (* Network dropped connection on reset
143 *)
144 | ECONNABORTED (* Software caused connection abort
145 *)
146 | ECONNRESET (* Connection reset by peer
147 *)
148 | ENOBUFS (* No buffer space available
149 *)
150 | EISCONN (* Socket is already connected
151 *)
152 | ENOTCONN (* Socket is not connected
153 *)
154 | ESHUTDOWN (* Can't send after socket shutdown
155 *)
156 | ETOOMANYREFS (* Too many references: can't splice
157 *)
158 | ETIMEDOUT (* Connection timed out
159 *)
160 | ECONNREFUSED (* Connection refused
161 *)
162 | EHOSTDOWN (* Host is down
163 *)
164 | EHOSTUNREACH (* No route to host
165 *)
166 | ELOOP (* Too many levels of symbolic links
167 *)
168 | EOVERFLOW (* File size or position not representable
169 *)
170 | EUNKNOWNERR of int
171 (* Unknown error
172 *)
173 The type of error codes. Errors defined in the POSIX standard and ad‐
176 ditional errors from UNIX98 and BSD. All other errors are mapped to
177 EUNKNOWNERR.
178 exception Unix_error of error * string * string
182 Raised by the system calls below when an error is encountered. The
185 first component is the error code; the second component is the function
186 name; the third component is the string parameter to the function, if
187 it has one, or the empty string otherwise.
188 UnixLabels.Unix_error and Unix.Unix_error are the same, and catching
191 one will catch the other.
192 val error_message : error -> string
196 Return a string describing the given error code.
198 val handle_unix_error : ('a -> 'b) -> 'a -> 'b
202 handle_unix_error f x applies f to x and returns the result. If the
205 exception UnixLabels.Unix_error is raised, it prints a message describ‐
206 ing the error and exits with code 2.
207 Access to the process environment
212 val environment : unit -> string array
213 Return the process environment, as an array of strings with the format
215 ``variable=value''. The returned array is empty if the process has
216 special privileges.
217 val unsafe_environment : unit -> string array
221 Return the process environment, as an array of strings with the format
223 ``variable=value''. Unlike UnixLabels.environment , this function re‐
224 turns a populated array even if the process has special privileges.
225 See the documentation for UnixLabels.unsafe_getenv for more details.
226 Since 4.12.0
229 val getenv : string -> string
233 Return the value associated to a variable in the process environment,
235 unless the process has special privileges.
236 Raises Not_found if the variable is unbound or the process has special
239 privileges.
240 This function is identical to Sys.getenv .
242 val unsafe_getenv : string -> string
246 Return the value associated to a variable in the process environment.
248 Unlike UnixLabels.getenv , this function returns the value even if the
250 process has special privileges. It is considered unsafe because the
251 programmer of a setuid or setgid program must be careful to avoid using
252 maliciously crafted environment variables in the search path for exe‐
253 cutables, the locations for temporary files or logs, and the like.
254 Since 4.06.0
257 Raises Not_found if the variable is unbound.
260 val putenv : string -> string -> unit
264 putenv name value sets the value associated to a variable in the
267 process environment. name is the name of the environment variable, and
268 value its new associated value.
269 Process handling
274 type process_status = Unix.process_status =
275 | WEXITED of int
276 (* The process terminated normally by exit ; the argument is the re‐
277 turn code.
278 *)
279 | WSIGNALED of int
280 (* The process was killed by a signal; the argument is the signal
281 number.
282 *)
283 | WSTOPPED of int
284 (* The process was stopped by a signal; the argument is the signal
285 number.
286 *)
287 The termination status of a process. See module Sys for the defini‐
290 tions of the standard signal numbers. Note that they are not the num‐
291 bers used by the OS.
292 type wait_flag = Unix.wait_flag =
295 | WNOHANG (* Do not block if no child has died yet, but immediately
296 return with a pid equal to 0.
297 *)
298 | WUNTRACED (* Report also the children that receive stop signals.
299 *)
300 Flags for UnixLabels.waitpid .
303 val execv : prog:string -> args:string array -> 'a
307 execv ~prog ~args execute the program in file prog , with the arguments
310 args , and the current process environment. These execv* functions
311 never return: on success, the current program is replaced by the new
312 one.
313 Raises Unix_error on failure
316 val execve : prog:string -> args:string array -> env:string array -> 'a
320 Same as UnixLabels.execv , except that the third argument provides the
322 environment to the program executed.
323 val execvp : prog:string -> args:string array -> 'a
327 Same as UnixLabels.execv , except that the program is searched in the
329 path.
330 val execvpe : prog:string -> args:string array -> env:string array ->
334 'a
335 Same as UnixLabels.execve , except that the program is searched in the
337 path.
338 val fork : unit -> int
342 Fork a new process. The returned integer is 0 for the child process,
344 the pid of the child process for the parent process.
345 On Windows: not implemented, use UnixLabels.create_process or threads.
347 val wait : unit -> int * process_status
351 Wait until one of the children processes die, and return its pid and
353 termination status.
354 On Windows: not implemented, use UnixLabels.waitpid .
356 val waitpid : mode:wait_flag list -> int -> int * process_status
360 Same as UnixLabels.wait , but waits for the child process whose pid is
362 given. A pid of -1 means wait for any child. A pid of 0 means wait
363 for any child in the same process group as the current process. Nega‐
364 tive pid arguments represent process groups. The list of options indi‐
365 cates whether waitpid should return immediately without waiting, and
366 whether it should report stopped children.
367 On Windows: can only wait for a given PID, not any child process.
369 val system : string -> process_status
373 Execute the given command, wait until it terminates, and return its
375 termination status. The string is interpreted by the shell /bin/sh (or
376 the command interpreter cmd.exe on Windows) and therefore can contain
377 redirections, quotes, variables, etc. To properly quote whitespace and
378 shell special characters occurring in file names or command arguments,
379 the use of Filename.quote_command is recommended. The result WEXITED
380 127 indicates that the shell couldn't be executed.
381 val _exit : int -> 'a
385 Terminate the calling process immediately, returning the given status
387 code to the operating system: usually 0 to indicate no errors, and a
388 small positive integer to indicate failure. Unlike exit , Unix._exit
389 performs no finalization whatsoever: functions registered with at_exit
390 are not called, input/output channels are not flushed, and the C
391 run-time system is not finalized either.
392 The typical use of Unix._exit is after a Unix.fork operation, when the
394 child process runs into a fatal error and must exit. In this case, it
395 is preferable to not perform any finalization action in the child
396 process, as these actions could interfere with similar actions per‐
397 formed by the parent process. For example, output channels should not
398 be flushed by the child process, as the parent process may flush them
399 again later, resulting in duplicate output.
400 Since 4.12.0
403 val getpid : unit -> int
407 Return the pid of the process.
409 val getppid : unit -> int
413 Return the pid of the parent process.
415 On Windows: not implemented (because it is meaningless).
417 val nice : int -> int
421 Change the process priority. The integer argument is added to the
423 ``nice'' value. (Higher values of the ``nice'' value mean lower priori‐
424 ties.) Return the new nice value.
425 On Windows: not implemented.
427 Basic file input/output
432 type file_descr = Unix.file_descr
433 The abstract type of file descriptors.
436 val stdin : file_descr
440 File descriptor for standard input.
442 val stdout : file_descr
446 File descriptor for standard output.
448 val stderr : file_descr
452 File descriptor for standard error.
454 type open_flag = Unix.open_flag =
457 | O_RDONLY (* Open for reading
458 *)
459 | O_WRONLY (* Open for writing
460 *)
461 | O_RDWR (* Open for reading and writing
462 *)
463 | O_NONBLOCK (* Open in non-blocking mode
464 *)
465 | O_APPEND (* Open for append
466 *)
467 | O_CREAT (* Create if nonexistent
468 *)
469 | O_TRUNC (* Truncate to 0 length if existing
470 *)
471 | O_EXCL (* Fail if existing
472 *)
473 | O_NOCTTY (* Don't make this dev a controlling tty
474 *)
475 | O_DSYNC (* Writes complete as `Synchronised I/O data integrity com‐
476 pletion'
477 *)
478 | O_SYNC (* Writes complete as `Synchronised I/O file integrity com‐
479 pletion'
480 *)
481 | O_RSYNC (* Reads complete as writes (depending on O_SYNC/O_DSYNC)
482 *)
483 | O_SHARE_DELETE (* Windows only: allow the file to be deleted while
484 still open
485 *)
486 | O_CLOEXEC (* Set the close-on-exec flag on the descriptor returned
487 by UnixLabels.openfile . See UnixLabels.set_close_on_exec for more in‐
488 formation.
489 *)
490 | O_KEEPEXEC (* Clear the close-on-exec flag. This is currently the
491 default.
492 *)
493 The flags to UnixLabels.openfile .
496 type file_perm = int
499 The type of file access rights, e.g. 0o640 is read and write for user,
502 read for group, none for others
503 val openfile : string -> mode:open_flag list -> perm:file_perm ->
507 file_descr
508 Open the named file with the given flags. Third argument is the permis‐
510 sions to give to the file if it is created (see UnixLabels.umask ). Re‐
511 turn a file descriptor on the named file.
512 val close : file_descr -> unit
516 Close a file descriptor.
518 val fsync : file_descr -> unit
522 Flush file buffers to disk.
524 Since 4.12.0
527 val read : file_descr -> buf:bytes -> pos:int -> len:int -> int
531 read fd ~buf ~pos ~len reads len bytes from descriptor fd , storing
534 them in byte sequence buf , starting at position pos in buf . Return
535 the number of bytes actually read.
536 val write : file_descr -> buf:bytes -> pos:int -> len:int -> int
540 write fd ~buf ~pos ~len writes len bytes to descriptor fd , taking them
543 from byte sequence buf , starting at position pos in buff . Return the
544 number of bytes actually written. write repeats the writing operation
545 until all bytes have been written or an error occurs.
546 val single_write : file_descr -> buf:bytes -> pos:int -> len:int -> int
550 Same as UnixLabels.write , but attempts to write only once. Thus, if
552 an error occurs, single_write guarantees that no data has been written.
553 val write_substring : file_descr -> buf:string -> pos:int -> len:int ->
557 int
558 Same as UnixLabels.write , but take the data from a string instead of a
560 byte sequence.
561 Since 4.02.0
564 val single_write_substring : file_descr -> buf:string -> pos:int ->
568 len:int -> int
569 Same as UnixLabels.single_write , but take the data from a string in‐
571 stead of a byte sequence.
572 Since 4.02.0
575 Interfacing with the standard input/output library
580 val in_channel_of_descr : file_descr -> in_channel
581 Create an input channel reading from the given descriptor. The channel
583 is initially in binary mode; use set_binary_mode_in ic false if text
584 mode is desired. Text mode is supported only if the descriptor refers
585 to a file or pipe, but is not supported if it refers to a socket.
586 On Windows: set_binary_mode_in always fails on channels created with
588 this function.
589 Beware that channels are buffered so more characters may have been read
591 from the file descriptor than those accessed using channel functions.
592 Channels also keep a copy of the current position in the file.
593 You need to explicitly close all channels created with this function.
595 Closing the channel also closes the underlying file descriptor (unless
596 it was already closed).
597 val out_channel_of_descr : file_descr -> out_channel
601 Create an output channel writing on the given descriptor. The channel
603 is initially in binary mode; use set_binary_mode_out oc false if text
604 mode is desired. Text mode is supported only if the descriptor refers
605 to a file or pipe, but is not supported if it refers to a socket.
606 On Windows: set_binary_mode_out always fails on channels created with
608 this function.
609 Beware that channels are buffered so you may have to flush them to en‐
611 sure that all data has been sent to the file descriptor. Channels also
612 keep a copy of the current position in the file.
613 You need to explicitly close all channels created with this function.
615 Closing the channel flushes the data and closes the underlying file de‐
616 scriptor (unless it has already been closed, in which case the buffered
617 data is lost).
618 val descr_of_in_channel : in_channel -> file_descr
622 Return the descriptor corresponding to an input channel.
624 val descr_of_out_channel : out_channel -> file_descr
628 Return the descriptor corresponding to an output channel.
630 Seeking and truncating
635 type seek_command = Unix.seek_command =
636 | SEEK_SET (* indicates positions relative to the beginning of the
637 file
638 *)
639 | SEEK_CUR (* indicates positions relative to the current position
640 *)
641 | SEEK_END (* indicates positions relative to the end of the file
642 *)
643 Positioning modes for UnixLabels.lseek .
646 val lseek : file_descr -> int -> mode:seek_command -> int
650 Set the current position for a file descriptor, and return the result‐
652 ing offset (from the beginning of the file).
653 val truncate : string -> len:int -> unit
657 Truncates the named file to the given size.
659 val ftruncate : file_descr -> len:int -> unit
663 Truncates the file corresponding to the given descriptor to the given
665 size.
666 File status
671 type file_kind = Unix.file_kind =
672 | S_REG (* Regular file
673 *)
674 | S_DIR (* Directory
675 *)
676 | S_CHR (* Character device
677 *)
678 | S_BLK (* Block device
679 *)
680 | S_LNK (* Symbolic link
681 *)
682 | S_FIFO (* Named pipe
683 *)
684 | S_SOCK (* Socket
685 *)
686 type stats = Unix.stats = {
691 st_dev : int ; (* Device number
692 *)
693 st_ino : int ; (* Inode number
694 *)
695 st_kind : file_kind ; (* Kind of the file
696 *)
697 st_perm : file_perm ; (* Access rights
698 *)
699 st_nlink : int ; (* Number of links
700 *)
701 st_uid : int ; (* User id of the owner
702 *)
703 st_gid : int ; (* Group ID of the file's group
704 *)
705 st_rdev : int ; (* Device ID (if special file)
706 *)
707 st_size : int ; (* Size in bytes
708 *)
709 st_atime : float ; (* Last access time
710 *)
711 st_mtime : float ; (* Last modification time
712 *)
713 st_ctime : float ; (* Last status change time
714 *)
715 }
716 The information returned by the UnixLabels.stat calls.
719 val stat : string -> stats
723 Return the information for the named file.
725 val lstat : string -> stats
729 Same as UnixLabels.stat , but in case the file is a symbolic link, re‐
731 turn the information for the link itself.
732 val fstat : file_descr -> stats
736 Return the information for the file associated with the given descrip‐
738 tor.
739 val isatty : file_descr -> bool
743 Return true if the given file descriptor refers to a terminal or con‐
745 sole window, false otherwise.
746 File operations on large files
751 module LargeFile : sig end
752 File operations on large files. This sub-module provides 64-bit vari‐
755 ants of the functions UnixLabels.LargeFile.lseek (for positioning a
756 file descriptor), UnixLabels.LargeFile.truncate and UnixLabels.Large‐
757 File.ftruncate (for changing the size of a file), and UnixLabels.Large‐
758 File.stat , UnixLabels.LargeFile.lstat and UnixLabels.LargeFile.fstat
759 (for obtaining information on files). These alternate functions repre‐
760 sent positions and sizes by 64-bit integers (type int64 ) instead of
761 regular integers (type int ), thus allowing operating on files whose
762 sizes are greater than max_int .
763 Mapping files into memory
768 val map_file : file_descr -> ?pos:int64 -> kind:('a, 'b) Bigarray.kind
769 -> layout:'c Bigarray.layout -> shared:bool -> dims:int array -> ('a,
770 'b, 'c) Bigarray.Genarray.t
771 Memory mapping of a file as a Bigarray. map_file fd ~kind ~layout
773 ~shared ~dims returns a Bigarray of kind kind , layout layout , and di‐
774 mensions as specified in dims . The data contained in this Bigarray
775 are the contents of the file referred to by the file descriptor fd (as
776 opened previously with UnixLabels.openfile , for example). The op‐
777 tional pos parameter is the byte offset in the file of the data being
778 mapped; it defaults to 0 (map from the beginning of the file).
779 If shared is true , all modifications performed on the array are re‐
781 flected in the file. This requires that fd be opened with write per‐
782 missions. If shared is false , modifications performed on the array
783 are done in memory only, using copy-on-write of the modified pages; the
784 underlying file is not affected.
785 Genarray.map_file is much more efficient than reading the whole file in
788 a Bigarray, modifying that Bigarray, and writing it afterwards.
789 To adjust automatically the dimensions of the Bigarray to the actual
791 size of the file, the major dimension (that is, the first dimension for
792 an array with C layout, and the last dimension for an array with For‐
793 tran layout) can be given as -1 . Genarray.map_file then determines
794 the major dimension from the size of the file. The file must contain
795 an integral number of sub-arrays as determined by the non-major dimen‐
796 sions, otherwise Failure is raised.
797 If all dimensions of the Bigarray are given, the file size is matched
799 against the size of the Bigarray. If the file is larger than the Bi‐
800 garray, only the initial portion of the file is mapped to the Bigarray.
801 If the file is smaller than the big array, the file is automatically
802 grown to the size of the Bigarray. This requires write permissions on
803 fd .
804 Array accesses are bounds-checked, but the bounds are determined by the
806 initial call to map_file . Therefore, you should make sure no other
807 process modifies the mapped file while you're accessing it, or a SIGBUS
808 signal may be raised. This happens, for instance, if the file is
809 shrunk.
810 Invalid_argument or Failure may be raised in cases where argument vali‐
813 dation fails.
814 Since 4.06.0
817 Operations on file names
822 val unlink : string -> unit
823 Removes the named file.
825 If the named file is a directory, raises:
827 - EPERM on POSIX compliant system
829 - EISDIR on Linux >= 2.1.132
831 - EACCESS on Windows
833 val rename : src:string -> dst:string -> unit
838 rename ~src ~dst changes the name of a file from src to dst , moving it
841 between directories if needed. If dst already exists, its contents
842 will be replaced with those of src . Depending on the operating sys‐
843 tem, the metadata (permissions, owner, etc) of dst can either be pre‐
844 served or be replaced by those of src .
845 val link : ?follow:bool -> src:string -> dst:string -> unit
849 link ?follow ~src ~dst creates a hard link named dst to the file named
852 src .
853 Raises ENOSYS On Unix if ~follow:_ is requested, but linkat is unavail‐
856 able.
857 Raises ENOSYS On Windows if ~follow:false is requested.
860 File permissions and ownership
865 type access_permission = Unix.access_permission =
866 | R_OK (* Read permission
867 *)
868 | W_OK (* Write permission
869 *)
870 | X_OK (* Execution permission
871 *)
872 | F_OK (* File exists
873 *)
874 Flags for the UnixLabels.access call.
877 val chmod : string -> perm:file_perm -> unit
881 Change the permissions of the named file.
883 val fchmod : file_descr -> perm:file_perm -> unit
887 Change the permissions of an opened file.
889 On Windows: not implemented.
891 val chown : string -> uid:int -> gid:int -> unit
895 Change the owner uid and owner gid of the named file.
897 On Windows: not implemented.
899 val fchown : file_descr -> uid:int -> gid:int -> unit
903 Change the owner uid and owner gid of an opened file.
905 On Windows: not implemented.
907 val umask : int -> int
911 Set the process's file mode creation mask, and return the previous
913 mask.
914 On Windows: not implemented.
916 val access : string -> perm:access_permission list -> unit
920 Check that the process has the given permissions over the named file.
922 On Windows: execute permission X_OK cannot be tested, just tests for
924 read permission instead.
925 Raises Unix_error otherwise.
928 Operations on file descriptors
933 val dup : ?cloexec:bool -> file_descr -> file_descr
934 Return a new file descriptor referencing the same file as the given de‐
936 scriptor. See UnixLabels.set_close_on_exec for documentation on the
937 cloexec optional argument.
938 val dup2 : ?cloexec:bool -> src:file_descr -> dst:file_descr -> unit
942 dup2 ~src ~dst duplicates src to dst , closing dst if already opened.
945 See UnixLabels.set_close_on_exec for documentation on the cloexec op‐
946 tional argument.
947 val set_nonblock : file_descr -> unit
951 Set the ``non-blocking'' flag on the given descriptor. When the
953 non-blocking flag is set, reading on a descriptor on which there is
954 temporarily no data available raises the EAGAIN or EWOULDBLOCK error
955 instead of blocking; writing on a descriptor on which there is tempo‐
956 rarily no room for writing also raises EAGAIN or EWOULDBLOCK .
957 val clear_nonblock : file_descr -> unit
961 Clear the ``non-blocking'' flag on the given descriptor. See UnixLa‐
963 bels.set_nonblock .
964 val set_close_on_exec : file_descr -> unit
968 Set the ``close-on-exec'' flag on the given descriptor. A descriptor
970 with the close-on-exec flag is automatically closed when the current
971 process starts another program with one of the exec , create_process
972 and open_process functions.
973 It is often a security hole to leak file descriptors opened on, say, a
975 private file to an external program: the program, then, gets access to
976 the private file and can do bad things with it. Hence, it is highly
977 recommended to set all file descriptors ``close-on-exec'', except in
978 the very few cases where a file descriptor actually needs to be trans‐
979 mitted to another program.
980 The best way to set a file descriptor ``close-on-exec'' is to create it
982 in this state. To this end, the openfile function has O_CLOEXEC and
983 O_KEEPEXEC flags to enforce ``close-on-exec'' mode or ``keep-on-exec''
984 mode, respectively. All other operations in the Unix module that cre‐
985 ate file descriptors have an optional argument ?cloexec:bool to indi‐
986 cate whether the file descriptor should be created in ``close-on-exec''
987 mode (by writing ~cloexec:true ) or in ``keep-on-exec'' mode (by writ‐
988 ing ~cloexec:false ). For historical reasons, the default file de‐
989 scriptor creation mode is ``keep-on-exec'', if no cloexec optional ar‐
990 gument is given. This is not a safe default, hence it is highly recom‐
991 mended to pass explicit cloexec arguments to operations that create
992 file descriptors.
993 The cloexec optional arguments and the O_KEEPEXEC flag were introduced
995 in OCaml 4.05. Earlier, the common practice was to create file de‐
996 scriptors in the default, ``keep-on-exec'' mode, then call
997 set_close_on_exec on those freshly-created file descriptors. This is
998 not as safe as creating the file descriptor in ``close-on-exec'' mode
999 because, in multithreaded programs, a window of vulnerability exists
1000 between the time when the file descriptor is created and the time
1001 set_close_on_exec completes. If another thread spawns another program
1002 during this window, the descriptor will leak, as it is still in the
1003 ``keep-on-exec'' mode.
1004 Regarding the atomicity guarantees given by ~cloexec:true or by the use
1006 of the O_CLOEXEC flag: on all platforms it is guaranteed that a concur‐
1007 rently-executing Caml thread cannot leak the descriptor by starting a
1008 new process. On Linux, this guarantee extends to concurrently-execut‐
1009 ing C threads. As of Feb 2017, other operating systems lack the neces‐
1010 sary system calls and still expose a window of vulnerability during
1011 which a C thread can see the newly-created file descriptor in
1012 ``keep-on-exec'' mode.
1013 val clear_close_on_exec : file_descr -> unit
1017 Clear the ``close-on-exec'' flag on the given descriptor. See UnixLa‐
1019 bels.set_close_on_exec .
1020 Directories
1025 val mkdir : string -> perm:file_perm -> unit
1026 Create a directory with the given permissions (see UnixLabels.umask ).
1028 val rmdir : string -> unit
1032 Remove an empty directory.
1034 val chdir : string -> unit
1038 Change the process working directory.
1040 val getcwd : unit -> string
1044 Return the name of the current working directory.
1046 val chroot : string -> unit
1050 Change the process root directory.
1052 On Windows: not implemented.
1054 type dir_handle = Unix.dir_handle
1057 The type of descriptors over opened directories.
1060 val opendir : string -> dir_handle
1064 Open a descriptor on a directory
1066 val readdir : dir_handle -> string
1070 Return the next entry in a directory.
1072 Raises End_of_file when the end of the directory has been reached.
1075 val rewinddir : dir_handle -> unit
1079 Reposition the descriptor to the beginning of the directory
1081 val closedir : dir_handle -> unit
1085 Close a directory descriptor.
1087 Pipes and redirections
1092 val pipe : ?cloexec:bool -> unit -> file_descr * file_descr
1093 Create a pipe. The first component of the result is opened for reading,
1095 that's the exit to the pipe. The second component is opened for writ‐
1096 ing, that's the entrance to the pipe. See UnixLabels.set_close_on_exec
1097 for documentation on the cloexec optional argument.
1098 val mkfifo : string -> perm:file_perm -> unit
1102 Create a named pipe with the given permissions (see UnixLabels.umask ).
1104 On Windows: not implemented.
1106 High-level process and redirection management
1111 val create_process : prog:string -> args:string array -> stdin:file_de‐
1112 scr -> stdout:file_descr -> stderr:file_descr -> int
1113 create_process ~prog ~args ~stdin ~stdout ~stderr forks a new process
1116 that executes the program in file prog , with arguments args . The pid
1117 of the new process is returned immediately; the new process executes
1118 concurrently with the current process. The standard input and outputs
1119 of the new process are connected to the descriptors stdin , stdout and
1120 stderr . Passing e.g. Stdlib.stdout for stdout prevents the redirect‐
1121 ion and causes the new process to have the same standard output as the
1122 current process. The executable file prog is searched in the path.
1123 The new process has the same environment as the current process.
1124 val create_process_env : prog:string -> args:string array -> env:string
1128 array -> stdin:file_descr -> stdout:file_descr -> stderr:file_descr ->
1129 int
1130 create_process_env ~prog ~args ~env ~stdin ~stdout ~stderr works as
1133 UnixLabels.create_process , except that the extra argument env speci‐
1134 fies the environment passed to the program.
1135 val open_process_in : string -> in_channel
1139 High-level pipe and process management. This function runs the given
1141 command in parallel with the program. The standard output of the com‐
1142 mand is redirected to a pipe, which can be read via the returned input
1143 channel. The command is interpreted by the shell /bin/sh (or cmd.exe
1144 on Windows), cf. UnixLabels.system . The Filename.quote_command func‐
1145 tion can be used to quote the command and its arguments as appropriate
1146 for the shell being used. If the command does not need to be run
1147 through the shell, UnixLabels.open_process_args_in can be used as a
1148 more robust and more efficient alternative to UnixLa‐
1149 bels.open_process_in .
1150 val open_process_out : string -> out_channel
1154 Same as UnixLabels.open_process_in , but redirect the standard input of
1156 the command to a pipe. Data written to the returned output channel is
1157 sent to the standard input of the command. Warning: writes on output
1158 channels are buffered, hence be careful to call flush at the right
1159 times to ensure correct synchronization. If the command does not need
1160 to be run through the shell, UnixLabels.open_process_args_out can be
1161 used instead of UnixLabels.open_process_out .
1162 val open_process : string -> in_channel * out_channel
1166 Same as UnixLabels.open_process_out , but redirects both the standard
1168 input and standard output of the command to pipes connected to the two
1169 returned channels. The input channel is connected to the output of the
1170 command, and the output channel to the input of the command. If the
1171 command does not need to be run through the shell, UnixLa‐
1172 bels.open_process_args can be used instead of UnixLabels.open_process .
1173 val open_process_full : string -> env:string array -> in_channel *
1177 out_channel * in_channel
1178 Similar to UnixLabels.open_process , but the second argument specifies
1180 the environment passed to the command. The result is a triple of chan‐
1181 nels connected respectively to the standard output, standard input, and
1182 standard error of the command. If the command does not need to be run
1183 through the shell, UnixLabels.open_process_args_full can be used in‐
1184 stead of UnixLabels.open_process_full .
1185 val open_process_args_in : string -> string array -> in_channel
1189 High-level pipe and process management. The first argument specifies
1191 the command to run, and the second argument specifies the argument ar‐
1192 ray passed to the command. This function runs the command in parallel
1193 with the program. The standard output of the command is redirected to
1194 a pipe, which can be read via the returned input channel.
1195 Since 4.08.0
1198 val open_process_args_out : string -> string array -> out_channel
1202 Same as UnixLabels.open_process_args_in , but redirect the standard in‐
1204 put of the command to a pipe. Data written to the returned output
1205 channel is sent to the standard input of the command. Warning: writes
1206 on output channels are buffered, hence be careful to call flush at the
1207 right times to ensure correct synchronization.
1208 Since 4.08.0
1211 val open_process_args : string -> string array -> in_channel *
1215 out_channel
1216 Same as UnixLabels.open_process_args_out , but redirects both the stan‐
1218 dard input and standard output of the command to pipes connected to the
1219 two returned channels. The input channel is connected to the output of
1220 the command, and the output channel to the input of the command.
1221 Since 4.08.0
1224 val open_process_args_full : string -> string array -> string array ->
1228 in_channel * out_channel * in_channel
1229 Similar to UnixLabels.open_process_args , but the third argument speci‐
1231 fies the environment passed to the command. The result is a triple of
1232 channels connected respectively to the standard output, standard input,
1233 and standard error of the command.
1234 Since 4.08.0
1237 val process_in_pid : in_channel -> int
1241 Return the pid of a process opened via UnixLabels.open_process_in or
1243 UnixLabels.open_process_args_in .
1244 Since 4.12.0
1247 val process_out_pid : out_channel -> int
1251 Return the pid of a process opened via UnixLabels.open_process_out or
1253 UnixLabels.open_process_args_out .
1254 Since 4.12.0
1257 val process_pid : in_channel * out_channel -> int
1261 Return the pid of a process opened via UnixLabels.open_process or
1263 UnixLabels.open_process_args .
1264 Since 4.12.0
1267 val process_full_pid : in_channel * out_channel * in_channel -> int
1271 Return the pid of a process opened via UnixLabels.open_process_full or
1273 UnixLabels.open_process_args_full .
1274 Since 4.12.0
1277 val close_process_in : in_channel -> process_status
1281 Close channels opened by UnixLabels.open_process_in , wait for the as‐
1283 sociated command to terminate, and return its termination status.
1284 val close_process_out : out_channel -> process_status
1288 Close channels opened by UnixLabels.open_process_out , wait for the as‐
1290 sociated command to terminate, and return its termination status.
1291 val close_process : in_channel * out_channel -> process_status
1295 Close channels opened by UnixLabels.open_process , wait for the associ‐
1297 ated command to terminate, and return its termination status.
1298 val close_process_full : in_channel * out_channel * in_channel ->
1302 process_status
1303 Close channels opened by UnixLabels.open_process_full , wait for the
1305 associated command to terminate, and return its termination status.
1306 Symbolic links
1311 val symlink : ?to_dir:bool -> src:string -> dst:string -> unit
1312 symlink ?to_dir ~src ~dst creates the file dst as a symbolic link to
1315 the file src . On Windows, ~to_dir indicates if the symbolic link
1316 points to a directory or a file; if omitted, symlink examines src using
1317 stat and picks appropriately, if src does not exist then false is as‐
1318 sumed (for this reason, it is recommended that the ~to_dir parameter be
1319 specified in new code). On Unix, ~to_dir is ignored.
1320 Windows symbolic links are available in Windows Vista onwards. There
1322 are some important differences between Windows symlinks and their POSIX
1323 counterparts.
1324 Windows symbolic links come in two flavours: directory and regular,
1326 which designate whether the symbolic link points to a directory or a
1327 file. The type must be correct - a directory symlink which actually
1328 points to a file cannot be selected with chdir and a file symlink which
1329 actually points to a directory cannot be read or written (note that
1330 Cygwin's emulation layer ignores this distinction).
1331 When symbolic links are created to existing targets, this distinction
1333 doesn't matter and symlink will automatically create the correct kind
1334 of symbolic link. The distinction matters when a symbolic link is cre‐
1335 ated to a non-existent target.
1336 The other caveat is that by default symbolic links are a privileged op‐
1338 eration. Administrators will always need to be running elevated (or
1339 with UAC disabled) and by default normal user accounts need to be
1340 granted the SeCreateSymbolicLinkPrivilege via Local Security Policy
1341 (secpol.msc) or via Active Directory.
1342 UnixLabels.has_symlink can be used to check that a process is able to
1345 create symbolic links.
1346 val has_symlink : unit -> bool
1350 Returns true if the user is able to create symbolic links. On Windows,
1352 this indicates that the user not only has the SeCreateSymbolicLinkPriv‐
1353 ilege but is also running elevated, if necessary. On other platforms,
1354 this is simply indicates that the symlink system call is available.
1355 Since 4.03.0
1358 val readlink : string -> string
1362 Read the contents of a symbolic link.
1364 Polling
1369 val select : read:file_descr list -> write:file_descr list -> ex‐
1370 cept:file_descr list -> timeout:float -> file_descr list * file_descr
1371 list * file_descr list
1372 Wait until some input/output operations become possible on some chan‐
1374 nels. The three list arguments are, respectively, a set of descriptors
1375 to check for reading (first argument), for writing (second argument),
1376 or for exceptional conditions (third argument). The fourth argument is
1377 the maximal timeout, in seconds; a negative fourth argument means no
1378 timeout (unbounded wait). The result is composed of three sets of de‐
1379 scriptors: those ready for reading (first component), ready for writing
1380 (second component), and over which an exceptional condition is pending
1381 (third component).
1382 Locking
1387 type lock_command = Unix.lock_command =
1388 | F_ULOCK (* Unlock a region
1389 *)
1390 | F_LOCK (* Lock a region for writing, and block if already locked
1391 *)
1392 | F_TLOCK (* Lock a region for writing, or fail if already locked
1393 *)
1394 | F_TEST (* Test a region for other process locks
1395 *)
1396 | F_RLOCK (* Lock a region for reading, and block if already locked
1397 *)
1398 | F_TRLOCK (* Lock a region for reading, or fail if already locked
1399 *)
1400 Commands for UnixLabels.lockf .
1403 val lockf : file_descr -> mode:lock_command -> len:int -> unit
1407 lockf fd ~mode ~len puts a lock on a region of the file opened as fd .
1410 The region starts at the current read/write position for fd (as set by
1411 UnixLabels.lseek ), and extends len bytes forward if len is positive,
1412 len bytes backwards if len is negative, or to the end of the file if
1413 len is zero. A write lock prevents any other process from acquiring a
1414 read or write lock on the region. A read lock prevents any other
1415 process from acquiring a write lock on the region, but lets other pro‐
1416 cesses acquire read locks on it.
1417 The F_LOCK and F_TLOCK commands attempts to put a write lock on the
1419 specified region. The F_RLOCK and F_TRLOCK commands attempts to put a
1420 read lock on the specified region. If one or several locks put by an‐
1421 other process prevent the current process from acquiring the lock,
1422 F_LOCK and F_RLOCK block until these locks are removed, while F_TLOCK
1423 and F_TRLOCK fail immediately with an exception. The F_ULOCK removes
1424 whatever locks the current process has on the specified region. Fi‐
1425 nally, the F_TEST command tests whether a write lock can be acquired on
1426 the specified region, without actually putting a lock. It returns im‐
1427 mediately if successful, or fails otherwise.
1428 What happens when a process tries to lock a region of a file that is
1430 already locked by the same process depends on the OS. On POSIX-compli‐
1431 ant systems, the second lock operation succeeds and may "promote" the
1432 older lock from read lock to write lock. On Windows, the second lock
1433 operation will block or fail.
1434 Signals
1439 Note: installation of signal handlers is performed via the functions
1440 Sys.signal and Sys.set_signal .
1441 val kill : pid:int -> signal:int -> unit
1443 kill ~pid ~signal sends signal number signal to the process with id pid
1446 .
1447 On Windows: only the Sys.sigkill signal is emulated.
1449 type sigprocmask_command = Unix.sigprocmask_command =
1452 | SIG_SETMASK
1453 | SIG_BLOCK
1454 | SIG_UNBLOCK
1455 val sigprocmask : mode:sigprocmask_command -> int list -> int list
1461 sigprocmask ~mode sigs changes the set of blocked signals. If mode is
1464 SIG_SETMASK , blocked signals are set to those in the list sigs . If
1465 mode is SIG_BLOCK , the signals in sigs are added to the set of blocked
1466 signals. If mode is SIG_UNBLOCK , the signals in sigs are removed from
1467 the set of blocked signals. sigprocmask returns the set of previously
1468 blocked signals.
1469 When the systhreads version of the Thread module is loaded, this func‐
1471 tion redirects to Thread.sigmask . I.e., sigprocmask only changes the
1472 mask of the current thread.
1473 On Windows: not implemented (no inter-process signals on Windows).
1475 val sigpending : unit -> int list
1479 Return the set of blocked signals that are currently pending.
1481 On Windows: not implemented (no inter-process signals on Windows).
1483 val sigsuspend : int list -> unit
1487 sigsuspend sigs atomically sets the blocked signals to sigs and waits
1490 for a non-ignored, non-blocked signal to be delivered. On return, the
1491 blocked signals are reset to their initial value.
1492 On Windows: not implemented (no inter-process signals on Windows).
1494 val pause : unit -> unit
1498 Wait until a non-ignored, non-blocked signal is delivered.
1500 On Windows: not implemented (no inter-process signals on Windows).
1502 Time functions
1507 type process_times = Unix.process_times = {
1508 tms_utime : float ; (* User time for the process
1509 *)
1510 tms_stime : float ; (* System time for the process
1511 *)
1512 tms_cutime : float ; (* User time for the children processes
1513 *)
1514 tms_cstime : float ; (* System time for the children processes
1515 *)
1516 }
1517 The execution times (CPU times) of a process.
1520 type tm = Unix.tm = {
1523 tm_sec : int ; (* Seconds 0..60
1524 *)
1525 tm_min : int ; (* Minutes 0..59
1526 *)
1527 tm_hour : int ; (* Hours 0..23
1528 *)
1529 tm_mday : int ; (* Day of month 1..31
1530 *)
1531 tm_mon : int ; (* Month of year 0..11
1532 *)
1533 tm_year : int ; (* Year - 1900
1534 *)
1535 tm_wday : int ; (* Day of week (Sunday is 0)
1536 *)
1537 tm_yday : int ; (* Day of year 0..365
1538 *)
1539 tm_isdst : bool ; (* Daylight time savings in effect
1540 *)
1541 }
1542 The type representing wallclock time and calendar date.
1545 val time : unit -> float
1549 Return the current time since 00:00:00 GMT, Jan. 1, 1970, in seconds.
1551 val gettimeofday : unit -> float
1555 Same as UnixLabels.time , but with resolution better than 1 second.
1557 val gmtime : float -> tm
1561 Convert a time in seconds, as returned by UnixLabels.time , into a date
1563 and a time. Assumes UTC (Coordinated Universal Time), also known as
1564 GMT. To perform the inverse conversion, set the TZ environment vari‐
1565 able to "UTC", use UnixLabels.mktime , and then restore the original
1566 value of TZ.
1567 val localtime : float -> tm
1571 Convert a time in seconds, as returned by UnixLabels.time , into a date
1573 and a time. Assumes the local time zone. The function performing the
1574 inverse conversion is UnixLabels.mktime .
1575 val mktime : tm -> float * tm
1579 Convert a date and time, specified by the tm argument, into a time in
1581 seconds, as returned by UnixLabels.time . The tm_isdst , tm_wday and
1582 tm_yday fields of tm are ignored. Also return a normalized copy of the
1583 given tm record, with the tm_wday , tm_yday , and tm_isdst fields re‐
1584 computed from the other fields, and the other fields normalized (so
1585 that, e.g., 40 October is changed into 9 November). The tm argument is
1586 interpreted in the local time zone.
1587 val alarm : int -> int
1591 Schedule a SIGALRM signal after the given number of seconds.
1593 On Windows: not implemented.
1595 val sleep : int -> unit
1599 Stop execution for the given number of seconds.
1601 val sleepf : float -> unit
1605 Stop execution for the given number of seconds. Like sleep , but frac‐
1607 tions of seconds are supported.
1608 Since 4.12.0
1611 val times : unit -> process_times
1615 Return the execution times of the process.
1617 On Windows: partially implemented, will not report timings for child
1619 processes.
1620 val utimes : string -> access:float -> modif:float -> unit
1624 Set the last access time (second arg) and last modification time (third
1626 arg) for a file. Times are expressed in seconds from 00:00:00 GMT, Jan.
1627 1, 1970. If both times are 0.0 , the access and last modification
1628 times are both set to the current time.
1629 type interval_timer = Unix.interval_timer =
1632 | ITIMER_REAL (* decrements in real time, and sends the signal
1633 SIGALRM when expired.
1634 *)
1635 | ITIMER_VIRTUAL (* decrements in process virtual time, and sends
1636 SIGVTALRM when expired.
1637 *)
1638 | ITIMER_PROF (* (for profiling) decrements both when the process is
1639 running and when the system is running on behalf of the process; it
1640 sends SIGPROF when expired.
1641 *)
1642 The three kinds of interval timers.
1645 type interval_timer_status = Unix.interval_timer_status = {
1648 it_interval : float ; (* Period
1649 *)
1650 it_value : float ; (* Current value of the timer
1651 *)
1652 }
1653 The type describing the status of an interval timer
1656 val getitimer : interval_timer -> interval_timer_status
1660 Return the current status of the given interval timer.
1662 On Windows: not implemented.
1664 val setitimer : interval_timer -> interval_timer_status -> inter‐
1668 val_timer_status
1669 setitimer t s sets the interval timer t and returns its previous sta‐
1672 tus. The s argument is interpreted as follows: s.it_value , if nonzero,
1673 is the time to the next timer expiration; s.it_interval , if nonzero,
1674 specifies a value to be used in reloading it_value when the timer ex‐
1675 pires. Setting s.it_value to zero disables the timer. Setting
1676 s.it_interval to zero causes the timer to be disabled after its next
1677 expiration.
1678 On Windows: not implemented.
1680 User id, group id
1685 val getuid : unit -> int
1686 Return the user id of the user executing the process.
1688 On Windows: always returns 1 .
1690 val geteuid : unit -> int
1694 Return the effective user id under which the process runs.
1696 On Windows: always returns 1 .
1698 val setuid : int -> unit
1702 Set the real user id and effective user id for the process.
1704 On Windows: not implemented.
1706 val getgid : unit -> int
1710 Return the group id of the user executing the process.
1712 On Windows: always returns 1 .
1714 val getegid : unit -> int
1718 Return the effective group id under which the process runs.
1720 On Windows: always returns 1 .
1722 val setgid : int -> unit
1726 Set the real group id and effective group id for the process.
1728 On Windows: not implemented.
1730 val getgroups : unit -> int array
1734 Return the list of groups to which the user executing the process be‐
1736 longs.
1737 On Windows: always returns [|1|] .
1739 val setgroups : int array -> unit
1743 setgroups groups sets the supplementary group IDs for the calling
1746 process. Appropriate privileges are required.
1747 On Windows: not implemented.
1749 val initgroups : string -> int -> unit
1753 initgroups user group initializes the group access list by reading the
1756 group database /etc/group and using all groups of which user is a mem‐
1757 ber. The additional group group is also added to the list.
1758 On Windows: not implemented.
1760 type passwd_entry = Unix.passwd_entry = {
1763 pw_name : string ;
1764 pw_passwd : string ;
1765 pw_uid : int ;
1766 pw_gid : int ;
1767 pw_gecos : string ;
1768 pw_dir : string ;
1769 pw_shell : string ;
1770 }
1771 Structure of entries in the passwd database.
1774 type group_entry = Unix.group_entry = {
1777 gr_name : string ;
1778 gr_passwd : string ;
1779 gr_gid : int ;
1780 gr_mem : string array ;
1781 }
1782 Structure of entries in the groups database.
1785 val getlogin : unit -> string
1789 Return the login name of the user executing the process.
1791 val getpwnam : string -> passwd_entry
1795 Find an entry in passwd with the given name.
1797 Raises Not_found if no such entry exists, or always on Windows.
1800 val getgrnam : string -> group_entry
1804 Find an entry in group with the given name.
1806 Raises Not_found if no such entry exists, or always on Windows.
1809 val getpwuid : int -> passwd_entry
1813 Find an entry in passwd with the given user id.
1815 Raises Not_found if no such entry exists, or always on Windows.
1818 val getgrgid : int -> group_entry
1822 Find an entry in group with the given group id.
1824 Raises Not_found if no such entry exists, or always on Windows.
1827 Internet addresses
1832 type inet_addr = Unix.inet_addr
1833 The abstract type of Internet addresses.
1836 val inet_addr_of_string : string -> inet_addr
1840 Conversion from the printable representation of an Internet address to
1842 its internal representation. The argument string consists of 4 numbers
1843 separated by periods ( XXX.YYY.ZZZ.TTT ) for IPv4 addresses, and up to
1844 8 numbers separated by colons for IPv6 addresses.
1845 Raises Failure when given a string that does not match these formats.
1848 val string_of_inet_addr : inet_addr -> string
1852 Return the printable representation of the given Internet address. See
1854 UnixLabels.inet_addr_of_string for a description of the printable rep‐
1855 resentation.
1856 val inet_addr_any : inet_addr
1860 A special IPv4 address, for use only with bind , representing all the
1862 Internet addresses that the host machine possesses.
1863 val inet_addr_loopback : inet_addr
1867 A special IPv4 address representing the host machine ( 127.0.0.1 ).
1869 val inet6_addr_any : inet_addr
1873 A special IPv6 address, for use only with bind , representing all the
1875 Internet addresses that the host machine possesses.
1876 val inet6_addr_loopback : inet_addr
1880 A special IPv6 address representing the host machine ( ::1 ).
1882 val is_inet6_addr : inet_addr -> bool
1886 Whether the given inet_addr is an IPv6 address.
1888 Since 4.12.0
1891 Sockets
1896 type socket_domain = Unix.socket_domain =
1897 | PF_UNIX (* Unix domain
1898 *)
1899 | PF_INET (* Internet domain (IPv4)
1900 *)
1901 | PF_INET6 (* Internet domain (IPv6)
1902 *)
1903 The type of socket domains. Not all platforms support IPv6 sockets
1906 (type PF_INET6 ).
1907 On Windows: PF_UNIX not implemented.
1909 type socket_type = Unix.socket_type =
1912 | SOCK_STREAM (* Stream socket
1913 *)
1914 | SOCK_DGRAM (* Datagram socket
1915 *)
1916 | SOCK_RAW (* Raw socket
1917 *)
1918 | SOCK_SEQPACKET (* Sequenced packets socket
1919 *)
1920 The type of socket kinds, specifying the semantics of communications.
1923 SOCK_SEQPACKET is included for completeness, but is rarely supported by
1924 the OS, and needs system calls that are not available in this library.
1925 type sockaddr = Unix.sockaddr =
1928 | ADDR_UNIX of string
1929 | ADDR_INET of inet_addr * int
1930 The type of socket addresses. ADDR_UNIX name is a socket address in
1933 the Unix domain; name is a file name in the file system.
1934 ADDR_INET(addr,port) is a socket address in the Internet domain; addr
1935 is the Internet address of the machine, and port is the port number.
1936 val socket : ?cloexec:bool -> domain:socket_domain -> kind:socket_type
1940 -> protocol:int -> file_descr
1941 Create a new socket in the given domain, and with the given kind. The
1943 third argument is the protocol type; 0 selects the default protocol for
1944 that kind of sockets. See UnixLabels.set_close_on_exec for documenta‐
1945 tion on the cloexec optional argument.
1946 val domain_of_sockaddr : sockaddr -> socket_domain
1950 Return the socket domain adequate for the given socket address.
1952 val socketpair : ?cloexec:bool -> domain:socket_domain ->
1956 kind:socket_type -> protocol:int -> file_descr * file_descr
1957 Create a pair of unnamed sockets, connected together. See UnixLa‐
1959 bels.set_close_on_exec for documentation on the cloexec optional argu‐
1960 ment.
1961 val accept : ?cloexec:bool -> file_descr -> file_descr * sockaddr
1965 Accept connections on the given socket. The returned descriptor is a
1967 socket connected to the client; the returned address is the address of
1968 the connecting client. See UnixLabels.set_close_on_exec for documenta‐
1969 tion on the cloexec optional argument.
1970 val bind : file_descr -> addr:sockaddr -> unit
1974 Bind a socket to an address.
1976 val connect : file_descr -> addr:sockaddr -> unit
1980 Connect a socket to an address.
1982 val listen : file_descr -> max:int -> unit
1986 Set up a socket for receiving connection requests. The integer argument
1988 is the maximal number of pending requests.
1989 type shutdown_command = Unix.shutdown_command =
1992 | SHUTDOWN_RECEIVE (* Close for receiving
1993 *)
1994 | SHUTDOWN_SEND (* Close for sending
1995 *)
1996 | SHUTDOWN_ALL (* Close both
1997 *)
1998 The type of commands for shutdown .
2001 val shutdown : file_descr -> mode:shutdown_command -> unit
2005 Shutdown a socket connection. SHUTDOWN_SEND as second argument causes
2007 reads on the other end of the connection to return an end-of-file con‐
2008 dition. SHUTDOWN_RECEIVE causes writes on the other end of the connec‐
2009 tion to return a closed pipe condition ( SIGPIPE signal).
2010 val getsockname : file_descr -> sockaddr
2014 Return the address of the given socket.
2016 val getpeername : file_descr -> sockaddr
2020 Return the address of the host connected to the given socket.
2022 type msg_flag = Unix.msg_flag =
2025 | MSG_OOB
2026 | MSG_DONTROUTE
2027 | MSG_PEEK
2028 The flags for UnixLabels.recv , UnixLabels.recvfrom , UnixLabels.send
2031 and UnixLabels.sendto .
2032 val recv : file_descr -> buf:bytes -> pos:int -> len:int ->
2036 mode:msg_flag list -> int
2037 Receive data from a connected socket.
2039 val recvfrom : file_descr -> buf:bytes -> pos:int -> len:int ->
2043 mode:msg_flag list -> int * sockaddr
2044 Receive data from an unconnected socket.
2046 val send : file_descr -> buf:bytes -> pos:int -> len:int ->
2050 mode:msg_flag list -> int
2051 Send data over a connected socket.
2053 val send_substring : file_descr -> buf:string -> pos:int -> len:int ->
2057 mode:msg_flag list -> int
2058 Same as send , but take the data from a string instead of a byte se‐
2060 quence.
2061 Since 4.02.0
2064 val sendto : file_descr -> buf:bytes -> pos:int -> len:int ->
2068 mode:msg_flag list -> addr:sockaddr -> int
2069 Send data over an unconnected socket.
2071 val sendto_substring : file_descr -> buf:string -> pos:int -> len:int
2075 -> mode:msg_flag list -> sockaddr -> int
2076 Same as sendto , but take the data from a string instead of a byte se‐
2078 quence.
2079 Since 4.02.0
2082 Socket options
2087 type socket_bool_option = Unix.socket_bool_option =
2088 | SO_DEBUG (* Record debugging information
2089 *)
2090 | SO_BROADCAST (* Permit sending of broadcast messages
2091 *)
2092 | SO_REUSEADDR (* Allow reuse of local addresses for bind
2093 *)
2094 | SO_KEEPALIVE (* Keep connection active
2095 *)
2096 | SO_DONTROUTE (* Bypass the standard routing algorithms
2097 *)
2098 | SO_OOBINLINE (* Leave out-of-band data in line
2099 *)
2100 | SO_ACCEPTCONN (* Report whether socket listening is enabled
2101 *)
2102 | TCP_NODELAY (* Control the Nagle algorithm for TCP sockets
2103 *)
2104 | IPV6_ONLY (* Forbid binding an IPv6 socket to an IPv4 address
2105 *)
2106 | SO_REUSEPORT (* Allow reuse of address and port bindings
2107 *)
2108 The socket options that can be consulted with UnixLabels.getsockopt and
2111 modified with UnixLabels.setsockopt . These options have a boolean (
2112 true / false ) value.
2113 type socket_int_option = Unix.socket_int_option =
2116 | SO_SNDBUF (* Size of send buffer
2117 *)
2118 | SO_RCVBUF (* Size of received buffer
2119 *)
2120 | SO_ERROR (* Deprecated. Use UnixLabels.getsockopt_error instead.
2121 *)
2122 | SO_TYPE (* Report the socket type
2123 *)
2124 | SO_RCVLOWAT (* Minimum number of bytes to process for input opera‐
2125 tions
2126 *)
2127 | SO_SNDLOWAT (* Minimum number of bytes to process for output opera‐
2128 tions
2129 *)
2130 The socket options that can be consulted with UnixLabels.getsockopt_int
2133 and modified with UnixLabels.setsockopt_int . These options have an
2134 integer value.
2135 type socket_optint_option = Unix.socket_optint_option =
2138 | SO_LINGER (* Whether to linger on closed connections that have data
2139 present, and for how long (in seconds)
2140 *)
2141 The socket options that can be consulted with UnixLabels.getsock‐
2144 opt_optint and modified with UnixLabels.setsockopt_optint . These op‐
2145 tions have a value of type int option , with None meaning ``disabled''.
2146 type socket_float_option = Unix.socket_float_option =
2149 | SO_RCVTIMEO (* Timeout for input operations
2150 *)
2151 | SO_SNDTIMEO (* Timeout for output operations
2152 *)
2153 The socket options that can be consulted with UnixLabels.getsock‐
2156 opt_float and modified with UnixLabels.setsockopt_float . These op‐
2157 tions have a floating-point value representing a time in seconds. The
2158 value 0 means infinite timeout.
2159 val getsockopt : file_descr -> socket_bool_option -> bool
2163 Return the current status of a boolean-valued option in the given
2165 socket.
2166 val setsockopt : file_descr -> socket_bool_option -> bool -> unit
2170 Set or clear a boolean-valued option in the given socket.
2172 val getsockopt_int : file_descr -> socket_int_option -> int
2176 Same as UnixLabels.getsockopt for an integer-valued socket option.
2178 val setsockopt_int : file_descr -> socket_int_option -> int -> unit
2182 Same as UnixLabels.setsockopt for an integer-valued socket option.
2184 val getsockopt_optint : file_descr -> socket_optint_option -> int op‐
2188 tion
2189 Same as UnixLabels.getsockopt for a socket option whose value is an int
2191 option .
2192 val setsockopt_optint : file_descr -> socket_optint_option -> int op‐
2196 tion -> unit
2197 Same as UnixLabels.setsockopt for a socket option whose value is an int
2199 option .
2200 val getsockopt_float : file_descr -> socket_float_option -> float
2204 Same as UnixLabels.getsockopt for a socket option whose value is a
2206 floating-point number.
2207 val setsockopt_float : file_descr -> socket_float_option -> float ->
2211 unit
2212 Same as UnixLabels.setsockopt for a socket option whose value is a
2214 floating-point number.
2215 val getsockopt_error : file_descr -> error option
2219 Return the error condition associated with the given socket, and clear
2221 it.
2222 High-level network connection functions
2227 val open_connection : sockaddr -> in_channel * out_channel
2228 Connect to a server at the given address. Return a pair of buffered
2230 channels connected to the server. Remember to call flush on the output
2231 channel at the right times to ensure correct synchronization.
2232 val shutdown_connection : in_channel -> unit
2236 ``Shut down'' a connection established with UnixLabels.open_connection
2238 ; that is, transmit an end-of-file condition to the server reading on
2239 the other side of the connection. This does not fully close the file
2240 descriptor associated with the channel, which you must remember to free
2241 via close_in .
2242 val establish_server : (in_channel -> out_channel -> unit) ->
2246 addr:sockaddr -> unit
2247 Establish a server on the given address. The function given as first
2249 argument is called for each connection with two buffered channels con‐
2250 nected to the client. A new process is created for each connection. The
2251 function UnixLabels.establish_server never returns normally.
2252 On Windows: not implemented (use threads).
2254 Host and protocol databases
2259 type host_entry = Unix.host_entry = {
2260 h_name : string ;
2261 h_aliases : string array ;
2262 h_addrtype : socket_domain ;
2263 h_addr_list : inet_addr array ;
2264 }
2265 Structure of entries in the hosts database.
2268 type protocol_entry = Unix.protocol_entry = {
2271 p_name : string ;
2272 p_aliases : string array ;
2273 p_proto : int ;
2274 }
2275 Structure of entries in the protocols database.
2278 type service_entry = Unix.service_entry = {
2281 s_name : string ;
2282 s_aliases : string array ;
2283 s_port : int ;
2284 s_proto : string ;
2285 }
2286 Structure of entries in the services database.
2289 val gethostname : unit -> string
2293 Return the name of the local host.
2295 val gethostbyname : string -> host_entry
2299 Find an entry in hosts with the given name.
2301 Raises Not_found if no such entry exists.
2304 val gethostbyaddr : inet_addr -> host_entry
2308 Find an entry in hosts with the given address.
2310 Raises Not_found if no such entry exists.
2313 val getprotobyname : string -> protocol_entry
2317 Find an entry in protocols with the given name.
2319 Raises Not_found if no such entry exists.
2322 val getprotobynumber : int -> protocol_entry
2326 Find an entry in protocols with the given protocol number.
2328 Raises Not_found if no such entry exists.
2331 val getservbyname : string -> protocol:string -> service_entry
2335 Find an entry in services with the given name.
2337 Raises Not_found if no such entry exists.
2340 val getservbyport : int -> protocol:string -> service_entry
2344 Find an entry in services with the given service number.
2346 Raises Not_found if no such entry exists.
2349 type addr_info = Unix.addr_info = {
2352 ai_family : socket_domain ; (* Socket domain
2353 *)
2354 ai_socktype : socket_type ; (* Socket type
2355 *)
2356 ai_protocol : int ; (* Socket protocol number
2357 *)
2358 ai_addr : sockaddr ; (* Address
2359 *)
2360 ai_canonname : string ; (* Canonical host name
2361 *)
2362 }
2363 Address information returned by UnixLabels.getaddrinfo .
2366 type getaddrinfo_option = Unix.getaddrinfo_option =
2369 | AI_FAMILY of socket_domain
2370 (* Impose the given socket domain
2371 *)
2372 | AI_SOCKTYPE of socket_type
2373 (* Impose the given socket type
2374 *)
2375 | AI_PROTOCOL of int
2376 (* Impose the given protocol
2377 *)
2378 | AI_NUMERICHOST (* Do not call name resolver, expect numeric IP ad‐
2379 dress
2380 *)
2381 | AI_CANONNAME (* Fill the ai_canonname field of the result
2382 *)
2383 | AI_PASSIVE (* Set address to ``any'' address for use with UnixLa‐
2384 bels.bind
2385 *)
2387 Options to UnixLabels.getaddrinfo .
2390 val getaddrinfo : string -> string -> getaddrinfo_option list ->
2394 addr_info list
2395 getaddrinfo host service opts returns a list of UnixLabels.addr_info
2398 records describing socket parameters and addresses suitable for commu‐
2399 nicating with the given host and service. The empty list is returned
2400 if the host or service names are unknown, or the constraints expressed
2401 in opts cannot be satisfied.
2402 host is either a host name or the string representation of an IP ad‐
2405 dress. host can be given as the empty string; in this case, the
2406 ``any'' address or the ``loopback'' address are used, depending whether
2407 opts contains AI_PASSIVE . service is either a service name or the
2408 string representation of a port number. service can be given as the
2409 empty string; in this case, the port field of the returned addresses is
2410 set to 0. opts is a possibly empty list of options that allows the
2411 caller to force a particular socket domain (e.g. IPv6 only or IPv4
2412 only) or a particular socket type (e.g. TCP only or UDP only).
2413 type name_info = Unix.name_info = {
2416 ni_hostname : string ; (* Name or IP address of host
2417 *)
2418 ni_service : string ; (* Name of service or port number
2419 *)
2420 }
2421 Host and service information returned by UnixLabels.getnameinfo .
2424 type getnameinfo_option = Unix.getnameinfo_option =
2427 | NI_NOFQDN (* Do not qualify local host names
2428 *)
2429 | NI_NUMERICHOST (* Always return host as IP address
2430 *)
2431 | NI_NAMEREQD (* Fail if host name cannot be determined
2432 *)
2433 | NI_NUMERICSERV (* Always return service as port number
2434 *)
2435 | NI_DGRAM (* Consider the service as UDP-based instead of the de‐
2436 fault TCP
2437 *)
2438 Options to UnixLabels.getnameinfo .
2441 val getnameinfo : sockaddr -> getnameinfo_option list -> name_info
2445 getnameinfo addr opts returns the host name and service name corre‐
2448 sponding to the socket address addr . opts is a possibly empty list of
2449 options that governs how these names are obtained.
2450 Raises Not_found if an error occurs.
2453 Terminal interface
2458 The following functions implement the POSIX standard terminal inter‐
2459 face. They provide control over asynchronous communication ports and
2460 pseudo-terminals. Refer to the termios man page for a complete descrip‐
2461 tion.
2462 type terminal_io = Unix.terminal_io = {
2464 mutable c_ignbrk : bool ; (* Ignore the break condition.
2466 *)
2467 mutable c_brkint : bool ; (* Signal interrupt on break condition.
2469 *)
2470 mutable c_ignpar : bool ; (* Ignore characters with parity errors.
2472 *)
2473 mutable c_parmrk : bool ; (* Mark parity errors.
2475 *)
2476 mutable c_inpck : bool ; (* Enable parity check on input.
2478 *)
2479 mutable c_istrip : bool ; (* Strip 8th bit on input characters.
2481 *)
2482 mutable c_inlcr : bool ; (* Map NL to CR on input.
2484 *)
2485 mutable c_igncr : bool ; (* Ignore CR on input.
2487 *)
2488 mutable c_icrnl : bool ; (* Map CR to NL on input.
2490 *)
2491 mutable c_ixon : bool ; (* Recognize XON/XOFF characters on input.
2493 *)
2494 mutable c_ixoff : bool ; (* Emit XON/XOFF chars to control input flow.
2496 *)
2497 mutable c_opost : bool ; (* Enable output processing.
2499 *)
2500 mutable c_obaud : int ; (* Output baud rate (0 means close connec‐
2502 tion).
2503 *)
2504 mutable c_ibaud : int ; (* Input baud rate.
2506 *)
2507 mutable c_csize : int ; (* Number of bits per character (5-8).
2509 *)
2510 mutable c_cstopb : int ; (* Number of stop bits (1-2).
2512 *)
2513 mutable c_cread : bool ; (* Reception is enabled.
2515 *)
2516 mutable c_parenb : bool ; (* Enable parity generation and detection.
2518 *)
2519 mutable c_parodd : bool ; (* Specify odd parity instead of even.
2521 *)
2522 mutable c_hupcl : bool ; (* Hang up on last close.
2524 *)
2525 mutable c_clocal : bool ; (* Ignore modem status lines.
2527 *)
2528 mutable c_isig : bool ; (* Generate signal on INTR, QUIT, SUSP.
2530 *)
2531 mutable c_icanon : bool ; (* Enable canonical processing (line buffer‐
2533 ing and editing)
2534 *)
2535 mutable c_noflsh : bool ; (* Disable flush after INTR, QUIT, SUSP.
2537 *)
2538 mutable c_echo : bool ; (* Echo input characters.
2540 *)
2541 mutable c_echoe : bool ; (* Echo ERASE (to erase previous character).
2543 *)
2544 mutable c_echok : bool ; (* Echo KILL (to erase the current line).
2546 *)
2547 mutable c_echonl : bool ; (* Echo NL even if c_echo is not set.
2549 *)
2550 mutable c_vintr : char ; (* Interrupt character (usually ctrl-C).
2552 *)
2553 mutable c_vquit : char ; (* Quit character (usually ctrl-\).
2555 *)
2556 mutable c_verase : char ; (* Erase character (usually DEL or ctrl-H).
2558 *)
2559 mutable c_vkill : char ; (* Kill line character (usually ctrl-U).
2561 *)
2562 mutable c_veof : char ; (* End-of-file character (usually ctrl-D).
2564 *)
2565 mutable c_veol : char ; (* Alternate end-of-line char. (usually none).
2567 *)
2568 mutable c_vmin : int ; (* Minimum number of characters to read before
2570 the read request is satisfied.
2571 *)
2572 mutable c_vtime : int ; (* Maximum read wait (in 0.1s units).
2574 *)
2575 mutable c_vstart : char ; (* Start character (usually ctrl-Q).
2577 *)
2578 mutable c_vstop : char ; (* Stop character (usually ctrl-S).
2580 *)
2581 }
2582 val tcgetattr : file_descr -> terminal_io
2588 Return the status of the terminal referred to by the given file de‐
2590 scriptor.
2591 On Windows: not implemented.
2593 type setattr_when = Unix.setattr_when =
2596 | TCSANOW
2597 | TCSADRAIN
2598 | TCSAFLUSH
2599 val tcsetattr : file_descr -> mode:setattr_when -> terminal_io -> unit
2605 Set the status of the terminal referred to by the given file descrip‐
2607 tor. The second argument indicates when the status change takes place:
2608 immediately ( TCSANOW ), when all pending output has been transmitted (
2609 TCSADRAIN ), or after flushing all input that has been received but not
2610 read ( TCSAFLUSH ). TCSADRAIN is recommended when changing the output
2611 parameters; TCSAFLUSH , when changing the input parameters.
2612 On Windows: not implemented.
2614 val tcsendbreak : file_descr -> duration:int -> unit
2618 Send a break condition on the given file descriptor. The second argu‐
2620 ment is the duration of the break, in 0.1s units; 0 means standard du‐
2621 ration (0.25s).
2622 On Windows: not implemented.
2624 val tcdrain : file_descr -> unit
2628 Waits until all output written on the given file descriptor has been
2630 transmitted.
2631 On Windows: not implemented.
2633 type flush_queue = Unix.flush_queue =
2636 | TCIFLUSH
2637 | TCOFLUSH
2638 | TCIOFLUSH
2639 val tcflush : file_descr -> mode:flush_queue -> unit
2645 Discard data written on the given file descriptor but not yet transmit‐
2647 ted, or data received but not yet read, depending on the second argu‐
2648 ment: TCIFLUSH flushes data received but not read, TCOFLUSH flushes
2649 data written but not transmitted, and TCIOFLUSH flushes both.
2650 On Windows: not implemented.
2652 type flow_action = Unix.flow_action =
2655 | TCOOFF
2656 | TCOON
2657 | TCIOFF
2658 | TCION
2659 val tcflow : file_descr -> mode:flow_action -> unit
2665 Suspend or restart reception or transmission of data on the given file
2667 descriptor, depending on the second argument: TCOOFF suspends output,
2668 TCOON restarts output, TCIOFF transmits a STOP character to suspend in‐
2669 put, and TCION transmits a START character to restart input.
2670 On Windows: not implemented.
2672 val setsid : unit -> int
2676 Put the calling process in a new session and detach it from its con‐
2678 trolling terminal.
2679 On Windows: not implemented.
2681OCamldoc 2021-07-22 UnixLabels(3)